---
url: >-
  /docs/resources/references/adr/2024-12-19-offer-html-alternative-to-our-pdf-standard-document.md
---

# "\[A11y] Offer HTML alternative to our pdf standard documents"

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2024-12-19-offer-html-alternative-to-our-pdf-standard-document.md)
:::

## Context

To comply with Web Content Accessibility Guidelines (WCAG), we aim to make Shopware 6's document solution accessible (A11y-compliant). This ensures that our solution remains usable while meeting legal requirements and making documents accessible to customers with disabilities.

Currently, our PDF generation library, DomPDF, does not meet accessibility standards, posing a significant challenge.

## Decision

We have decided to make HTML documents available in addition to PDF documents, as these are more accessible.

* **Better for Accessibility**: HTML is naturally organized, making it easier for accessibility tools to read and present content to people with disabilities.

* **Lack of Support**: As our current PDFs lack support for accessibility. Few tools, especially in PHP, can create accessible tagged PDFs, making it difficult to maintain PDF accessibility.

* **Industry Trends**: Many organizations are already moving from PDFs to HTML for accessibility. For example, government websites have been required to meet accessibility standards since the early 2000s. Most of them now use HTML for most of their content because it meets these standards better.

Providing HTML documents aligns with these trends and ensures we are using best practices for accessibility.

### Affected Areas

We will integrate HTML A11y document support in the following areas:

1. **Document Type Support**:
   * Support includes all document types Shopware provides by default, `invoice`, `delivery note`, `credit note`, and `cancellation invoice`. Extensions must adapt themselves.
2. **Administration**:
   * **Order Detail Page**: Option to download HTML alongside PDF for each document type.
   * **Document Settings**: Toggle to generate HTML documents.
3. **Storefront**:
   * **Order History**: Customers can access HTML and PDF versions of documents.
4. **Flow Builder**:
   * This setup requires no additional special actions, and merchants can customize file generation for "Generate documents" in the `Document Settings`
5. **Email Delivery**:
   * Enhance the original email by including a link to the HTML document. Customers will need to log in to access the document, and additional guidance will be provided.
   * We can’t attach the HTML file directly due to issues with "virus scanners", as many email providers do not allow HTML file attachments. Instead we will provide a link inside the Email.
   * A lot of the major platforms (Microsoft, Google, Amazon, etc.) will also email a summary with a link to the customer account for things like Azure/Google Cloud/etc.

### Core concept

#### Document Template

1. **Adjust Twig Template for A11y**:

   * Modify the `html.twig` templates to support accessibility (A11y) by adding elements like `tabindex` and appropriate CSS styles.

   `src/Core/Framework/Resources/views/documents/invoice.html.twig`:

   ```twig
   {% block document_headline %}
       <h1 class="headline" tabindex="0">
           <!-- Headline content -->
       </h1>
   {% endblock %}
   ```

   `src/Core/Framework/Resources/views/documents/style_base_html.css.twig`:

   ```twig
   {% block document_style_html %}
       body {
           max-width: 1200px;
           margin: auto;
           font-size: 14px;
           line-height: 18px;
       }
       ...
   {% endblock %}
   ```

2. **Metadata and Security**:

   * The generation date of the HTML will be "fingerprinted" by adding a metadata header. This allows users to track the creation date of the document.
   * Implement a Content-Security-Policy meta-tag to minimize XSS attack risks, such as disallowing JavaScript and Restricts  to the same domain, protecting against base URL manipulation.

   Added new Twig block for metadata`src/Core/Framework/Resources/views/documents/base.html.twig`:

   ```twig
   {% block document_head_meta_protection %}
       <meta http-equiv="Content-Security-Policy" content="script-src 'none'; base-uri 'self';">
       <meta name="date" content="{{ 'now'|date('c') }}">
   {% endblock %}
   ```

#### Core

1. **Abstract Class for Multi-Format Rendering**

   * We will introduce an abstract class, `src/Core/Checkout/Document/Service/AbstractDocumentTypeRenderer`, to support rendering multiple document types, including `PDF` and `HTML`.

   ```php
   abstract class AbstractDocumentTypeRenderer
   {
       abstract public function render(RenderedDocument $document): string;
   }

   class HtmlRenderer extends AbstractDocumentTypeRenderer
   {
     public function render(RenderedDocument $document): string
     {
         $content = $this->documentTemplateRenderer->render(
             ...$options
         );
         
         $document->setContentType(self::FILE_CONTENT_TYPE);
         $document->setFileExtension(self::FILE_EXTENSION);
         $document->setContent($content);
         
         return $content;
     }
   }

   class PdfRenderer extends AbstractDocumentTypeRenderer {}
   ```

2. **Service Registration**:

   * We need to use the service tag `document_type.renderer` for the `Shopware\Core\Checkout\Document\Service\DocumentFileRendererRegistry` to recognize this service. This is essential for the proper registration and functioning of the `HtmlRenderer`.

   ```xml
   <service id="...\HtmlRenderer">
       <tag name="document_type.renderer" key="html"/>
   </service>
   ```

3. **Database Schema**:

   * We will add a new column `document_a11y_media_file_id` to the `document` table to store the media file ID for HTML A11y documents.

   ```sql
   ALTER TABLE `document`
   ADD COLUMN `document_a11y_media_file_id` BINARY(16);
   ```

   * The column is intended to link each document entry with its corresponding A11y media file `src/Core/Checkout/Document/DocumentDefinition.php`

   ```php
   (new FkField('document_a11y_media_file_id', 'documentA11yMediaFileId', MediaDefinition::class))
       ->addFlags(new ApiAware());
   ```

### Email Migration

* For templates that have been customized, new content must be migrated same as code below:

  `src/Core/Migration/Fixtures/mails/invoice_mail/de-plain.html.twig`

  ```twig
  {% if a11yDocuments %}
  For better accessibility, we also provide an HTML version of the documents here:

  {% for a11y in a11yDocuments %}
  {% set documentLink = rawUrl(
      'frontend.account.order.single.document.a11y',
      {
          documentId: a11y.documentId,
          deepLinkCode: a11y.deepLinkCode,
          fileType: a11y.fileExtension,
      },
      salesChannel.domains|first.url
  ) %}

      - {{ documentLink }}
  {% endfor %}
  {% endif %}
  ```

## Consequences

With this implementation, Shopware 6 will support HTML A11y documents alongside PDFs for standard document types. This change will have the following consequences:

* **Renderer Updates**: Document renderers need changes to handle HTML output, using the `AbstractDocumentTypeRenderer` [here](#core).
* **Email Integration**: For templates that have been customized, new content must be migrated as detailed in [here](#email-migration).
* **Improved Accessibility**: HTML documents make content easier to access for users with disabilities, aligning with WCAG standards.
* **Customizability**: Options in Document settings to enable or disable HTML documents should be added, giving merchants choice in document format.

---

---
url: >-
  /docs/v6.6/resources/references/adr/2024-12-19-offer-html-alternative-to-our-pdf-standard-document.md
---

# "\[A11y] Offer HTML alternative to our pdf standard documents"

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2024-12-19-offer-html-alternative-to-our-pdf-standard-document.md)
:::

## Context

To comply with Web Content Accessibility Guidelines (WCAG), we aim to make Shopware 6's document solution accessible (A11y-compliant). This ensures that our solution remains usable while meeting legal requirements and making documents accessible to customers with disabilities.

Currently, our PDF generation library, DomPDF, does not meet accessibility standards, posing a significant challenge.

## Decision

We have decided to make HTML documents available in addition to PDF documents, as these are more accessible.

* **Better for Accessibility**: HTML is naturally organized, making it easier for accessibility tools to read and present content to people with disabilities.

* **Lack of Support**: As our current PDFs lack support for accessibility. Few tools, especially in PHP, can create accessible tagged PDFs, making it difficult to maintain PDF accessibility.

* **Industry Trends**: Many organizations are already moving from PDFs to HTML for accessibility. For example, government websites have been required to meet accessibility standards since the early 2000s. Most of them now use HTML for most of their content because it meets these standards better.

Providing HTML documents aligns with these trends and ensures we are using best practices for accessibility.

### Affected Areas

We will integrate HTML A11y document support in the following areas:

1. **Document Type Support**:
   * Support includes all document types Shopware provides by default, `invoice`, `delivery note`, `credit note`, and `cancellation invoice`. Extensions must adapt themselves.
2. **Administration**:
   * **Order Detail Page**: Option to download HTML alongside PDF for each document type.
   * **Document Settings**: Toggle to generate HTML documents.
3. **Storefront**:
   * **Order History**: Customers can access HTML and PDF versions of documents.
4. **Flow Builder**:
   * This setup requires no additional special actions, and merchants can customize file generation for "Generate documents" in the `Document Settings`
5. **Email Delivery**:
   * Enhance the original email by including a link to the HTML document. Customers will need to log in to access the document, and additional guidance will be provided.
   * We can’t attach the HTML file directly due to issues with "virus scanners", as many email providers do not allow HTML file attachments. Instead we will provide a link inside the Email.
   * A lot of the major platforms (Microsoft, Google, Amazon, etc.) will also email a summary with a link to the customer account for things like Azure/Google Cloud/etc.

### Core concept

#### Document Template

1. **Adjust Twig Template for A11y**:

   * Modify the `html.twig` templates to support accessibility (A11y) by adding elements like `tabindex` and appropriate CSS styles.

   `src/Core/Framework/Resources/views/documents/invoice.html.twig`:

   ```twig
   {% block document_headline %}
       <h1 class="headline" tabindex="0">
           <!-- Headline content -->
       </h1>
   {% endblock %}
   ```

   `src/Core/Framework/Resources/views/documents/style_base_html.css.twig`:

   ```twig
   {% block document_style_html %}
       body {
           max-width: 1200px;
           margin: auto;
           font-size: 14px;
           line-height: 18px;
       }
       ...
   {% endblock %}
   ```

2. **Metadata and Security**:

   * The generation date of the HTML will be "fingerprinted" by adding a metadata header. This allows users to track the creation date of the document.
   * Implement a Content-Security-Policy meta-tag to minimize XSS attack risks, such as disallowing JavaScript and Restricts  to the same domain, protecting against base URL manipulation.

   Added new Twig block for metadata`src/Core/Framework/Resources/views/documents/base.html.twig`:

   ```twig
   {% block document_head_meta_protection %}
       <meta http-equiv="Content-Security-Policy" content="script-src 'none'; base-uri 'self';">
       <meta name="date" content="{{ 'now'|date('c') }}">
   {% endblock %}
   ```

#### Core

1. **Abstract Class for Multi-Format Rendering**

   * We will introduce an abstract class, `src/Core/Checkout/Document/Service/AbstractDocumentTypeRenderer`, to support rendering multiple document types, including `PDF` and `HTML`.

   ```php
   abstract class AbstractDocumentTypeRenderer
   {
       abstract public function render(RenderedDocument $document): string;
   }

   class HtmlRenderer extends AbstractDocumentTypeRenderer
   {
     public function render(RenderedDocument $document): string
     {
         $content = $this->documentTemplateRenderer->render(
             ...$options
         );
         
         $document->setContentType(self::FILE_CONTENT_TYPE);
         $document->setFileExtension(self::FILE_EXTENSION);
         $document->setContent($content);
         
         return $content;
     }
   }

   class PdfRenderer extends AbstractDocumentTypeRenderer {}
   ```

2. **Service Registration**:

   * We need to use the service tag `document_type.renderer` for the `Shopware\Core\Checkout\Document\Service\DocumentFileRendererRegistry` to recognize this service. This is essential for the proper registration and functioning of the `HtmlRenderer`.

   ```xml
   <service id="...\HtmlRenderer">
       <tag name="document_type.renderer" key="html"/>
   </service>
   ```

3. **Database Schema**:

   * We will add a new column `document_a11y_media_file_id` to the `document` table to store the media file ID for HTML A11y documents.

   ```sql
   ALTER TABLE `document`
   ADD COLUMN `document_a11y_media_file_id` BINARY(16);
   ```

   * The column is intended to link each document entry with its corresponding A11y media file `src/Core/Checkout/Document/DocumentDefinition.php`

   ```php
   (new FkField('document_a11y_media_file_id', 'documentA11yMediaFileId', MediaDefinition::class))
       ->addFlags(new ApiAware());
   ```

### Email Migration

* For templates that have been customized, new content must be migrated same as code below:

  `src/Core/Migration/Fixtures/mails/invoice_mail/de-plain.html.twig`

  ```twig
  {% if a11yDocuments %}
  For better accessibility, we also provide an HTML version of the documents here:

  {% for a11y in a11yDocuments %}
  {% set documentLink = rawUrl(
      'frontend.account.order.single.document.a11y',
      {
          documentId: a11y.documentId,
          deepLinkCode: a11y.deepLinkCode,
          fileType: a11y.fileExtension,
      },
      salesChannel.domains|first.url
  ) %}

      - {{ documentLink }}
  {% endfor %}
  {% endif %}
  ```

## Consequences

With this implementation, Shopware 6 will support HTML A11y documents alongside PDFs for standard document types. This change will have the following consequences:

* **Renderer Updates**: Document renderers need changes to handle HTML output, using the `AbstractDocumentTypeRenderer` [here](#core).
* **Email Integration**: For templates that have been customized, new content must be migrated as detailed in [here](#email-migration).
* **Improved Accessibility**: HTML documents make content easier to access for users with disabilities, aligning with WCAG standards.
* **Customizability**: Options in Document settings to enable or disable HTML documents should be added, giving merchants choice in document format.

---

---
url: /frontends/packages/composables/useAddToCart.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useAddress.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useB2bQuoteManagement.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useBreadcrumbs.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useCart.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useCartErrorParamsResolver.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useCartItem.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useCartNotification.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useCategory.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useCategorySearch.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useCheckout.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useCmsBlock.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useCmsMeta.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useCmsSection.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useCmsTranslations.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useContext.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useCountries.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useCustomerOrders.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useCustomerPassword.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useDefaultOrderAssociations.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useInternationalization.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useLandingSearch.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useListing.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useLocalWishlist.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useNavigation.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useNavigationContext.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useNavigationSearch.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useNewsletter.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useNotifications.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useOrderDetails.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useOrderPayment.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/usePrice.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useProduct.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useProductAssociations.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useProductConfigurator.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useProductPrice.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useProductReviews.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useProductSearch.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useProductSearchSuggest.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useProductWishlist.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useSalutations.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useSessionContext.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useShopwareContext.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useSyncWishlist.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useUrlResolver.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useUser.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/packages/composables/useWishlist.md
---
# {{NAME}}

{{DESCRIPTION}}

{{ADDITIONAL\_README}}

{{DEMO\_BLOCK}}

## Types

{{INTERFACE\_CONTENT}}

{{RETURN\_TYPES\_CONTENT}}

---

---
url: /frontends/resources/community-modules.md
---

# 🤗 Community Modules

:::warning
The modules listed here are not officially supported or maintained by Shopware. Please use them at your own risk.
:::

The following section contains modules, plugins and other resources that are created and maintaned by the community. If you want to contribute to this list, please create a [pull request](https://github.com/shopware/frontends/pulls) or submit a new [idea](https://github.com/shopware/frontends/discussions/categories/ideas).

---

---
url: /frontends/resources/troubleshooting.md
---

# 😱 Troubleshooting

Collection of common issues you may run into while working with Shopware Composable Frontends. If you need help or have other questions, feel free to join the [frontends Discord channel](https://discord.com/channels/1308047705309708348/1405501315160739951/archives/C050L6NCMGQ).

## Which SalesChannel type to use for Composable Frontends?

Currently you should use the default **Storefront SalesChannel type**. This sounds wrong, but if you using the Headless SalesChannel type you will not have nice speaking seo urls at the moment. Because the generation of seo urls will only be executed for SalesChannels with the type Storefront. We working on a more flexible solution with the core team to not have this confusion in the future.

## The access token for the store API is public visible?

In general, the store API should only output content that would also be visible on a standard storefront. Therefore, do not output any sensitive data to the store API. For our vue-starter-template, we decided to use a public access token, also to have a simple configuration. However, this does not mean that you should do the same in a production environment. To secure your access token, you can use [proxy api requests](#proxy-api-requests) also have a look at our [community modules](../resources/community-modules/) how others are doing this.

## How to use https for your localhost with Composable Frontends?

### Option 1: Manual with mkcert

* Make sure you have `mkcert` installed on your system. Otherwise, follow [here](https://github.com/FiloSottile/mkcert) to set it up.
* Create a valid certificate in your project folder by running `mkcert localhost`.
* Update the `nuxt dev` command in your `package.json`.\
  It should look like this: `NODE_TLS_REJECT_UNAUTHORIZED=0 nuxt dev --https --ssl-cert localhost.pem --ssl-key localhost-key.pem`
* Now run your project with `npm run dev` or `pnpm run dev` from your project root.
* Your browser may ask you to accept the risk when you visit `https://localhost:3000`. This is because it is a self-signed certificate.

### Option 2: Vite plugin

* Execute `pnpm add -D @vitejs/plugin-basic-ssl` in your project folder
* Edit your `nuxt.config.ts` file and add:
  ```ts
  import basicSsl from '@vitejs/plugin-basic-ssl'
  // https://v3.nuxtjs.org/docs/directory-structure/nuxt.config
  export default defineNuxtConfig({
  // ...
  devServer: {
    https: true,
  },
  vite: {
    plugins: [
      basicSsl(),
    ],
  },
  // ...
  ```
* Start your dev server with `pnpm run dev`
* Your browser may ask you to accept the risk when you visit `https://localhost:3000`. This is because it is a self-signed certificate.

## SSR throws error in local environment with DDEV?

If you are using DDEV as a local environment with SSR = true (Nuxt config for routes) and you always get a 500 error message that the context is not provided for category, you may have a problem with the SSL certificate. Try to use `NODE_TLS_REJECT_UNAUTHORIZED = 0` in [.env file](https://nuxt.com/docs/guide/directory-structure/env) (this is a issue with self-signed certificates). To validate if this is your problem: Connect the local Frontend with a valid SSL from a cloud instance and check it against this instance. Also check if you can reach any local store API endpoint with some API client.

## 412 error page during local development?

The HTTP status code 412 (Precondition Failed) usually means in the Shopware `store API` context that the specified `accessToken` is incorrect or not correct for the specified `endpoint`. Check your `nuxt.config.ts` file, if you do not see an error, please try connecting directly to your `store API` endpoint using an API client.

```ts
// a part of nuxt.config.ts

  shopware: {
    accessToken: "SWSCBHFSNTVMAWNZDNFKSHLAYW", // access token for corresponding sales channel
    endpoint: "https://demo-frontends.shopware.store/store-api/", // endpoint where store-api is available
    devStorefrontUrl: "https://demo-frontends.shopware.store", // see section below
  },

```

## What is `devStorefrontUrl` and when to use it?

The `devStorefrontUrl` configuration option is primarily used for **customer registration** functionality. The Shopware registration endpoint requires a `storefrontUrl` parameter in its payload to identify which sales channel domain the customer is registering from.

### Why is it needed?

By default, the application uses `window.location.origin` (e.g., `https://your-store.com`) to determine the storefront URL. However, this fails in certain scenarios:

* **Local development** - Your browser origin is `http://localhost:3000`, which doesn't match any configured sales channel domain
* **Separate frontend/API hosting** - When your frontend runs on a different domain than what's configured in Shopware

### How to configure it

Set `devStorefrontUrl` to a domain that is configured in your Shopware admin under **Sales Channel → Domains**:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  runtimeConfig: {
    public: {
      shopware: {
        endpoint: "https://your-shop.shopware.store/store-api",
        accessToken: "your-access-token",
        devStorefrontUrl: "https://your-shop.shopware.store", // must match a domain in Sales Channel settings
      },
    },
  },
});
```

Or use an environment variable:

```bash
NUXT_PUBLIC_SHOPWARE_DEV_STOREFRONT_URL=https://your-shop.shopware.store
```

:::tip
If customer registration works in production but fails locally, `devStorefrontUrl` is likely the solution. Set it to your production storefront domain during local development.
:::

## Access from origin 127.0.0.1:3000 has been blocked by CORS policy

Depending on your server, you may need to set the `Access-Control-Allow-Origin` header to access your server from an external origin. And yes, your local development server is also an external origin in this case. Also, have a look at this [documentation](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS/Errors/CORSMissingAllowOrigin) from MDN.

## Proxy API requests

If you're encountering issues related to Cross-Origin Resource Sharing (CORS) or if you wish to conceal the backend API URL, you can use Vite's proxy mechanism

### Nuxt example

Edit your `nuxt.config.ts` file and add:

```
  vite: {
    server: {
      proxy: {
        "/store-api": {
          target: "<backend url>",
          changeOrigin: true,
          secure: false,
        },
      },
    },
  },
```

Modify the Shopware API endpoint to match your local frontend URL.

```
  {
    ...
      shopware: {
          endpoint: "<frontends >store-api/",
          ...
      }
  }
```

## Broadcasting and BFCache Compatibility

### Issue

When Broadcasting is enabled, the BFCache (Back-Forward Cache) functionality is not operational. This incompatibility can lead to suboptimal performance and user experience when navigating back and forth between pages.

### Resolution (vue-demo template)

To leverage the benefits of BFCache, we have decided to disable Broadcasting. By turning off Broadcasting, we ensure that the BFCache can function correctly, providing a smoother and faster navigation experience for users.

```
...
runtimeConfig: {
  broadcasting: true,
},
...
```

### Additional Information

BFCache is a browser optimization that allows pages to be stored in memory, enabling instant loading when users navigate back or forward. While Broadcasting is useful for real-time updates, its current implementation conflicts with BFCache. Disabling Broadcasting allows us to prioritize the performance improvements offered by BFCache.

For more details on BFCache, refer to the [MDN Web Docs](https://developer.mozilla.org/en-US/docs/Web/Performance/Navigation_and_resource_timing#bfcache), [WHATWG](https://github.com/whatwg/html/issues/7253)

## CORS (Cross-Origin Resource Sharing) Issues

See the [CORS](./troubleshooting/CORS) page for more information on how to handle CORS issues in your project.

## \[unimport] failed to find "createShopwareContext" imported from "#imports"

### Problem

This error occurs when `@shopware/nuxt-module` is added to your project, but `@shopware/composables/nuxt-layer` is not extended in your Nuxt configuration.

### Why it happens

The `@shopware/nuxt-module` plugin imports `createShopwareContext` from the `#imports` alias. The `@shopware/composables/nuxt-layer` is responsible for configuring Nuxt's auto-import system and TypeScript paths to make composables exports available via `#imports`.

When you use Nuxt layers, the layer system merges TypeScript configuration files from both the composables layer and your project. This merge adds the composables exports to the `#imports` alias scope. Without extending the composables layer, these exports are not available, causing the import error.

### Solution

Extend `@shopware/composables/nuxt-layer` in your `nuxt.config.ts`:

```ts
// nuxt.config.ts
export default defineNuxtConfig({
  extends: ["@shopware/composables/nuxt-layer"],
  modules: ["@shopware/nuxt-module"],
  // ... rest of your configuration
});
```

:::tip
If you're using `@shopware/cms-base-layer`, you can extend both layers together:

```ts
extends: [
  "@shopware/composables/nuxt-layer",
  "@shopware/cms-base-layer",
  "@shopware/unocss-design-tokens-layer"
],
```

:::

### Additional Information

* The `@shopware/composables/nuxt-layer` sets up auto-imports for all composables from the `src` directory
* It also configures TypeScript path aliases (`#imports` and `#shopware`) that are required by the nuxt-module
* Always extend the composables layer when using `@shopware/nuxt-module` in your project

---

---
url: /frontends/resources/links.md
---

# 🚀 Links

::: tip Do we miss some Link? 😶‍🌫️
Please tell us via [Community Discord](https://discord.com/channels/1308047705309708348/1405501315160739951/archives/C050L6NCMGQ), so we can add it.
:::

## Blog posts

Sorted by date, newest first

* [Unofficial API aware guidelines for Shopware 6](https://www.brocksi.net/blog/unofficial-api-aware-guidelines-shopware-6/)
* [How to work with Shopware Frontends: Experience creating POC](https://itdelight.io/how-to-work-with-shopware-frontends-experience-creating-poc/)
* [Multi-Page or Single-Page Variants Selection](https://www.brocksi.net/blog/variants-selection-multi-page-or-single-page/)
* [Create a CI/CD Pipeline for Shopware Frontends](https://kiplingi.de/create-a-ci-cd-pipeline-for-shopware-frontends/)
* [Gross and Net-Switch for B2B and B2C Shops built with Composable Frontends](https://dev.to/shopware/gross-and-net-switch-for-b2b-and-b2c-shops-built-with-composable-frontends-2b24)
* [Komponentenbasierte Entwicklung mit dem Shopware Frontends Framework](https://sitegeist.de/blog/e-commerce/komponentenbasierte-entwicklung-mit-dem-shopware-frontends-framework.html)
* [Frontend API with Nuxt + Nitro = Flexibility 🐙](https://www.brocksi.net/blog/frontend-api-with-nuxt-and-nitro-will-lead-to-flexibility/)
* [Remixing the Shopware Checkout (Part 1)](https://elkmod.dev/blogs/remixing-shopware-checkout)
* [Create a vue.js composable and call any API within Shopware Frontends](https://www.brocksi.net/blog/vue-js-composable-call-api-shopware-frontends/)
* [The future of Shopware PWA](https://www.shopware.com/de/news/the-future-of-shopware-pwa/)
* [Frontends - yet another storefront?](https://www.shopware.com/en/news/frontends-yet-another-storefront/)

## Presentations

* [Quick-Start Composable Frontends - Shopware Boostday 2023](https://ecommerce.shopware.com/hubfs/Boost%20Days/Quick%20Start%20-%20Shopware%20Composable%20Frontends.pdf) (PDF)

## Videos

Sorted by date, newest first

* [Developer Brunch April 2024 - "Composable frontends"](https://www.youtube.com/watch?v=Tz-86f72cDk)
* [Going Headless - One Page Shop mit Shopware & Nuxt 🚀 | shopware x synaigy Meetup](https://www.youtube.com/watch?v=RXaNWRMuea8)
* [Performance Improvements Headless Shopware Frontends - Niklas Wolf, Mothership GmbH](https://www.youtube.com/watch?v=GhniPTMtIt8)
* [Ein Microstore mit Shopware Frontends | Shopware Meetup der Mothership GmbH in München](https://www.youtube.com/watch?v=Dal-z94WLCk)
* [Shopware Composable Frontends in Action - A real-life example with Miriam Müller](https://www.youtube.com/watch?v=AClnII3-GhQ)
* [Quick-Start Composable Frontends - Shopware Boostday 2023](https://www.youtube.com/watch?v=2AwLWvPOffw)
* [Shopware Composable Frontends: An interview. What is it, when to use it?](https://www.youtube.com/watch?v=A_O2nke4yoo)
* [Your new tool: Composable Frontends | #SCD23](https://www.youtube.com/watch?v=hN3t96zVfpw)
* [Shopware’s Vue.js framework for building custom storefronts](https://www.youtube.com/watch?v=0W_3xWIpYho)
* [Ramona Schwering - Ecommerce as easy as an UI component - Vuejs Amsterdam 2023](https://www.youtube.com/watch?v=VivLHGGds6c)
* [shopcast.fm Folge 38 - "Frontends" Revisited](https://www.youtube.com/watch?v=eW9-jrXx4wA)
* [shopcast.fm Folge 37 - Projekt Shopware "Frontends"](https://www.youtube.com/watch?v=vupiRTNoePU)

## Code examples

* [Multi sales channel support Nuxt plugin](https://github.com/shopware/frontends/tree/main/examples/multi-sales-channel)
* [Multi-Instances Repo Example for Composable Frontends](https://github.com/patzick/frontends-multiinstances-example)
* Language/Translation Switch [StackBlitz](https://stackblitz.com/github/mkucmus/language-translations?file=app.vue) / [GitHub](https://github.com/mkucmus/language-translations)

::: tip More Code examples
Check the [examples folder](https://github.com/shopware/frontends/tree/main/examples) in our Frontends Repository.
:::

---

---
url: /frontends/integrations.md
---

# 🛠️ Integrations

This is your go-to resource for seamlessly incorporating various platforms into Shopware Composable Frontends. Explore the following sub-pages to find detailed instructions on integrating different systems,
ensuring a harmonious and efficient synergy between your Shopware store and diverse external services.

## Overview

---

---
url: /docs/resources/guidelines/code/core/6.5-new-php-language-features.md
---
::: info
This document represents core guidelines and has been mirrored from the core in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/coding-guidelines/core/6.5-new-php-language-features.md)
:::

# 2023-05-16 - PHP 8.1 & Symfony 6.1 new features

## Context

As of Shopware 6.5 the minimum version of PHP is 8.1 and the minimum version of Symfony is 6.1. We would like to *promote* the usage of the newly available features.

Many of the new features allow us to reduce boilerplate, make it easier to prevent common mistakes, improve refactoring support, increase legibility, perform faster and so on.

By using the latest features we allow the reader and writer of code to focus on the domain rather than the language.

## PHP 8.0 & 8.1 new features

### Promoted Properties

* [PHP Docs](https://www.php.net/manual/en/language.oop5.decon.php#language.oop5.decon.constructor.promotion)
* [PHP Watch](https://php.watch/versions/8.0/constructor-property-promotion)

*We have automatically refactored all existing code to use Promoted Properties using Rector.*

Promoted properties allow us to reduce the boilerplate when defining classes, by removing the need to type the property name four times and the type twice.

Class properties, with their visibility and flags can now be specified entirely in the constructor.

From:

```php
class Point {
    private int $x;
    private int $y;
    public function __construct(int $x, int $y)
    {
        $this->x = $x;
        $this->y = $y;
    }
}
```

To:

```php
class Point {
    public function __construct(private int $x, private int $y)
    {
    }
}
```

Note: It is still possible to use normal property definitions/assignments with promoted properties. For example, if you need to manipulate some dependencies.

Advantages:

* Less code, less duplication.
* Better refactoring.

#### Backwards Compatibility / Migration Strategy

Migrating to promoted properties does not represent a breaking change.

### New in initializers

* [PHP Docs](https://www.php.net/manual/en/language.oop5.decon.php#language.oop5.decon.constructor.new)

It is now possible to specify an object as a default parameter value in a function/method. Previously it was only possible to specify scalar values.

From:

```php
class PasswordHasher
{
    private Hasher $hasher;
    public function __construct(private Hasher $hasher = null)
    {
        $this->hasher = $hasher ?? new Bcrypt();
    }
}
```

To:

```php
class PasswordHasher
{
    public function __construct(private Hasher $hasher = new Bcrypt())
    {}
}
```

Advantages:

* Less code
* More consistent

#### Backwards Compatibility / Migration Strategy

Migrating to inline object default parameters does not represent a breaking change.

### Match

* [PHP Docs](https://www.php.net/manual/en/control-structures.match.php)
* [PHP Watch](https://php.watch/versions/8.0/match-expression)

*We have automatically refactored all existing code to use match instead of switch using Rector.*

In most cases, `switch` statements can be replaced with `match` statements:

* Match uses strict equality unlike switch which uses weak comparison and can lead to subtle bugs.
* Each match arm does not fall through without a break statement, unlike switch.
* Match expressions must be exhaustive, if there is no default arm specified, and no arm matches the given value, an `UnhandledMatchError` is thrown.
* Match is an expression and thus returns a value, reducing unnecessary variables and reducing the risk of accessing undefined variables.

From:

```php
switch ($statusCode) {
    case 200:
    case 300:
        $message = null;
        break;
    case 400:
        $message = 'not found';
        break;
    case 500:
        $message = 'server error';
        break;
    default:
        $message = 'unknown status code';
        break;
}
```

To:

```php
$message = match ($statusCode) {
    200, 300 => null,
    400 => 'not found',
    500 => 'server error',
    default => 'unknown status code',
};
```

Note: Conditions can be combined in a much simpler fashion.

#### Backwards Compatibility / Migration Strategy

There are cases where migrating from a switch to a match could case a BC break. For example switch performs lose type checks and throws an exception for unhandled values.

When migrating code, be sure to check that values are the correct types and that all cases are handled.

### New string functions

* `str_contains`
* `str_starts_with`
* `str_ends_with`

Advantages:

* Simpler and more concise.
* Saner return types.
* It is harder to get their usage wrong, for example checking for 0 vs false with `strpos`.
* The functions are faster, being implemented in C.
* The operations require less function calls, for example no usages of strlen are required.

### Named arguments

* [PHP Docs](https://www.php.net/manual/en/functions.arguments.php)
* [PHP Watch](https://php.watch/versions/8.0/named-parameters)

Named arguments are useful when calling code with bad and/or large API's. For example, many of PHP's global functions.

In terms of calling bad PHP API's, the following advantages apply:

* It is possible to skip defaults in between the arguments you want to change.
* The code is better documented since the argument label is specified with the value, very useful for boolean flags.

From:

```php
htmlspecialchars($string, ENT_COMPAT | ENT_HTML, 'UTF-8', false);
```

To:

```php
htmlspecialchars($string, double_encode: false);
```

Note: The second argument is not changed, but in the first example we must provide the default value, in order to change the double encode flag.

#### Backwards Compatibility / Migration Strategy

We do not want to use named parameters when calling Shopware API's as parameter names are not a part of the Backwards compatability promise.

Named parameters should only be used when calling PHP API's.

### Type improvements

* [PHP Docs](https://www.php.net/manual/en/language.types.type-system.php)
* [PHP Watch - Union Types](https://php.watch/versions/8.0/union-types)
* [PHP Watch - Mixed Type](https://php.watch/versions/8.0/mixed-type)
* [PHP Watch - Intersection Types](https://php.watch/versions/8.1/intersection-types)

**It will now only be necessary to reach for @var & @param annotations when defining array shapes, generics and more specific types such as `class-string`, `positive-int` etc. Everything else should be natively typed.**

When a type can really be any value, this can now be expressed as `mixed`.

When a type can be multiple, but not all, this can now be expressed as a union type, eg: `int|string`.

When a type must be an intersection of multiple types, this can now be expressed as an intersection type, eg: `MyService&MockObject`.

These improvements come with various advantages:

* The types are enforced by PHP, so TypeError's will be thrown when attempting to pass non-valid types.
* It allows us to move more type information from phpdoc into function signatures.
* It prevents incorrect function information. phpdocs can often become stale when they are not updated with the function itself.

### Enums

* [PHP Docs](https://www.php.net/manual/en/language.types.enumerations.php)
* [PHP Watch](https://php.watch/versions/8.1/enums)

PHP finally has native support for enumerations, with various advantages over common userland packages and using const's.

Enums are useful where we have a predefined list of constant values. It's now not necessary to provide values as constants, and it's not necessary to create arrays of the constants to check validity.

From:

```php
class Indexer
{
    public const PARTIAL = 'partial';
    public const FULL = 'full';

    public function product(int $id, string $method): void
    {
        if (!in_array($method, [self::PARTIAL, self::FULL], true)) {
            throw new \InvalidArgumentException();
        }
    
        match ($method) {
            self::PARTIAL => $this->partial($id),
            self::FULL => $this->full($id)
        };
    }
}
```

To:

```php
enum IndexMethod
{
    case PARTIAL;
    case FULL;
}

class Indexer
{
    public function product(int $id, IndexMethod $method): void
    {
        match ($method) {
            IndexMethod::PARTIAL => $this->partial($id),
            IndexMethod::FULL => $this->full($id)
        };
    }
}
```

Advantages:

* Works great with `match` - an `UnhandledMatchError` exception will be thrown if there is no match arm for a given enum case.
* Can type hint on an enum.
* No need to validate a case.
* Can provide backed values and serialize/unserialize with `MyEnum::from()` && `MyEnum::tryFrom()`.
* Enums can provide methods and implement interfaces.
* Better comparison features, e.g. Enums are singletons.

#### Backwards Compatibility / Migration Strategy

See the [Use PHP 8.1 Enums](../../../references/adr/2023-05-16-php-enums) ADR for the decision and migration strategy.

### Readonly properties

* [PHP Docs](https://www.php.net/manual/en/language.oop5.properties.php#language.oop5.properties.readonly-properties)
* [PHP Watch](https://php.watch/versions/8.1/readonly)

Readonly properties are very useful when building DTOs. When you want to communicate a payload to a system or service, `readonly` properties allow us to create immutable data structures with a lot less code.

In conjunction with promoted properties, we can reduce the boilerplate of a class significantly. Consider a product reindex command:

From:

```php
class ProductReindexCommand
{
    private int $productId;
    
    private bool $includeStock:
    
    public function __construct(int $productId, bool $includeStock)
    {
        $this->productId = $productId;
        $this->includeStock = $includeStock;
    }
    
    public function getProductId(): int
    {
        return $this->productId;
    }
    
    public function includeStock(): bool
    {
        return $this->includeStock;
    }
}
```

To:

```php
class ProductReindexCommand
{
    public function __construct(public readonly int $productId, public readonly bool $includeStock)
    {
    }
}
```

In the first example, we use private properties to prohibit updates and public getters to allow access to the data. In the second we change the properties to `public` to allow access to the data without getters, but use `readonly` to prohibit updates. We also use promoted properties to make it even more succinct.

Advantages:

* Reduced boilerplate.
* Make the intent of code clearer.

#### Backwards Compatibility / Migration Strategy

All private properties, which are not written to after instantiation can successfully be migrated to `readonly` without BC breaks.

New code can use `readonly` on public and protected properties, but for existing code, that would be a BC break.

### First-class callable syntax

* [PHP Docs](https://www.php.net/manual/en/functions.first_class_callable_syntax.php)
* [PHP Watch](https://php.watch/versions/8.1/first-class-callable-syntax)

This is a new method of referencing callables with strings and arrays. It allows for improved refactoring support, better static analysis and fixes some subtle bugs with scope.

Consider an operation to find the longest string in an array, you might use `strlen` within an `array_map`:

From:

```php
$longest = max(array_map('strlen', $strings));
```

To:

```php
$longest = max(array_map(strlen(...), $strings));
```

Instead of using an arbitrary string as a reference to a function, we can now use the `(...)` syntax to create a callable.

It can also be used with object methods, instance or static, e.g.:

```php
$callable = $object->doCoolStuff(...);
$callable = \My\Object::doCoolStuff(...);
```

Advantages:

* Refactoring support.
* Better static analyses.
* Fixes scope issues.

### Attributes

* [PHP Docs](https://www.php.net/manual/en/language.attributes.overview.php)
* [PHP Watch](https://php.watch/versions/8.0/attributes)

*We have automatically refactored all existing code to use attributes instead of annotations using Rector.*

It is now possible to use native PHP attributes to store structured metadata, rather than using the error-prone PHP docblock.

For us Shopware developers, this will be most useful in conjunction with Symfony bundled attributes, which allow us to configure services and routes directly in controllers and services.

From:

```php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Routing\Annotation\Route;

class BlogController extends AbstractController
{
    /**
     * @Route("/blog", name="blog_list")
     */
    public function list(): Response
    {
        // ...
    }
}
```

To:

```php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Routing\Annotation\Route;

class BlogController extends AbstractController
{
    #[Route('/blog', name: 'blog_list')]
    public function list(): Response
    {
        // ...
    }
}
```

Advantages:

* Add Metadata to classes, methods, properties, arguments and so on.
* They can replace PHP doc blocks, each with custom parsers and rules to a unified standard supported by PHP.
* Type safety & autocompletion.
* The data can be introspected using PHP's Reflection API's.

### Nullsafe operator

* [PHP Docs](https://www.php.net/manual/en/language.oop5.basic.php#language.oop5.basic.nullsafe)
* [PHP Watch](https://php.watch/versions/8.0/null-safe-operator)

The nullsafe operator works the same as property or method accesses, except that if the object being dereferenced is null then null will be returned rather than an exception thrown. If the dereference is part of a chain, the rest of the chain is skipped.

Put another way; it allows chaining multiple property or method accesses on an object, without first checking if each returned value is null before proceeding.

Consider the following code:

```php
class User
{
    public string $firstName;
    public string $lastName;
    public ?int $age = null;
    public ?Address $address = null;
}

class Address
{
    public int $number;
    public string $addressLine1;
    public ?string $addressLine2 = null;
}
```

Pre PHP 8.0, in order to access `addressLine2` for an address of a user, it would be necessary to write the following code:

```php

$user = new User(/**  */);
$address = $user->address;

if ($address !== null) {
   $addressLine2 = $address->addressLine2;
   
   if ($addressLine2 !== null) {
       //do something
   }
}
```

Instead, we can now write:

```php
$user = new User(/**  */);
$addressLine2 = $user?->address?->addressLine2;

if ($addressLine2 !== null) {
    //do something
}
```

Advantages:

* Much less code for simple operations where null is a valid value.
* If the operator is part of a chain, anything to the right of the null will not be executed, the statements will be short-circuited.
* Can be used on methods where null coalescing cannot `$user->getCreatedAt()->format('d-m-Y') ?? null` where `getCreatedAt()` could return `null` or a `\DateTime` instance.

### Other

* `never` return type: https://www.php.net/manual/en/language.types.never.php
* `array_is_list` function: https://www.php.net/manual/en/function.array-is-list.php
* `final const X` final for class constants: https://www.php.net/manual/en/language.oop5.final.php
* `$object::class` instead of `get_class($object)`:  https://wiki.php.net/rfc/class\_name\_literal\_on\_object
* Array unpacking with string keys is now supported: https://www.php.net/manual/en/language.types.array.php#language.types.array.unpacking

There are many more changes, including deprecations and backwards compatibility breaks. Please read the official announcement pages for both PHP 8.0 & PHP 8.1 for a deeper understanding:

* [PHP 8.0](https://www.php.net/releases/8.0/en.php)
* [PHP 8.0 - PHP Watch](https://php.watch/versions/8.0)
* [PHP 8.1](https://www.php.net/releases/8.1/en.php)
* [PHP 8.1 - PHP Watch](https://php.watch/versions/8.1)

## Symfony 6.1 new features

### Enums in route definitions

[Symfony Blog](https://symfony.com/blog/new-in-symfony-6-1-improved-routing-requirements-and-utf-8-parameters)

We can specify route parameters which will be validated against a given enums cases:

```php
use Symfony\Component\Routing\Annotation\Route;
use Symfony\Component\Routing\Requirement\EnumRequirement;

#[Route('/foo/{bar}', requirements: ['bar' => new EnumRequirement(SomeEnum::class)])]
```

### Service autowiring attributes

[Symfony Blog](https://symfony.com/blog/new-in-symfony-6-1-service-autowiring-attributes)

We can now wire up dependencies without touching XML. It is possible to define the required services directly in the class:

```php
use Symfony\Component\DependencyInjection\Attribute\Autowire;

class Mailer
{
    public function __construct(
        #[Autowire(service: 'email_adapter')]
        private Adapter $adapter,

        #[Autowire('%kernel.debug_mode%')]
        private bool $debugMode,
    ) {}
}
```

Further to that, we can decorate services with attributes: https://symfony.com/blog/new-in-symfony-6-1-service-decoration-attributes

#### Backwards Compatibility / Migration Strategy

See the [Symfony Dependency Management](../../../references/adr/_superseded/2023-05-16-symfony-dependency-management) ADR for the decision and migration strategy.

### Improved console autocompletion

[Symfony Blog](https://symfony.com/blog/new-in-symfony-6-1-improved-console-autocompletion)

Autocompletion values can now be defined directly in the command input definition, as the 5th parameter, for both arguments and inputs:

```php
public function configure(): void
{
    $this->addArgument(
        'features',
        InputArgument::REQUIRED | InputArgument::IS_ARRAY,
        'The features to enable',
        null,
        fn () => self::availableFeatures()
    );
}
```

---

---
url: /docs/v6.5/resources/guidelines/code/core/6.5-new-php-language-features.md
---
::: info
This document represents core guidelines and has been mirrored from the core in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/coding-guidelines/core/6.5-new-php-language-features.md)
:::

# 2023-05-16 - PHP 8.1 & Symfony 6.1 new features

## Context

As of Shopware 6.5 the minimum version of PHP is 8.1 and the minimum version of Symfony is 6.1. We would like to *promote* the usage of the newly available features.

Many of the new features allow us to reduce boilerplate, make it easier to prevent common mistakes, improve refactoring support, increase legibility, perform faster and so on.

By using the latest features we allow the reader and writer of code to focus on the domain rather than the language.

## PHP 8.0 & 8.1 new features

### Promoted Properties

* [PHP Docs](https://www.php.net/manual/en/language.oop5.decon.php#language.oop5.decon.constructor.promotion)
* [PHP Watch](https://php.watch/versions/8.0/constructor-property-promotion)

*We have automatically refactored all existing code to use Promoted Properties using Rector.*

Promoted properties allow us to reduce the boilerplate when defining classes, by removing the need to type the property name four times and the type twice.

Class properties, with their visibility and flags can now be specified entirely in the constructor.

From:

```php
class Point {
    private int $x;
    private int $y;
    public function __construct(int $x, int $y)
    {
        $this->x = $x;
        $this->y = $y;
    }
}
```

To:

```php
class Point {
    public function __construct(private int $x, private int $y)
    {
    }
}
```

Note: It is still possible to use normal property definitions/assignments with promoted properties. For example, if you need to manipulate some dependencies.

Advantages:

* Less code, less duplication.
* Better refactoring.

#### Backwards Compatibility / Migration Strategy

Migrating to promoted properties does not represent a breaking change.

### New in initializers

* [PHP Docs](https://www.php.net/manual/en/language.oop5.decon.php#language.oop5.decon.constructor.new)

It is now possible to specify an object as a default parameter value in a function/method. Previously it was only possible to specify scalar values.

From:

```php
class PasswordHasher
{
    private Hasher $hasher;
    public function __construct(private Hasher $hasher = null)
    {
        $this->hasher = $hasher ?? new Bcrypt();
    }
}
```

To:

```php
class PasswordHasher
{
    public function __construct(private Hasher $hasher = new Bcrypt())
    {}
}
```

Advantages:

* Less code
* More consistent

#### Backwards Compatibility / Migration Strategy

Migrating to inline object default parameters does not represent a breaking change.

### Match

* [PHP Docs](https://www.php.net/manual/en/control-structures.match.php)
* [PHP Watch](https://php.watch/versions/8.0/match-expression)

*We have automatically refactored all existing code to use match instead of switch using Rector.*

In most cases, `switch` statements can be replaced with `match` statements:

* Match uses strict equality unlike switch which uses weak comparison and can lead to subtle bugs.
* Each match arm does not fall through without a break statement, unlike switch.
* Match expressions must be exhaustive, if there is no default arm specified, and no arm matches the given value, an `UnhandledMatchError` is thrown.
* Match is an expression and thus returns a value, reducing unnecessary variables and reducing the risk of accessing undefined variables.

From:

```php
switch ($statusCode) {
    case 200:
    case 300:
        $message = null;
        break;
    case 400:
        $message = 'not found';
        break;
    case 500:
        $message = 'server error';
        break;
    default:
        $message = 'unknown status code';
        break;
}
```

To:

```php
$message = match ($statusCode) {
    200, 300 => null,
    400 => 'not found',
    500 => 'server error',
    default => 'unknown status code',
};
```

Note: Conditions can be combined in a much simpler fashion.

#### Backwards Compatibility / Migration Strategy

There are cases where migrating from a switch to a match could case a BC break. For example switch performs lose type checks and throws an exception for unhandled values.

When migrating code, be sure to check that values are the correct types and that all cases are handled.

### New string functions

* `str_contains`
* `str_starts_with`
* `str_ends_with`

Advantages:

* Simpler and more concise.
* Saner return types.
* It is harder to get their usage wrong, for example checking for 0 vs false with `strpos`.
* The functions are faster, being implemented in C.
* The operations require less function calls, for example no usages of strlen are required.

### Named arguments

* [PHP Docs](https://www.php.net/manual/en/functions.arguments.php)
* [PHP Watch](https://php.watch/versions/8.0/named-parameters)

Named arguments are useful when calling code with bad and/or large API's. For example, many of PHP's global functions.

In terms of calling bad PHP API's, the following advantages apply:

* It is possible to skip defaults in between the arguments you want to change.
* The code is better documented since the argument label is specified with the value, very useful for boolean flags.

From:

```php
htmlspecialchars($string, ENT_COMPAT | ENT_HTML, 'UTF-8', false);
```

To:

```php
htmlspecialchars($string, double_encode: false);
```

Note: The second argument is not changed, but in the first example we must provide the default value, in order to change the double encode flag.

#### Backwards Compatibility / Migration Strategy

We do not want to use named parameters when calling Shopware API's as parameter names are not a part of the Backwards compatability promise.

Named parameters should only be used when calling PHP API's.

### Type improvements

* [PHP Docs](https://www.php.net/manual/en/language.types.type-system.php)
* [PHP Watch - Union Types](https://php.watch/versions/8.0/union-types)
* [PHP Watch - Mixed Type](https://php.watch/versions/8.0/mixed-type)
* [PHP Watch - Intersection Types](https://php.watch/versions/8.1/intersection-types)

**It will now only be necessary to reach for @var & @param annotations when defining array shapes, generics and more specific types such as `class-string`, `positive-int` etc. Everything else should be natively typed.**

When a type can really be any value, this can now be expressed as `mixed`.

When a type can be multiple, but not all, this can now be expressed as a union type, eg: `int|string`.

When a type must be an intersection of multiple types, this can now be expressed as an intersection type, eg: `MyService&MockObject`.

These improvements come with various advantages:

* The types are enforced by PHP, so TypeError's will be thrown when attempting to pass non-valid types.
* It allows us to move more type information from phpdoc into function signatures.
* It prevents incorrect function information. phpdocs can often become stale when they are not updated with the function itself.

### Enums

* [PHP Docs](https://www.php.net/manual/en/language.types.enumerations.php)
* [PHP Watch](https://php.watch/versions/8.1/enums)

PHP finally has native support for enumerations, with various advantages over common userland packages and using const's.

Enums are useful where we have a predefined list of constant values. It's now not necessary to provide values as constants, and it's not necessary to create arrays of the constants to check validity.

From:

```php
class Indexer
{
    public const PARTIAL = 'partial';
    public const FULL = 'full';

    public function product(int $id, string $method): void
    {
        if (!in_array($method, [self::PARTIAL, self::FULL], true)) {
            throw new \InvalidArgumentException();
        }
    
        match ($method) {
            self::PARTIAL => $this->partial($id),
            self::FULL => $this->full($id)
        };
    }
}
```

To:

```php
enum IndexMethod
{
    case PARTIAL;
    case FULL;
}

class Indexer
{
    public function product(int $id, IndexMethod $method): void
    {
        match ($method) {
            IndexMethod::PARTIAL => $this->partial($id),
            IndexMethod::FULL => $this->full($id)
        };
    }
}
```

Advantages:

* Works great with `match` - an `UnhandledMatchError` exception will be thrown if there is no match arm for a given enum case.
* Can type hint on an enum.
* No need to validate a case.
* Can provide backed values and serialize/unserialize with `MyEnum::from()` && `MyEnum::tryFrom()`.
* Enums can provide methods and implement interfaces.
* Better comparison features, e.g. Enums are singletons.

#### Backwards Compatibility / Migration Strategy

See the [Use PHP 8.1 Enums](../../../references/adr/2023-05-16-php-enums) ADR for the decision and migration strategy.

### Readonly properties

* [PHP Docs](https://www.php.net/manual/en/language.oop5.properties.php#language.oop5.properties.readonly-properties)
* [PHP Watch](https://php.watch/versions/8.1/readonly)

Readonly properties are very useful when building DTOs. When you want to communicate a payload to a system or service, `readonly` properties allow us to create immutable data structures with a lot less code.

In conjunction with promoted properties, we can reduce the boilerplate of a class significantly. Consider a product reindex command:

From:

```php
class ProductReindexCommand
{
    private int $productId;
    
    private bool $includeStock:
    
    public function __construct(int $productId, bool $includeStock)
    {
        $this->productId = $productId;
        $this->includeStock = $includeStock;
    }
    
    public function getProductId(): int
    {
        return $this->productId;
    }
    
    public function includeStock(): bool
    {
        return $this->includeStock;
    }
}
```

To:

```php
class ProductReindexCommand
{
    public function __construct(public readonly int $productId, public readonly bool $includeStock)
    {
    }
}
```

In the first example, we use private properties to prohibit updates and public getters to allow access to the data. In the second we change the properties to `public` to allow access to the data without getters, but use `readonly` to prohibit updates. We also use promoted properties to make it even more succinct.

Advantages:

* Reduced boilerplate.
* Make the intent of code clearer.

#### Backwards Compatibility / Migration Strategy

All private properties, which are not written to after instantiation can successfully be migrated to `readonly` without BC breaks.

New code can use `readonly` on public and protected properties, but for existing code, that would be a BC break.

### First-class callable syntax

* [PHP Docs](https://www.php.net/manual/en/functions.first_class_callable_syntax.php)
* [PHP Watch](https://php.watch/versions/8.1/first-class-callable-syntax)

This is a new method of referencing callables with strings and arrays. It allows for improved refactoring support, better static analysis and fixes some subtle bugs with scope.

Consider an operation to find the longest string in an array, you might use `strlen` within an `array_map`:

From:

```php
$longest = max(array_map('strlen', $strings));
```

To:

```php
$longest = max(array_map(strlen(...), $strings));
```

Instead of using an arbitrary string as a reference to a function, we can now use the `(...)` syntax to create a callable.

It can also be used with object methods, instance or static, e.g.:

```php
$callable = $object->doCoolStuff(...);
$callable = \My\Object::doCoolStuff(...);
```

Advantages:

* Refactoring support.
* Better static analyses.
* Fixes scope issues.

### Attributes

* [PHP Docs](https://www.php.net/manual/en/language.attributes.overview.php)
* [PHP Watch](https://php.watch/versions/8.0/attributes)

*We have automatically refactored all existing code to use attributes instead of annotations using Rector.*

It is now possible to use native PHP attributes to store structured metadata, rather than using the error-prone PHP docblock.

For us Shopware developers, this will be most useful in conjunction with Symfony bundled attributes, which allow us to configure services and routes directly in controllers and services.

From:

```php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Routing\Annotation\Route;

class BlogController extends AbstractController
{
    /**
     * @Route("/blog", name="blog_list")
     */
    public function list(): Response
    {
        // ...
    }
}
```

To:

```php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Routing\Annotation\Route;

class BlogController extends AbstractController
{
    #[Route('/blog', name: 'blog_list')]
    public function list(): Response
    {
        // ...
    }
}
```

Advantages:

* Add Metadata to classes, methods, properties, arguments and so on.
* They can replace PHP doc blocks, each with custom parsers and rules to a unified standard supported by PHP.
* Type safety & autocompletion.
* The data can be introspected using PHP's Reflection API's.

### Nullsafe operator

* [PHP Docs](https://www.php.net/manual/en/language.oop5.basic.php#language.oop5.basic.nullsafe)
* [PHP Watch](https://php.watch/versions/8.0/null-safe-operator)

The nullsafe operator works the same as property or method accesses, except that if the object being dereferenced is null then null will be returned rather than an exception thrown. If the dereference is part of a chain, the rest of the chain is skipped.

Put another way; it allows chaining multiple property or method accesses on an object, without first checking if each returned value is null before proceeding.

Consider the following code:

```php
class User
{
    public string $firstName;
    public string $lastName;
    public ?int $age = null;
    public ?Address $address = null;
}

class Address
{
    public int $number;
    public string $addressLine1;
    public ?string $addressLine2 = null;
}
```

Pre PHP 8.0, in order to access `addressLine2` for an address of a user, it would be necessary to write the following code:

```php

$user = new User(/**  */);
$address = $user->address;

if ($address !== null) {
   $addressLine2 = $address->addressLine2;
   
   if ($addressLine2 !== null) {
       //do something
   }
}
```

Instead, we can now write:

```php
$user = new User(/**  */);
$addressLine2 = $user?->address?->addressLine2;

if ($addressLine2 !== null) {
    //do something
}
```

Advantages:

* Much less code for simple operations where null is a valid value.
* If the operator is part of a chain, anything to the right of the null will not be executed, the statements will be short-circuited.
* Can be used on methods where null coalescing cannot `$user->getCreatedAt()->format('d-m-Y') ?? null` where `getCreatedAt()` could return `null` or a `\DateTime` instance.

### Other

* `never` return type: https://www.php.net/manual/en/language.types.never.php
* `array_is_list` function: https://www.php.net/manual/en/function.array-is-list.php
* `final const X` final for class constants: https://www.php.net/manual/en/language.oop5.final.php
* `$object::class` instead of `get_class($object)`:  https://wiki.php.net/rfc/class\_name\_literal\_on\_object
* Array unpacking with string keys is now supported: https://www.php.net/manual/en/language.types.array.php#language.types.array.unpacking

There are many more changes, including deprecations and backwards compatibility breaks. Please read the official announcement pages for both PHP 8.0 & PHP 8.1 for a deeper understanding:

* [PHP 8.0](https://www.php.net/releases/8.0/en.php)
* [PHP 8.0 - PHP Watch](https://php.watch/versions/8.0)
* [PHP 8.1](https://www.php.net/releases/8.1/en.php)
* [PHP 8.1 - PHP Watch](https://php.watch/versions/8.1)

## Symfony 6.1 new features

### Enums in route definitions

[Symfony Blog](https://symfony.com/blog/new-in-symfony-6-1-improved-routing-requirements-and-utf-8-parameters)

We can specify route parameters which will be validated against a given enums cases:

```php
use Symfony\Component\Routing\Annotation\Route;
use Symfony\Component\Routing\Requirement\EnumRequirement;

#[Route('/foo/{bar}', requirements: ['bar' => new EnumRequirement(SomeEnum::class)])]
```

### Service autowiring attributes

[Symfony Blog](https://symfony.com/blog/new-in-symfony-6-1-service-autowiring-attributes)

We can now wire up dependencies without touching XML. It is possible to define the required services directly in the class:

```php
use Symfony\Component\DependencyInjection\Attribute\Autowire;

class Mailer
{
    public function __construct(
        #[Autowire(service: 'email_adapter')]
        private Adapter $adapter,

        #[Autowire('%kernel.debug_mode%')]
        private bool $debugMode,
    ) {}
}
```

Further to that, we can decorate services with attributes: https://symfony.com/blog/new-in-symfony-6-1-service-decoration-attributes

#### Backwards Compatibility / Migration Strategy

See the [Symfony Dependency Management](../../../references/adr/2023-05-16-symfony-dependency-management) ADR for the decision and migration strategy.

### Improved console autocompletion

[Symfony Blog](https://symfony.com/blog/new-in-symfony-6-1-improved-console-autocompletion)

Autocompletion values can now be defined directly in the command input definition, as the 5th parameter, for both arguments and inputs:

```php
public function configure(): void
{
    $this->addArgument(
        'features',
        InputArgument::REQUIRED | InputArgument::IS_ARRAY,
        'The features to enable',
        null,
        fn () => self::availableFeatures()
    );
}
```

---

---
url: /docs/v6.6/resources/guidelines/code/core/6.5-new-php-language-features.md
---
::: info
This document represents core guidelines and has been mirrored from the core in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/coding-guidelines/core/6.5-new-php-language-features.md)
:::

# 2023-05-16 - PHP 8.1 & Symfony 6.1 new features

## Context

As of Shopware 6.5 the minimum version of PHP is 8.1 and the minimum version of Symfony is 6.1. We would like to *promote* the usage of the newly available features.

Many of the new features allow us to reduce boilerplate, make it easier to prevent common mistakes, improve refactoring support, increase legibility, perform faster and so on.

By using the latest features we allow the reader and writer of code to focus on the domain rather than the language.

## PHP 8.0 & 8.1 new features

### Promoted Properties

* [PHP Docs](https://www.php.net/manual/en/language.oop5.decon.php#language.oop5.decon.constructor.promotion)
* [PHP Watch](https://php.watch/versions/8.0/constructor-property-promotion)

*We have automatically refactored all existing code to use Promoted Properties using Rector.*

Promoted properties allow us to reduce the boilerplate when defining classes, by removing the need to type the property name four times and the type twice.

Class properties, with their visibility and flags can now be specified entirely in the constructor.

From:

```php
class Point {
    private int $x;
    private int $y;
    public function __construct(int $x, int $y)
    {
        $this->x = $x;
        $this->y = $y;
    }
}
```

To:

```php
class Point {
    public function __construct(private int $x, private int $y)
    {
    }
}
```

Note: It is still possible to use normal property definitions/assignments with promoted properties. For example, if you need to manipulate some dependencies.

Advantages:

* Less code, less duplication.
* Better refactoring.

#### Backwards Compatibility / Migration Strategy

Migrating to promoted properties does not represent a breaking change.

### New in initializers

* [PHP Docs](https://www.php.net/manual/en/language.oop5.decon.php#language.oop5.decon.constructor.new)

It is now possible to specify an object as a default parameter value in a function/method. Previously it was only possible to specify scalar values.

From:

```php
class PasswordHasher
{
    private Hasher $hasher;
    public function __construct(private Hasher $hasher = null)
    {
        $this->hasher = $hasher ?? new Bcrypt();
    }
}
```

To:

```php
class PasswordHasher
{
    public function __construct(private Hasher $hasher = new Bcrypt())
    {}
}
```

Advantages:

* Less code
* More consistent

#### Backwards Compatibility / Migration Strategy

Migrating to inline object default parameters does not represent a breaking change.

### Match

* [PHP Docs](https://www.php.net/manual/en/control-structures.match.php)
* [PHP Watch](https://php.watch/versions/8.0/match-expression)

*We have automatically refactored all existing code to use match instead of switch using Rector.*

In most cases, `switch` statements can be replaced with `match` statements:

* Match uses strict equality unlike switch which uses weak comparison and can lead to subtle bugs.
* Each match arm does not fall through without a break statement, unlike switch.
* Match expressions must be exhaustive, if there is no default arm specified, and no arm matches the given value, an `UnhandledMatchError` is thrown.
* Match is an expression and thus returns a value, reducing unnecessary variables and reducing the risk of accessing undefined variables.

From:

```php
switch ($statusCode) {
    case 200:
    case 300:
        $message = null;
        break;
    case 400:
        $message = 'not found';
        break;
    case 500:
        $message = 'server error';
        break;
    default:
        $message = 'unknown status code';
        break;
}
```

To:

```php
$message = match ($statusCode) {
    200, 300 => null,
    400 => 'not found',
    500 => 'server error',
    default => 'unknown status code',
};
```

Note: Conditions can be combined in a much simpler fashion.

#### Backwards Compatibility / Migration Strategy

There are cases where migrating from a switch to a match could case a BC break. For example switch performs lose type checks and throws an exception for unhandled values.

When migrating code, be sure to check that values are the correct types and that all cases are handled.

### New string functions

* `str_contains`
* `str_starts_with`
* `str_ends_with`

Advantages:

* Simpler and more concise.
* Saner return types.
* It is harder to get their usage wrong, for example checking for 0 vs false with `strpos`.
* The functions are faster, being implemented in C.
* The operations require less function calls, for example no usages of strlen are required.

### Named arguments

* [PHP Docs](https://www.php.net/manual/en/functions.arguments.php)
* [PHP Watch](https://php.watch/versions/8.0/named-parameters)

Named arguments are useful when calling code with bad and/or large API's. For example, many of PHP's global functions.

In terms of calling bad PHP API's, the following advantages apply:

* It is possible to skip defaults in between the arguments you want to change.
* The code is better documented since the argument label is specified with the value, very useful for boolean flags.

From:

```php
htmlspecialchars($string, ENT_COMPAT | ENT_HTML, 'UTF-8', false);
```

To:

```php
htmlspecialchars($string, double_encode: false);
```

Note: The second argument is not changed, but in the first example we must provide the default value, in order to change the double encode flag.

#### Backwards Compatibility / Migration Strategy

We do not want to use named parameters when calling Shopware API's as parameter names are not a part of the Backwards compatability promise.

Named parameters should only be used when calling PHP API's.

### Type improvements

* [PHP Docs](https://www.php.net/manual/en/language.types.type-system.php)
* [PHP Watch - Union Types](https://php.watch/versions/8.0/union-types)
* [PHP Watch - Mixed Type](https://php.watch/versions/8.0/mixed-type)
* [PHP Watch - Intersection Types](https://php.watch/versions/8.1/intersection-types)

**It will now only be necessary to reach for @var & @param annotations when defining array shapes, generics and more specific types such as `class-string`, `positive-int` etc. Everything else should be natively typed.**

When a type can really be any value, this can now be expressed as `mixed`.

When a type can be multiple, but not all, this can now be expressed as a union type, eg: `int|string`.

When a type must be an intersection of multiple types, this can now be expressed as an intersection type, eg: `MyService&MockObject`.

These improvements come with various advantages:

* The types are enforced by PHP, so TypeError's will be thrown when attempting to pass non-valid types.
* It allows us to move more type information from phpdoc into function signatures.
* It prevents incorrect function information. phpdocs can often become stale when they are not updated with the function itself.

### Enums

* [PHP Docs](https://www.php.net/manual/en/language.types.enumerations.php)
* [PHP Watch](https://php.watch/versions/8.1/enums)

PHP finally has native support for enumerations, with various advantages over common userland packages and using const's.

Enums are useful where we have a predefined list of constant values. It's now not necessary to provide values as constants, and it's not necessary to create arrays of the constants to check validity.

From:

```php
class Indexer
{
    public const PARTIAL = 'partial';
    public const FULL = 'full';

    public function product(int $id, string $method): void
    {
        if (!in_array($method, [self::PARTIAL, self::FULL], true)) {
            throw new \InvalidArgumentException();
        }
    
        match ($method) {
            self::PARTIAL => $this->partial($id),
            self::FULL => $this->full($id)
        };
    }
}
```

To:

```php
enum IndexMethod
{
    case PARTIAL;
    case FULL;
}

class Indexer
{
    public function product(int $id, IndexMethod $method): void
    {
        match ($method) {
            IndexMethod::PARTIAL => $this->partial($id),
            IndexMethod::FULL => $this->full($id)
        };
    }
}
```

Advantages:

* Works great with `match` - an `UnhandledMatchError` exception will be thrown if there is no match arm for a given enum case.
* Can type hint on an enum.
* No need to validate a case.
* Can provide backed values and serialize/unserialize with `MyEnum::from()` && `MyEnum::tryFrom()`.
* Enums can provide methods and implement interfaces.
* Better comparison features, e.g. Enums are singletons.

#### Backwards Compatibility / Migration Strategy

See the [Use PHP 8.1 Enums](../../../references/adr/2023-05-16-php-enums) ADR for the decision and migration strategy.

### Readonly properties

* [PHP Docs](https://www.php.net/manual/en/language.oop5.properties.php#language.oop5.properties.readonly-properties)
* [PHP Watch](https://php.watch/versions/8.1/readonly)

Readonly properties are very useful when building DTOs. When you want to communicate a payload to a system or service, `readonly` properties allow us to create immutable data structures with a lot less code.

In conjunction with promoted properties, we can reduce the boilerplate of a class significantly. Consider a product reindex command:

From:

```php
class ProductReindexCommand
{
    private int $productId;
    
    private bool $includeStock:
    
    public function __construct(int $productId, bool $includeStock)
    {
        $this->productId = $productId;
        $this->includeStock = $includeStock;
    }
    
    public function getProductId(): int
    {
        return $this->productId;
    }
    
    public function includeStock(): bool
    {
        return $this->includeStock;
    }
}
```

To:

```php
class ProductReindexCommand
{
    public function __construct(public readonly int $productId, public readonly bool $includeStock)
    {
    }
}
```

In the first example, we use private properties to prohibit updates and public getters to allow access to the data. In the second we change the properties to `public` to allow access to the data without getters, but use `readonly` to prohibit updates. We also use promoted properties to make it even more succinct.

Advantages:

* Reduced boilerplate.
* Make the intent of code clearer.

#### Backwards Compatibility / Migration Strategy

All private properties, which are not written to after instantiation can successfully be migrated to `readonly` without BC breaks.

New code can use `readonly` on public and protected properties, but for existing code, that would be a BC break.

### First-class callable syntax

* [PHP Docs](https://www.php.net/manual/en/functions.first_class_callable_syntax.php)
* [PHP Watch](https://php.watch/versions/8.1/first-class-callable-syntax)

This is a new method of referencing callables with strings and arrays. It allows for improved refactoring support, better static analysis and fixes some subtle bugs with scope.

Consider an operation to find the longest string in an array, you might use `strlen` within an `array_map`:

From:

```php
$longest = max(array_map('strlen', $strings));
```

To:

```php
$longest = max(array_map(strlen(...), $strings));
```

Instead of using an arbitrary string as a reference to a function, we can now use the `(...)` syntax to create a callable.

It can also be used with object methods, instance or static, e.g.:

```php
$callable = $object->doCoolStuff(...);
$callable = \My\Object::doCoolStuff(...);
```

Advantages:

* Refactoring support.
* Better static analyses.
* Fixes scope issues.

### Attributes

* [PHP Docs](https://www.php.net/manual/en/language.attributes.overview.php)
* [PHP Watch](https://php.watch/versions/8.0/attributes)

*We have automatically refactored all existing code to use attributes instead of annotations using Rector.*

It is now possible to use native PHP attributes to store structured metadata, rather than using the error-prone PHP docblock.

For us Shopware developers, this will be most useful in conjunction with Symfony bundled attributes, which allow us to configure services and routes directly in controllers and services.

From:

```php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Routing\Annotation\Route;

class BlogController extends AbstractController
{
    /**
     * @Route("/blog", name="blog_list")
     */
    public function list(): Response
    {
        // ...
    }
}
```

To:

```php
namespace App\Controller;

use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\Routing\Annotation\Route;

class BlogController extends AbstractController
{
    #[Route('/blog', name: 'blog_list')]
    public function list(): Response
    {
        // ...
    }
}
```

Advantages:

* Add Metadata to classes, methods, properties, arguments and so on.
* They can replace PHP doc blocks, each with custom parsers and rules to a unified standard supported by PHP.
* Type safety & autocompletion.
* The data can be introspected using PHP's Reflection API's.

### Nullsafe operator

* [PHP Docs](https://www.php.net/manual/en/language.oop5.basic.php#language.oop5.basic.nullsafe)
* [PHP Watch](https://php.watch/versions/8.0/null-safe-operator)

The nullsafe operator works the same as property or method accesses, except that if the object being dereferenced is null then null will be returned rather than an exception thrown. If the dereference is part of a chain, the rest of the chain is skipped.

Put another way; it allows chaining multiple property or method accesses on an object, without first checking if each returned value is null before proceeding.

Consider the following code:

```php
class User
{
    public string $firstName;
    public string $lastName;
    public ?int $age = null;
    public ?Address $address = null;
}

class Address
{
    public int $number;
    public string $addressLine1;
    public ?string $addressLine2 = null;
}
```

Pre PHP 8.0, in order to access `addressLine2` for an address of a user, it would be necessary to write the following code:

```php

$user = new User(/**  */);
$address = $user->address;

if ($address !== null) {
   $addressLine2 = $address->addressLine2;
   
   if ($addressLine2 !== null) {
       //do something
   }
}
```

Instead, we can now write:

```php
$user = new User(/**  */);
$addressLine2 = $user?->address?->addressLine2;

if ($addressLine2 !== null) {
    //do something
}
```

Advantages:

* Much less code for simple operations where null is a valid value.
* If the operator is part of a chain, anything to the right of the null will not be executed, the statements will be short-circuited.
* Can be used on methods where null coalescing cannot `$user->getCreatedAt()->format('d-m-Y') ?? null` where `getCreatedAt()` could return `null` or a `\DateTime` instance.

### Other

* `never` return type: https://www.php.net/manual/en/language.types.never.php
* `array_is_list` function: https://www.php.net/manual/en/function.array-is-list.php
* `final const X` final for class constants: https://www.php.net/manual/en/language.oop5.final.php
* `$object::class` instead of `get_class($object)`:  https://wiki.php.net/rfc/class\_name\_literal\_on\_object
* Array unpacking with string keys is now supported: https://www.php.net/manual/en/language.types.array.php#language.types.array.unpacking

There are many more changes, including deprecations and backwards compatibility breaks. Please read the official announcement pages for both PHP 8.0 & PHP 8.1 for a deeper understanding:

* [PHP 8.0](https://www.php.net/releases/8.0/en.php)
* [PHP 8.0 - PHP Watch](https://php.watch/versions/8.0)
* [PHP 8.1](https://www.php.net/releases/8.1/en.php)
* [PHP 8.1 - PHP Watch](https://php.watch/versions/8.1)

## Symfony 6.1 new features

### Enums in route definitions

[Symfony Blog](https://symfony.com/blog/new-in-symfony-6-1-improved-routing-requirements-and-utf-8-parameters)

We can specify route parameters which will be validated against a given enums cases:

```php
use Symfony\Component\Routing\Annotation\Route;
use Symfony\Component\Routing\Requirement\EnumRequirement;

#[Route('/foo/{bar}', requirements: ['bar' => new EnumRequirement(SomeEnum::class)])]
```

### Service autowiring attributes

[Symfony Blog](https://symfony.com/blog/new-in-symfony-6-1-service-autowiring-attributes)

We can now wire up dependencies without touching XML. It is possible to define the required services directly in the class:

```php
use Symfony\Component\DependencyInjection\Attribute\Autowire;

class Mailer
{
    public function __construct(
        #[Autowire(service: 'email_adapter')]
        private Adapter $adapter,

        #[Autowire('%kernel.debug_mode%')]
        private bool $debugMode,
    ) {}
}
```

Further to that, we can decorate services with attributes: https://symfony.com/blog/new-in-symfony-6-1-service-decoration-attributes

#### Backwards Compatibility / Migration Strategy

See the [Symfony Dependency Management](../../../references/adr/2023-05-16-symfony-dependency-management) ADR for the decision and migration strategy.

### Improved console autocompletion

[Symfony Blog](https://symfony.com/blog/new-in-symfony-6-1-improved-console-autocompletion)

Autocompletion values can now be defined directly in the command input definition, as the 5th parameter, for both arguments and inputs:

```php
public function configure(): void
{
    $this->addArgument(
        'features',
        InputArgument::REQUIRED | InputArgument::IS_ARRAY,
        'The features to enable',
        null,
        fn () => self::availableFeatures()
    );
}
```

---

---
url: /frontends/best-practices/testing/ab-testing.md
---

# A/B Testing practices

A/B testing is a method of comparing two versions of a webpage or app against each other to determine which one performs better. It is a way to compare two versions of a single variable, typically by testing a subject's response to variant A against variant B, and determining which of the two variants is more effective.

## Providers

There are planty of A/B testing providers available. Here are some of the most popular ones:

* [AB Tasty](https://www.abtasty.com/)
* [Optimizely](https://www.optimizely.com/)
* [VWO](https://vwo.com/)
* [Split.io](https://www.split.io/)
* [Kameleoon](https://www.kameleoon.com/)
* [PostHog](https://posthog.com/)

You need to pick the right one for your needs. Depending on the size of your company, the complexity of your tests, and the budget you have available. There are generous free plans available in that list, so in most cases, you can start with that.

## Best practices

### Start with a hypothesis

Before you start your A/B test, you should have a clear hypothesis. What do you want to test? What do you expect to happen? What is the goal of the test?

### Split components dynamically to avoid enlagred bundle sizes

You should split your components dynamically. This will help you to avoid enlarged bundle sizes. You can use the `import()` function to load components on demand. Example:

```ts
const myExperimentFlag = useABTesting("myExperimentFlag");

const MyComponent = myExperimentFlag ? import("./MyComponentVariantA") : import("./MyComponentVariantB");

// later in the template

<MyComponent />
```

### Testing smaller components

While dynamic splitting is very effective to avoid loading too much code to the client's browser, this would not be efficient with some very small components. For example if you only want to test a different button variant, then in most cases it could be done in a single component. Example:

```ts
const myExperimentFlag = useABTesting("myExperimentFlag");

// later in the template

<button :class={{
  "bg-color-red": myExperimentFlag,
  "bg-color-blue": !myExperimentFlag
}}> Click me </button>

// or more slear split using v-show/v-if

<button v-if="myExperimentFlag" class="bg-color-red"> Click me </button>
<button v-else class="bg-color-blue"> Click me please! </button>
```

### Clean your code

After the test is finished, you should clean your code. Remove all the unused code and components. This will help you to keep your codebase clean and maintainable. Not removing unused variants will cost you many maintenance problems, especially while refactoring your application.

---

---
url: /docs/guides/development/accessibility.md
---

# Accessibility

Shopware is committed to creating inclusive and barrier-free shopping experiences. Accessibility affects both the core Storefront and all custom themes and extensions. Developers are responsible for ensuring their implementations comply with accessibility standards, such as WCAG 2.1 Level AA.

## In this section

## Why accessibility matters

* Legal compliance (e.g., EU accessibility regulations)
* Better usability for all users
* Improved SEO and performance
* Future-proof storefront implementations

Shopware continuously introduces accessibility improvements in new releases. Always test extensions with the `ACCESSIBILITY_TWEAKS` feature flag enabled to ensure compatibility.

---

---
url: /docs/guides/development/accessibility/storefront-accessibility.md
---

# Accessibility in the Storefront

Shopware is committed to creating inclusive and barrier-free shopping experiences for our merchants and their customers.

## What does Shopware do to ensure accessibility?

* Shopware is committed to fulfilling the [WCAG 2.1 AA](https://www.w3.org/TR/WCAG21/) accessibility guidelines and Barrier-Free Information Technology Regulation (BITV 2.0) in the Storefront.
  * You can find more information on [shopware.design](https://shopware.design/foundations/accessibility.html) and [in our blog post](https://www.shopware.com/en/news/accessible-online-store-by-2025/).
* The Storefront is using [Bootstrap components](https://getbootstrap.com/docs/5.3/getting-started/accessibility/) that already consider good accessibility practices, for example, using aria roles.
* Much of the HTML structure and CSS styling already fulfill accessibility guidelines. However, there are still [open accessibility issues](https://github.com/shopware/shopware/issues?q=state%3Aopen%20label%3Aarea%2Faccessibility) that will be addressed.
* Automated [E2E testing with playwright](https://github.com/shopware/shopware/tree/trunk/tests/acceptance) and axe reporter are used to ensure future accessibility.

## How are core accessibility improvements released?

Starting with **Shopware 6.6+**, accessibility improvements have been introduced, and **6.7+** includes further enhancements. Accessibility improvements are rolled out in regular minor releases, similar to other improvements or bug fixes.
There is no significant "accessibility release" planned that ships all accessibility improvements at once.

## How to deal with breaking accessibility changes?

Ensuring an accessible shop page can require changes in the HTML/Twig structure or the CSS. This can cause unintended behavior in an extension that modifies an area being changed to improve accessibility.

Because of this, breaking accessibility changes are not enabled by default. All accessibility changes that include breaking changes are implemented behind a feature flag:

```env
ACCESSIBILITY_TWEAKS=1
```

However, breaking accessibility changes are still released regularly inside minor releases. They are not active by default to not cause a breaking change.

The feature flag `ACCESSIBILITY_TWEAKS` can be activated in your `.env`, similar to the major feature flags like `V6_7_0_0`. When the feature flag is enabled, all available accessibility improvements are activated.
This allows you to check whether your project or extension is affected by the change and to prepare an adaptation already if necessary.

::: warning
With the major version v6.7.0, all accessibility improvements will become the default.
:::

### Example of a breaking accessibility change

Let's say, for example, that a list is not using proper markup and is changed to improve accessibility.

This is what a suboptimal HTML structure could look like:

```twig
<div class="sidebar-list">
 {% block component_list_items %}
 <div class="list-item"><a href="#">Item</a></div>
 <div class="list-item"><a href="#">Item</a></div>
 <div class="list-item"><a href="#">Item</a></div>
 {% endblock %}
</div>
```

Let's assume it should be changed to a proper list. Instead of implementing this right away, it is implemented behind the `ACCESSIBILITY_TWEAKS` flag, including instructions on how it should be changed:

```twig
{# @deprecated tag:v6.7.0 - The list will be changed to `<ul>` and `<li>` to improve accessibility #}
{% if feature('ACCESSIBILITY_TWEAKS') %}
 <ul class="sidebar-list">
 {% block component_list_items_inner %}
 <li class="list-item"><a href="#">Item</a></li>
 <li class="list-item"><a href="#">Item</a></li>
 <li class="list-item"><a href="#">Item</a></li>
 {% endblock %}
 </ul>
{% else %}
 <div class="sidebar-list">
 {# @deprecated tag:v6.7.0 - Use `component_list_items_inner` instead with `<li>` #}
 {% block component_list_items %}
 <div class="list-item"><a href="#">Item</a></div>
 <div class="list-item"><a href="#">Item</a></div>
 <div class="list-item"><a href="#">Item</a></div>
 {% endblock %}
 </div>
{% endif %}
```

If the block `component_list_items` is being extended, the new accessibility change can already be considered. If the change was rolled out without a feature flag, the extension still assumes a `<div class="list-item">` which would likely result in incorrect HTML:

```twig
{% sw_extends '@Storefront/storefront/component/list.html.twig' %}

{# Consider the new structure already #}
{% block component_list_items_inner %}
 {{ parent() }}
 <li class="list-item"><a href="#">My item</a></li>
{% endblock %}

{# This can be removed after v6.7.0 #}
{% block component_list_items %}
 {{ parent() }}
 <div class="list-item"><a href="#">My item</a></div>
{% endblock %}
```

## Overview of accessibility issues for iteration 1

::: info
With accessibility iteration 1, we have addressed the most critical accessibility problems and implemented multiple improvements.
:::

### Continuous efforts to ensure accessibility

We are continuously testing our core Storefront to meet accessibility requirements. This includes screen reader usage, keyboard operation, or color contrast analysis.
We are using the [WCAG 2.1 Level AA](https://www.w3.org/TR/WCAG21/) standard and do our best to resolve all issues to meet its requirements.

### Overview of released accessibility improvements

* Below, you find a list of recent accessibility improvements. The list includes a changelog and the release versions for each improvement.
* Enable the feature flag `ACCESSIBILITY_TWEAKS` to activate all breaking accessibility changes.

| Topic                                                                                           | Breaking changes | Changelog                                                                                                                                                 | Release versions                                                                                 |
|-------------------------------------------------------------------------------------------------|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|
| Missing semantic markup of form address headings                                                | No               | [Changelog](https://github.com/shopware/shopware/blob/v6.6.6.0/changelog/release-6-6-6-0/2024-08-13-registration-form-fieldset-improvement.md)            | [v6.6.6.0](https://github.com/shopware/shopware/releases/tag/v6.6.6.0)                           |
| Product image zoom modal keyboard accessibility                                                 | No               | [Changelog](https://github.com/shopware/shopware/blob/v6.6.6.0/changelog/release-6-6-6-0/2024-08-08-improve-image-zoom-modal-accessibility.md)            | [v6.6.6.0](https://github.com/shopware/shopware/releases/tag/v6.6.6.0)                           |
| Focused slides in the carousel are not being moved into the visible area                        | Yes              | [Changelog](https://github.com/shopware/shopware/blob/v6.6.6.0/changelog/release-6-6-6-0/2024-08-05-improve-slider-element-accessibility.md)              | [v6.6.6.0](https://github.com/shopware/shopware/releases/tag/v6.6.6.0)                           |
| Focus jumps to the top of the page after closing a modal                                        | No               | [Changelog](https://github.com/shopware/shopware/blob/v6.6.6.0/changelog/release-6-6-6-0/2024-08-01-add-focus-handling-to-storefront.md)                  | [v6.6.6.0](https://github.com/shopware/shopware/releases/tag/v6.6.6.0)                           |
| Ensure that resizing content up to 200% does not cause breaks                                   | Yes              | [Changelog](https://github.com/shopware/shopware/blob/v6.6.6.0/changelog/release-6-6-6-0/2024-08-13-Improved-storefront-text-scaling.md)                  | [v6.6.6.0](https://github.com/shopware/shopware/releases/tag/v6.6.6.0)                           |
| Language of each Storefront passage or phrase in the content can be programmatically determined | No               | [Changelog](https://github.com/shopware/shopware/blob/v6.6.6.0/changelog/release-6-6-6-0/2024-08-05-add-language-to-reviews.md)                           | [v6.6.6.0](https://github.com/shopware/shopware/releases/tag/v6.6.6.0)                           |
| Check Lighthouse Accessibility Score                                                            | No               | [Changelog](https://github.com/shopware/shopware/blob/v6.6.6.0/changelog/release-6-6-6-0/2024-08-21-fix-scroll-up-button-accessibility.md)                | [v6.6.6.0](https://github.com/shopware/shopware/releases/tag/v6.6.6.0)                           |
| Pagination does not have links                                                                  | Yes              | [Changelog](https://github.com/shopware/shopware/blob/v6.6.6.0/changelog/release-6-6-6-0/2023-08-31-pagination-with-links.md)                             | [v6.6.6.0](https://github.com/shopware/shopware/releases/tag/v6.6.6.0)                           |
| Non-informative document title                                                                  | No               | [Changelog](https://github.com/shopware/shopware/blob/v6.6.1.0/changelog/release-6-6-1-0/2024-03-12-distinctive-document-titles.md)                       | [v6.6.6.0](https://github.com/shopware/shopware/releases/tag/v6.6.1.0)                           |
| The form element quantity selector is not labeled                                               | No               | [Changelog](https://github.com/shopware/shopware/blob/v6.6.5.0/changelog/release-6-6-5-0/2024-07-15-the-form-element-quantity-selector-is-not-labeled.md) | [v6.6.5.0](https://github.com/shopware/shopware/releases/tag/v6.6.5.0)                           |
| Slider reports confusing status changes to screen readers                                       | No               | [Changelog](https://github.com/shopware/shopware/blob/v6.6.4.0/changelog/release-6-6-4-0/2024-05-31-remove-unwanted-aria-live-attributes-from-sliders.md) | [v6.6.4.0](https://github.com/shopware/shopware/releases/tag/v6.6.4.0)                           |
| The user needs to be able to close triggered, additional content                                | No               | [Changelog](https://github.com/shopware/shopware/blob/trunk/changelog/release-6-6-3-0/2024-05-03-esc-key-for-nav-flyout-close.md)                         | [v6.6.3.0](https://github.com/shopware/shopware/releases/tag/v6.6.3.0)                           |
| Improve "Remove Product" button labeling in checkout                                            | No               | [Changelog](https://github.com/shopware/shopware/blob/v6.6.3.0/changelog/release-6-6-3-0/2024-05-03-improve-line-item-labels-and-alt-texts.md)            | [v6.6.3.0](https://github.com/shopware/shopware/releases/tag/v6.6.3.0)                           |
| Missing alternative text for product images in the shopping cart                                | No               | [Changelog](https://github.com/shopware/shopware/blob/v6.6.3.0/changelog/release-6-6-3-0/2024-05-03-improve-line-item-labels-and-alt-texts.md)            | [v6.6.3.0](https://github.com/shopware/shopware/releases/tag/v6.6.3.0)                           |
| A closing mechanism for the navigation                                                          | No               | [Changelog](https://github.com/shopware/shopware/blob/trunk/changelog/release-6-6-3-0/2024-05-03-esc-key-for-nav-flyout-close.md)                         | [v6.6.3.0](https://github.com/shopware/shopware/releases/tag/v6.6.3.0)                           |
| Change shipping toggle in OffCanvas cart to button element                                      | No               | [Changelog](https://github.com/shopware/shopware/blob/v6.6.2.0/changelog/release-6-6-2-0/2024-04-17-change-shipping-costs-toggle-to-button-element.md)    | [v6.6.2.0](https://github.com/shopware/shopware/releases/tag/v6.6.2.0)                           |
| Add heading elements for account login page                                                     | No               | [Changelog](https://github.com/shopware/shopware/blob/v6.6.2.0/changelog/release-6-6-2-0/2024-04-15-heading-elements-on-registration-page.md)             | [v6.6.2.0](https://github.com/shopware/shopware/releases/tag/v6.6.2.0)                           |
| Provide distinctive document titles for each page                                               | No               | [Changelog](https://github.com/shopware/shopware/blob/v6.6.1.0/changelog/release-6-6-1-0/2024-03-12-distinctive-document-titles.md)                       | [v6.6.1.0](https://github.com/shopware/shopware/releases/tag/v6.6.1.0)                           |
| No empty nav element in top-bar                                                                 | Yes              | [Changelog](https://github.com/shopware/shopware/blob/v6.6.1.0/changelog/release-6-6-1-0/2023-03-05-no-empty-nav.md)                                      | [v6.6.1.0](https://github.com/shopware/shopware/releases/tag/v6.6.1.0)                           |
| Update the focus states so that they are clearly visible                                        | No               | [Multiple changes](https://github.com/search?q=repo%3Ashopware%2Fshopware+NEXT-26712\&type=commits)                                                        | [Multiple releases](https://github.com/search?q=repo%3Ashopware%2Fshopware+NEXT-26712\&type=code) |
| Increase compatibility of Storefront with future assistance technologies                        | No               | [Multiple changes](https://github.com/search?q=repo%3Ashopware%2Fshopware+NEXT-26717\&type=commits)                                                        | [Multiple releases](https://github.com/search?q=repo%3Ashopware%2Fshopware+NEXT-26717\&type=code) |
| Content functionality operable through keyboard                                                 | Yes              | [Multiple changes](https://github.com/search?q=repo%3Ashopware%2Fshopware+NEXT-26705\&type=commits)                                                        | [Multiple releases](https://github.com/search?q=repo%3Ashopware%2Fshopware+NEXT-26705\&type=code) |
| No keyboard traps should occur in the Storefront                                                | -                | Verification work without released code changes                                                                                                           | -                                                                                                |
| Mechanism for the user to pause, stop, or hide moving content                                   | -                | Verification work without released code changes                                                                                                           | -                                                                                                |
| Add text to components that only work with icons to identify their purpose                      | -                | -                                                                                                                                                         |
| Check if all non-text content has a text alternative and provide if necessary                     | -                | -                                                                                                                                                         |
| Provide error correction suggestions                                                            | -                | -                                                                                                                                                         |
| Text styles need to be adjusted (line height, paragraph spacing)                               | -                | -                                                                                                                                                         |
| Keyboard/Tabs should work for nav main-navigation-menu                                          | -                | -                                                                                                                                                         |

### Overview of known accessibility issues

To report any new accessibility issues, click the New Issue button, select Bug Report, fill out the required fields, and make sure to add the area/accessibility label.
Here is a reference to the existing [accessibility Issues](https://github.com/shopware/shopware/issues?q=state%3Aopen%20label%3Aarea%2Faccessibility).

## Best practices for accessibility (a11y) in Shopware extensions

Ensuring accessibility in your Shopware extension improves **usability, inclusivity, and compliance** with standards like **WCAG 2.1** and the **EU Web Accessibility Directive**. Below are best practices to help you build accessible extensions and themes.

### 1. Setting up for accessibility testing

#### Activate the accessibility feature flag

Enable the **feature flag** to test changes before release by activating it in your local environment. Modify your `project-root/.env`.

```env
ACCESSIBILITY_TWEAKS=1
```

Once `ACCESSIBILITY_TWEAKS` is enabled, a theme recompilation is needed to apply all styling improvements, such as adjusted font sizes.

```text
bin/console theme:compile
```

Now you can:

* Preview upcoming a11y improvements before they become mandatory.
* Identify potential breaking changes in your theme or extension.
* Ensure your UI remains functional with new [accessibility enhancements](./accessibility-checklist.md).

### 2. Testing for accessibility compliance

#### Automated testing tools

Use automated tools to **detect common accessibility issues** in your extension:

* **[Google Lighthouse](../testing/store/quality-guidelines.md#lighthouse-a-b-testing)** – Run audits in Chrome DevTools.
* **AXE DevTools** – More detailed accessibility testing.
* **WAVE (WebAIM Tool)** – Identifies HTML structure and ARIA misuses.

#### Manual Testing

While automation helps, **manual checks** ensure real-world usability:

* **Keyboard Navigation** – Ensure users can navigate your store using `Tab`, `Enter`, and `Esc`.
* **Screen Readers** – Test with **NVDA (Windows)** or **VoiceOver (Mac/iOS)**.
* **Color Contrast Checks** – Use [WebAIM Contrast Checker](https://webaim.org/resources/contrastchecker/) to verify readability.

### 3. Validating accessibility in extensions

#### Common a11y issues to fix before release

* Misuse of **HTML & ARIA roles** (Ensure correct semantic structure).
* Missing **form labels & alt text** for images/icons.
* Improper **focus management** in modals, dropdowns, and popups.
* **Dynamic content updates** not announced to screen readers.

#### Shopware QA and self-certification

* Developers can **self-certify** an extension as a11y-compliant.
* Shopware **QA verification** may be required for listing in the store.

### 4. Accessibility support in Shopware versions

| **Shopware version** | **Accessibility support** |
|---------------------|------------------------|
| **6.7+** | Full A11y improvements available for testing |
| **6.6+** | Accessibility features introduced (use `ACCESSIBILITY_TWEAKS` feature flag) |
| **Shopware 5** | **No accessibility support** |

### 5. Getting help with accessibility

* Work with **Shopware-certified agencies** for A11y audits.
* Stay updated with Shopware's **developer guidelines**.
* Discuss A11y best practices with other developers in the **Shopware community**.

## Conclusion

Understanding accessibility best practices is just the beginning. To truly create an inclusive storefront, these ideas must be translated into practice. To help you turn these into action, we have created a comprehensive [Storefront Accessibility Checklist](./accessibility-checklist.md). It outlines the key technical and design practices needed to build accessible interfaces—from semantic HTML to keyboard navigation and ARIA usage.

---

---
url: /docs/v6.6/resources/accessibility/storefront.md
---

# Accessibility in the Storefront

At Shopware, we are committed to creating inclusive and barrier-free shopping experiences for our merchants and their customers.

## What shopware does to ensure accessibility

* Shopware is committed to fulfill the [WCAG 2.1 AA](https://www.w3.org/TR/WCAG21/) accessibility guidelines and Barrier-Free Information Technology Regulation (BITV 2.0) in the Storefront.
  * You can find more information on [shopware.design](https://shopware.design/foundations/accessibility.html) and [in our blog post](https://www.shopware.com/en/news/accessible-online-store-by-2025/).
* The Storefront is using [Bootstrap components](https://getbootstrap.com/docs/5.3/getting-started/accessibility/) that already consider good accessibility practices, for example, using aria roles.
* Much of the HTML structure and CSS styling already fulfill accessibility guidelines. However, there are still [open accessibility issues](#Overview-of-known-accessibility-issues) that will be addressed.
* Automated [E2E testing with playwright](https://github.com/shopware/shopware/tree/trunk/tests/acceptance) and axe reporter are used to ensure future accessibility.

## How core accessibility improvements are released

Accessibility improvements are rolled out in regular minor releases, similar to other improvements or bug-fixes. We implement all accessibility improvements in the current major version `6.6.x` and its minor versions.
There is no large "accessibility release" planned that ships all accessibility improvements at once.

## How to deal with breaking accessibility changes

Ensuring an accessible shop page can require changes in the HTML/Twig structure or the CSS. This can cause unintended behavior for an extension that is modifying an area that is being changed to improve accessibility.

Because of this, breaking accessibility changes are not enabled by default. All accessibility changes that include breaking changes are implemented behind a feature flag:

```env
ACCESSIBILITY_TWEAKS
```

However, breaking accessibility changes are still released regularly inside minor releases. They are just not active by default to not cause a breaking change.

The feature flag `ACCESSIBILITY_TWEAKS` can be activated inside your `.env`, similar to the major feature flags like `V6_7_0_0`. When the feature flag is enabled, all available accessibility improvements are activated.
This allows you to check if your project or extension is effected by the change and already prepare an adaptation to the change if it is necessary.

::: warning
With the major version v6.7.0 all accessibility improvements will become the default.
:::

### Example of a breaking accessibility change

Let's say, for example, that a list is not using a proper markup, and it is changed to improve accessibility.

This is what a suboptimal HTML structure could look like:

```twig
<div class="sidebar-list">
    {% block component_list_items %}
        <div class="list-item"><a href="#">Item</a></div>
        <div class="list-item"><a href="#">Item</a></div>
        <div class="list-item"><a href="#">Item</a></div>
    {% endblock %}
</div>
```

Let's assume it should be changed to a proper list. Instead of implementing this right away, it is implemented behind the `ACCESSIBILITY_TWEAKS` flag, including instructions how it should be changed:

```twig
{# @deprecated tag:v6.7.0 - The list will be changed to `<ul>` and `<li>` to improve accessibility #}
{% if feature('ACCESSIBILITY_TWEAKS') %}
    <ul class="sidebar-list">
        {% block component_list_items_inner %}
            <li class="list-item"><a href="#">Item</a></li>
            <li class="list-item"><a href="#">Item</a></li>
            <li class="list-item"><a href="#">Item</a></li>
        {% endblock %}
    </ul>
{% else %}
    <div class="sidebar-list">
        {# @deprecated tag:v6.7.0 - Use `component_list_items_inner` instead with `<li>` #}
        {% block component_list_items %}
            <div class="list-item"><a href="#">Item</a></div>
            <div class="list-item"><a href="#">Item</a></div>
            <div class="list-item"><a href="#">Item</a></div>
        {% endblock %}
    </div>
{% endif %}
```

If the block `component_list_items` is being extended, the new accessibility change can already be considered. If the change was rolled out without a feature flag, the extension still assumes a `<div class="list-item">` which would likely result in incorrect HTML:

```twig
{% sw_extends '@Storefront/storefront/component/list.html.twig' %}

{# Consider the new structure already #}
{% block component_list_items_inner %}
    {{ parent() }}
    <li class="list-item"><a href="#">My item</a></li>
{% endblock %}

{# This can be removed after v6.7.0 #}
{% block component_list_items %}
    {{ parent() }}
    <div class="list-item"><a href="#">My item</a></div>
{% endblock %}
```

## Overview of accessibility issues for iteration 1

::: info
With accessibility iteration 1 we have addressed the most critical accessibility problems and implemented multiple improvements.
You can find an overview of the accessibility iteration 1 epic in the following ticket: [NEXT-37039](https://issues.shopware.com/issues/NEXT-37039)
:::

### Continuous efforts to ensure accessibility

We are continuously testing our core Storefront to meet accessibility requirements. This includes screen reader usage, keyboard-operation or color contrast analyzes.
We are using the [WCAG 2.1 Level AA](https://www.w3.org/TR/WCAG21/) standard and do our best to solve all issues to meet the WCAG 2.1 requirements.

### Overview of released accessibility improvements

* Below, you find a list of recent accessibility improvements. The list includes a changelog and the release versions for each improvement.
* Enable the feature flag `ACCESSIBILITY_TWEAKS` to activate all breaking accessibility changes.

| Topic                                                                                           | Breaking changes | Changelog                                                                                                                                                 | Release versions                                                                                 |
|-------------------------------------------------------------------------------------------------|------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------|--------------------------------------------------------------------------------------------------|
| Missing semantic markup of form address headings                                                | No               | [Changelog](https://github.com/shopware/shopware/blob/v6.6.6.0/changelog/release-6-6-6-0/2024-08-13-registration-form-fieldset-improvement.md)            | [v6.6.6.0](https://github.com/shopware/shopware/releases/tag/v6.6.6.0)                           |
| Product image zoom modal keyboard accessibility                                                 | No               | [Changelog](https://github.com/shopware/shopware/blob/v6.6.6.0/changelog/release-6-6-6-0/2024-08-08-improve-image-zoom-modal-accessibility.md)            | [v6.6.6.0](https://github.com/shopware/shopware/releases/tag/v6.6.6.0)                           |
| Focused slides in the carousel are not being moved into the visible area                        | Yes              | [Changelog](https://github.com/shopware/shopware/blob/v6.6.6.0/changelog/release-6-6-6-0/2024-08-05-improve-slider-element-accessibility.md)              | [v6.6.6.0](https://github.com/shopware/shopware/releases/tag/v6.6.6.0)                           |
| Focus jumps to the top of the page after closing a modal                                        | No               | [Changelog](https://github.com/shopware/shopware/blob/v6.6.6.0/changelog/release-6-6-6-0/2024-08-01-add-focus-handling-to-storefront.md)                  | [v6.6.6.0](https://github.com/shopware/shopware/releases/tag/v6.6.6.0)                           |
| Ensure that resizing content up to 200% does not cause breaks                                   | Yes              | [Changelog](https://github.com/shopware/shopware/blob/v6.6.6.0/changelog/release-6-6-6-0/2024-08-13-Improved-storefront-text-scaling.md)                  | [v6.6.6.0](https://github.com/shopware/shopware/releases/tag/v6.6.6.0)                           |
| Language of each Storefront passage or phrase in the content can be programmatically determined | No               | [Changelog](https://github.com/shopware/shopware/blob/v6.6.6.0/changelog/release-6-6-6-0/2024-08-05-add-language-to-reviews.md)                           | [v6.6.6.0](https://github.com/shopware/shopware/releases/tag/v6.6.6.0)                           |
| Check Lighthouse Accessibility Score                                                            | No               | [Changelog](https://github.com/shopware/shopware/blob/v6.6.6.0/changelog/release-6-6-6-0/2024-08-21-fix-scroll-up-button-accessibility.md)                | [v6.6.6.0](https://github.com/shopware/shopware/releases/tag/v6.6.6.0)                           |
| Pagination does not have links                                                                  | Yes              | [Changelog](https://github.com/shopware/shopware/blob/v6.6.6.0/changelog/release-6-6-6-0/2023-08-31-pagination-with-links.md)                             | [v6.6.6.0](https://github.com/shopware/shopware/releases/tag/v6.6.6.0)                           |
| Non-informative document title                                                                  | No               | [Changelog](https://github.com/shopware/shopware/blob/v6.6.1.0/changelog/release-6-6-1-0/2024-03-12-distinctive-document-titles.md)                       | [v6.6.6.0](https://github.com/shopware/shopware/releases/tag/v6.6.1.0)                           |
| The form element quantity selector is not labeled                                               | No               | [Changelog](https://github.com/shopware/shopware/blob/v6.6.5.0/changelog/release-6-6-5-0/2024-07-15-the-form-element-quantity-selector-is-not-labeled.md) | [v6.6.5.0](https://github.com/shopware/shopware/releases/tag/v6.6.5.0)                           |
| Slider reports confusing status changes to screen readers                                       | No               | [Changelog](https://github.com/shopware/shopware/blob/v6.6.4.0/changelog/release-6-6-4-0/2024-05-31-remove-unwanted-aria-live-attributes-from-sliders.md) | [v6.6.4.0](https://github.com/shopware/shopware/releases/tag/v6.6.4.0)                           |
| The user needs to be able to close triggered, additional content                                | No               | [Changelog](https://github.com/shopware/shopware/blob/trunk/changelog/release-6-6-3-0/2024-05-03-esc-key-for-nav-flyout-close.md)                         | [v6.6.3.0](https://github.com/shopware/shopware/releases/tag/v6.6.3.0)                           |
| Improve "Remove Product" button labeling in checkout                                            | No               | [Changelog](https://github.com/shopware/shopware/blob/v6.6.3.0/changelog/release-6-6-3-0/2024-05-03-improve-line-item-labels-and-alt-texts.md)            | [v6.6.3.0](https://github.com/shopware/shopware/releases/tag/v6.6.3.0)                           |
| Missing alternative text for product images in the shopping cart                                | No               | [Changelog](https://github.com/shopware/shopware/blob/v6.6.3.0/changelog/release-6-6-3-0/2024-05-03-improve-line-item-labels-and-alt-texts.md)            | [v6.6.3.0](https://github.com/shopware/shopware/releases/tag/v6.6.3.0)                           |
| A closing mechanism for the navigation                                                          | No               | [Changelog](https://github.com/shopware/shopware/blob/trunk/changelog/release-6-6-3-0/2024-05-03-esc-key-for-nav-flyout-close.md)                         | [v6.6.3.0](https://github.com/shopware/shopware/releases/tag/v6.6.3.0)                           |
| Change shipping toggle in OffCanvas cart to button element                                      | No               | [Changelog](https://github.com/shopware/shopware/blob/v6.6.2.0/changelog/release-6-6-2-0/2024-04-17-change-shipping-costs-toggle-to-button-element.md)    | [v6.6.2.0](https://github.com/shopware/shopware/releases/tag/v6.6.2.0)                           |
| Add heading elements for account login page                                                     | No               | [Changelog](https://github.com/shopware/shopware/blob/v6.6.2.0/changelog/release-6-6-2-0/2024-04-15-heading-elements-on-registration-page.md)             | [v6.6.2.0](https://github.com/shopware/shopware/releases/tag/v6.6.2.0)                           |
| Provide distinctive document titles for each page                                               | No               | [Changelog](https://github.com/shopware/shopware/blob/v6.6.1.0/changelog/release-6-6-1-0/2024-03-12-distinctive-document-titles.md)                       | [v6.6.1.0](https://github.com/shopware/shopware/releases/tag/v6.6.1.0)                           |
| No empty nav element in top-bar                                                                 | Yes              | [Changelog](https://github.com/shopware/shopware/blob/v6.6.1.0/changelog/release-6-6-1-0/2023-03-05-no-empty-nav.md)                                      | [v6.6.1.0](https://github.com/shopware/shopware/releases/tag/v6.6.1.0)                           |
| Update the focus states so that they are clearly visible                                        | No               | [Multiple changes](https://github.com/search?q=repo%3Ashopware%2Fshopware+NEXT-26712\&type=commits)                                                        | [Multiple releases](https://github.com/search?q=repo%3Ashopware%2Fshopware+NEXT-26712\&type=code) |
| Increase compatibility of Storefront with future assistance technologies                        | No               | [Multiple changes](https://github.com/search?q=repo%3Ashopware%2Fshopware+NEXT-26717\&type=commits)                                                        | [Multiple releases](https://github.com/search?q=repo%3Ashopware%2Fshopware+NEXT-26717\&type=code) |
| Content functionality operable through keyboard                                                 | Yes              | [Multiple changes](https://github.com/search?q=repo%3Ashopware%2Fshopware+NEXT-26705\&type=commits)                                                        | [Multiple releases](https://github.com/search?q=repo%3Ashopware%2Fshopware+NEXT-26705\&type=code) |
| No keyboard traps should occur in the Storefront                                                | -                | Verification work without released code changes                                                                                                           | -                                                                                                |
| Mechanism for the user to pause, stop, or hide moving content                                   | -                | Verification work without released code changes                                                                                                           | -                                                                                                |
| Add text to components that only work with icons to identify their purpose                      | -                | -                                                                                                                                                         |
| Check if all non-text content has text alternative and provide if necessary                     | -                | -                                                                                                                                                         |
| Provide error correction suggestions                                                            | -                | -                                                                                                                                                         |
| Text styles needs to be adjusted (line height, paragraph spacing)                               | -                | -                                                                                                                                                         |
| Keyboard/Tabs should work for nav main-navigation-menu                                          | -                | -                                                                                                                                                         |

### Overview of known accessibility issues

[GitHub Issues](https://github.com/shopware/shopware/labels/accessibility)

---

---
url: /docs/products/paas/shopware/fundamentals/account.md
---

# Account

An account represents your access to resources within the Shopware PaaS Native backend environment. The `sw-paas account` commands cover identity inspection, context management, human user memberships, service accounts, and access tokens.

## Identity and roles

To find what resources you have access to via the CLI:

```sh
sw-paas account whoami
```

This shows the currently authenticated user and the roles attached to that user.

For role details at organization level, see [organization guide](./organization.md).

## Context

To avoid repetitive prompts for `organization-id` and `project-id`, you can set a context and the CLI will automatically use these values without asking.

Setting your context streamlines your workflow by eliminating the need to specify these parameters with every command.

```sh
sw-paas account context set
```

Display the current context:

```sh
sw-paas account context show
```

Delete the saved context:

```sh
sw-paas account context delete
```

The context is saved as `context-production.yaml` and stored alongside the main configuration file in the following locations:

|                 | Unix                   | macOS                                      | Windows        |
|-----------------|------------------------|--------------------------------------------|----------------|
| XDG\_CONFIG\_HOME | ~/.config/sw-paas      | ~/Library/Application Support/sw-paas | %LOCALAPPDATA% |
| XDG\_STATE\_HOME  | ~/.local/state/sw-paas | ~/Library/Application Support/sw-paas | %LOCALAPPDATA% |

## Human user access

Human user memberships at organization, project, and application level are managed through `account user`.

List memberships:

```sh
sw-paas account user list
```

Add a user membership:

```sh
sw-paas account user add
```

Remove a user membership:

```sh
sw-paas account user remove
```

Users can also request access themselves:

```sh
sw-paas account user request
sw-paas account user requests list
```

Users with the `account-admin` role can review and resolve pending requests:

```sh
sw-paas account user requests resolve
```

## Service accounts

Service accounts are machine identities for CI/CD pipelines and other automation.
They can also be used to give an external developer temporary access to an application.

Create, list, update, or delete a service account:

```sh
sw-paas account service-account create
sw-paas account service-account list
sw-paas account service-account update
sw-paas account service-account delete
```

Manage service account grants:

```sh
sw-paas account service-account grant list
sw-paas account service-account grant add
sw-paas account service-account grant policies
sw-paas account service-account grant revoke
```

:::warning
Service account tokens can have stricter authorization policies than human users. When using a
strictly scoped token, specify resources with `--organization-id`, `--project-id`, and
`--application-id`. The corresponding `--organization`, `--project`, and `--application` options
accept names, which the CLI resolves to IDs through internal list API calls. These lookups require
additional permissions that a strictly scoped token might not have. To use resource names instead,
grant the service account the `organization:viewer` and `project:viewer` policies.
:::

## Authentication tokens

The `token` command manages access tokens for either your own account or a service account. Personal access tokens can be used for personal scripts. For CI/CD, you should use service accounts.

Personal access tokens inherit the permissions of the user who created them, except the ability to create new tokens. This means any action the user can perform, the personal token can perform as well.

Service account tokens do not inherit the full permissions of the user who created them. They authenticate as the service account and are limited to the permissions granted to that service account.

:::warning
Personal access tokens should be used with caution since they are tied to a user. If someone obtains a personal access token, they can act on behalf of that user with all of their permissions.
:::

### Personal tokens

Generate a new access token:

```sh
sw-paas account token create
```

### Using a Token

To use a token you have multiple options:

```sh
token=<your-token-here>
sw-paas --token $token account whoami
sw-paas --token "<your-token-here>" account whoami

# Set it for the current terminal session
export SW_PAAS_TOKEN=<your-token-here>
sw-paas account whoami
```

### Revoking a Token

Remove a specific token by ID:

```sh
sw-paas account token revoke --token-id abcd-1234
```

### Service account tokens

To manage tokens for a service account, pass `--service-account-id`:

```sh
sw-paas account token create --service-account-id <service-account-id>
sw-paas account token list --service-account-id <service-account-id>
sw-paas account token revoke --service-account-id <service-account-id>
```

---

---
url: /docs/v6.6/products/paas/shopware/CLI/account.md
---

# Account

The `account` command gives you access to account-level operations such as context management, token handling, user-role mapping, and role identification. An **account** represents your access to resources within our backend environment.

## Usage

```sh
sw-paas account [command]
```

## Commands

### Account Context

The `context` command lets you define and manipulate a *context file*, allowing the CLI to skip repetitive prompts for `organization-id` and `project-id`. The default context file is saved as `context-production.yaml` and stored alongside the main config file. Below is the location of where these files are stored.

|                 | Unix                   | MacOS                                      | Windows        |
|-----------------|------------------------|--------------------------------------------|----------------|
| XDG\_CONFIG\_HOME | ~/.config/sw-paas      | ~/Library/Application Support/sw-paas | %LOCALAPPDATA% |
| XDG\_STATE\_HOME  | ~/.local/state/sw-paas | ~/Library/Application Support/sw-paas | %LOCALAPPDATA% |

**Usage:**

```sh
sw-paas account context [command]
```

**Available Subcommands:**

* `set`: Define or update your current context.
* `show`: Display the currently active context values.
* `delete`: Remove the saved context.

**Examples:**

```sh
# Set a new context for organization and project
sw-paas account context set --organization-id org-123 --project-id proj-456

# Set a new context for organization skipping project
sw-paas account context set --organization-id org-123 --skip-project-id

# View the current context
sw-paas account context show

# Delete the current context file
sw-paas account context delete
```

### Authentication Tokens

The `token` command manages personal access tokens for secure API and CLI usage. Tokens can be created, listed, and revoked.

**Usage:**

```sh
sw-paas account token [command]
```

**Available Subcommands:**

* `create`: Generate a new access token.
* `list`: View all your active tokens.
* `revoke`: Remove a specific token.

**Examples:**

```sh
# Create a new token
sw-paas account token create --name "ci-token"

# List all active tokens
sw-paas account token list

# Revoke a token by ID
sw-paas account token revoke --token-id abcd-1234
```

### Users and Roles

Use the `user` command to map users to specific roles within the organization. Only users with sufficient privileges (e.g., admin) can modify roles.

**Usage:**

```sh
sw-paas account user [command]
```

**Available Subcommands:**

* `add`: Add a user to the organization with a specific role.
* `remove`: Remove a user from a role.

If you already have the `project-admin` role and wish to add additional users to your organization, they can share their **user ID (sub-id)** with you. You can instruct them to retrieve it using the following command:

```sh
sw-paas account whoami --output json
```

Or, if they have `jq` installed for easier parsing:

```sh
sw-paas account whoami --output json | jq ".sub"
```

Once you receive their `sub` (subject ID), you can proceed to add them to your organization with the appropriate role.

**Available Roles:**

* `read-only`: Gets access to projects and applications. Only actions allowed are `get` and `list`.
* `developer`: Gets access to projects and applications. All actions are allowed.
* `account-admin`: Gets access to projects and applications. All actions are allowed.
* `project-admin`: Gets access to account management. Actions for managing Users are allowed.

**Examples:**

```sh
# Add a new user as a developer
sw-paas account user add --sub adbs-123 --organization-id abc-123 --role developer

# Remove a user from the developer role
sw-paas account user remove --sub adbs-123 --organization-id abc-123 --role developer
```

### **whoami** – Show Your Identity and Roles

Use the `whoami` command to display your identity, including your User ID(Sub ID), email, and associated policies within the account.

**Usage:**

```sh
sw-paas account whoami
```

This is especially helpful for confirming which roles and permissions are currently active in a given account.

## **Tips**

* Always set a context to reduce repetitive prompts across commands.
* Token management is essential for CI/CD and script-based access. You can use this in environments such as Github Action, CircleCI, GitLab CI, Travis CI etc.
* Use `whoami` to verify access if permission errors occur.

---

---
url: /frontends/frontends-recipes/account.md
---

# Account

Recipes for customer session and account flows.

---

---
url: /docs/products/extensions/b2b-suite/guides/storefront/acl-routing.md
---

# ACL and Routing

The ACL Routing component allows you to block Controller Actions for B2B users.
It relies on and extends the technologies already defined by the ACL component.
To accomplish this, the component directly maps an `action` in a given `controller` to a `resource` (= entity type) and `privilege` (= class of actions).
There are two core actions you should know: `index` and `detail`, as you can see in the following acl-config example below.

## Registering routes

All routes that need access rights need to be stored in the database.
The B2B Suite provides a service to simplify this process.
For it to work correctly, you need an array in a specific format structured like this:

```php
$myAclConfig =  [
    'contingentgroup' => //resource name
    [
        'B2bContingentGroup' => // controller name
        [
            'index' => 'list', // action name => privilege name
            [...]
            'detail' => 'detail',
        ],
    ],
];
```

This configuration array can then be synced to the database by using this service during installation:

```php
Shopware\B2B\AclRoute\Framework\AclRoutingUpdateService::create()
    ->addConfig($myAclConfig);
```

This way, you can easily create and store the resources.
Of course, to show a nice frontend, you must also provide snippets for translation.
The snippets get automatically created from resource and privilege names and are prefixed with `_acl_`.
So the resource `contingentgroup` needs a translation named `_acl_contingentgroup`.

## Privilege names

The default privileges are:

| Privilege name |                                    What it means                                    |
|:--------------:|:-----------------------------------------------------------------------------------:|
|     `list`     |                   Entity listing (e.g. indexActions, gridActions)                   |
|    `detail`    | Disabled forms, lists of assignments, but only the inspection, not the modification |
|    `create`    |                              Creation of new entities                               |
|    `delete`    |                            Removal of existing entities                             |
|    `update`    |                         Updating/changing existing entities                         |
|    `assign`    |                        Changing the assignment of the entity                        |
|     `free`     |                                   No restrictions                                   |

It is quite natural to map CRUD actions like this.
However, the assignment is a little less intuitive.
This should help:

* All assignment controllers belong to the resource on the right side of the assignment (e.g., the `B2BContactRole` controller is part of the `role` resource).
* All assignment listings have the detail privilege (e.g., `B2BContactRole:indexAction` is part of the `detail` privilege).
* All actions writing the assignment are part of the assign privilege (e.g. `B2BContactRole:assignAction` is part of the `assign` privilege).

## Automatic generation

You can autogenerate this format with the `RoutingIndexer`.
This service expects a format that is automatically created by the *IndexerService*.
This could be part of your deployment or testing workflow.

```php
require __DIR__ . '/../B2bContact.php';
$indexer = new Shopware\B2B\AclRoute\Framework\RoutingIndexer();
$indexer->generate(\Shopware_Controllers_Frontend_B2bContact::class, __DIR__ . '/my-acl-config.php');
```

The generated file looks like this:

```php
'NOT_MAPPED' => //resource name
      array(
          'B2bContingentGroup' => // controller name
              array(
                  'index' => 'NOT_MAPPED', // action name => privilege name
                  [...]
                  'detail' => 'NOT_MAPPED',
              ),
      ),
```

If you spot a privilege or resource that is called `NOT_MAPPED`,
the action is new, and you must update the file to add the correct privilege name.

## Template extension

The ACL implementation is safe at the PHP level.
Any route you have no access to will automatically be blocked, but for a better user experience, you should also extend the template to hide inaccessible actions.

```twig
<a href="{{ url("frontend.b2b." ~ page.route ~ ".assign") }}" class="{{ b2b_acl('b2broleaddress', 'assign') }}">
```

This will add a few vital CSS classes:

Allowed actions:

```html
<a [...] class="is--b2b-acl is--b2b-acl-controller-b2broleaddress is--b2b-acl-action-assign is--b2b-acl-allowed"/>
```

Denied actions:

```html
<a [...] class="is--b2b-acl is--b2b-acl-controller-b2broleaddress is--b2b-acl-action-assign is--b2b-acl-forbidden"/>
```

The default behavior is then just to hide the link by setting its display property to `display: none`.

But there are certain specials to this:

* applied to a `form` tag will remove the submit button and disable all form items.
* applied to a table row in the b2b default grid will mute the applied ajax panel action.

## Download

Refer here for [simple example plugin](../example-plugins/B2bAcl.zip).

---

---
url: /docs/v6.5/products/extensions/b2b-suite/guides/storefront/acl-routing.md
---

# ACL and Routing

The ACL Routing component allows you to block Controller Actions for B2B users. It relies on and extends the technologies already defined by the ACL component. To accomplish this, the component directly maps an `action` in a given `controller` to a `resource` (= entity type) and `privilege` (= class of actions). There are two core actions you should know: `index` and `detail`, as you can see in the following acl-config example below.

## Registering routes

All routes that need access rights need to be stored in the database. The B2B Suite provides a service to simplify this process. For it to work correctly, you need an array in a specific format structured like this:

```php
$myAclConfig =  [
    'contingentgroup' => //resource name
    [
        'B2bContingentGroup' => // controller name
        [
            'index' => 'list', // action name => privilege name
            [...]
            'detail' => 'detail',
        ],
    ],
];
```

This configuration array can then be synced to the database by using this service during installation:

```php
Shopware\B2B\AclRoute\Framework\AclRoutingUpdateService::create()
    ->addConfig($myAclConfig);
```

This way, you can easily create and store the resources. Of course, to show a nice frontend, you must also provide snippets for translation. The snippets get automatically created from resource and privilege names and are prefixed with `_acl_`. So the resource `contingentgroup` needs a translation named `_acl_contingentgroup`.

## Privilege names

The default privileges are:

| Privilege name |                                    What it means                                    |
|:----------------:|:-----------------------------------------------------------------------------------:|
| `list`           |                  Entity listing (e.g. indexActions, gridActions)                   |
| `detail`         | Disabled forms, lists of assignments, but only the inspection, not the modification |
| `create`         |                              Creation of new entities                               |
| `delete`         |                           Removal of existing entities                             |
| `update`         |                         Updating/changing existing entities                         |
| `assign`         |                        Changing the assignment of the entity                        |
| `free`           |                                   No restrictions                                   |

It is quite natural to map CRUD actions like this. However, the assignment is a little less intuitive. This should help:

* All assignment controllers belong to the resource on the right side of the assignment (e.g., the `B2BContactRole` controller is part of the `role` resource).
* All assignment listings have the detail privilege (e.g., `B2BContactRole:indexAction` is part of the `detail` privilege).
* All actions writing the assignment are part of the assign privilege (e.g. `B2BContactRole:assignAction` is part of the `assign` privilege).

## Automatic generation

You can autogenerate this format with the `RoutingIndexer`. This service expects a format that is automatically created by the *IndexerService*.
This could be part of your deployment or testing workflow.

```php
require __DIR__ . '/../B2bContact.php';
$indexer = new Shopware\B2B\AclRoute\Framework\RoutingIndexer();
$indexer->generate(\Shopware_Controllers_Frontend_B2bContact::class, __DIR__ . '/my-acl-config.php');
```

The generated file looks like this:

```php
'NOT_MAPPED' => //resource name
      array(
          'B2bContingentGroup' => // controller name
              array(
                  'index' => 'NOT_MAPPED', // action name => privilege name
                  [...]
                  'detail' => 'NOT_MAPPED',
              ),
      ),
```

If you spot a privilege or resource that is called `NOT_MAPPED`,
the action is new, and you must update the file to add the correct privilege name.

## Template extension

The ACL implementation is safe at the PHP level. Any route you have no access to will automatically be blocked, but for a better user experience, you should also extend the template to hide inaccessible actions.

```twig
<a href="{{ url("frontend.b2b." ~ page.route ~ ".assign") }}" class="{{ b2b_acl('b2broleaddress', 'assign') }}">
```

This will add a few vital CSS classes:

Allowed actions:

```html
<a [...] class="is--b2b-acl is--b2b-acl-controller-b2broleaddress is--b2b-acl-action-assign is--b2b-acl-allowed"/>
```

Denied actions:

```html
<a [...] class="is--b2b-acl is--b2b-acl-controller-b2broleaddress is--b2b-acl-action-assign is--b2b-acl-forbidden"/>
```

The default behavior is then just to hide the link by setting its display property to `display: none`.

But there are certain specials to this:

* applied to a `form` tag will remove the submit button and disable all form items.
* applied to a table row in the b2b default grid will mute the applied ajax panel action.

## Download

Refer here for [simple example plugin](../../../../../../products/extensions/b2b/b2b-suite/guides/example-plugins/B2bAcl.zip).

---

---
url: /docs/v6.6/products/extensions/b2b-suite/guides/storefront/acl-routing.md
---

# ACL and Routing

The ACL Routing component allows you to block Controller Actions for B2B users.
It relies on and extends the technologies already defined by the ACL component.
To accomplish this, the component directly maps an `action` in a given `controller` to a `resource` (= entity type) and `privilege` (= class of actions).
There are two core actions you should know: `index` and `detail`, as you can see in the following acl-config example below.

## Registering routes

All routes that need access rights need to be stored in the database.
The B2B Suite provides a service to simplify this process.
For it to work correctly, you need an array in a specific format structured like this:

```php
$myAclConfig =  [
    'contingentgroup' => //resource name
    [
        'B2bContingentGroup' => // controller name
        [
            'index' => 'list', // action name => privilege name
            [...]
            'detail' => 'detail',
        ],
    ],
];
```

This configuration array can then be synced to the database by using this service during installation:

```php
Shopware\B2B\AclRoute\Framework\AclRoutingUpdateService::create()
    ->addConfig($myAclConfig);
```

This way, you can easily create and store the resources.
Of course, to show a nice frontend, you must also provide snippets for translation.
The snippets get automatically created from resource and privilege names and are prefixed with `_acl_`.
So the resource `contingentgroup` needs a translation named `_acl_contingentgroup`.

## Privilege names

The default privileges are:

| Privilege name |                                    What it means                                    |
|:--------------:|:-----------------------------------------------------------------------------------:|
|     `list`     |                   Entity listing (e.g. indexActions, gridActions)                   |
|    `detail`    | Disabled forms, lists of assignments, but only the inspection, not the modification |
|    `create`    |                              Creation of new entities                               |
|    `delete`    |                            Removal of existing entities                             |
|    `update`    |                         Updating/changing existing entities                         |
|    `assign`    |                        Changing the assignment of the entity                        |
|     `free`     |                                   No restrictions                                   |

It is quite natural to map CRUD actions like this.
However, the assignment is a little less intuitive.
This should help:

* All assignment controllers belong to the resource on the right side of the assignment (e.g., the `B2BContactRole` controller is part of the `role` resource).
* All assignment listings have the detail privilege (e.g., `B2BContactRole:indexAction` is part of the `detail` privilege).
* All actions writing the assignment are part of the assign privilege (e.g. `B2BContactRole:assignAction` is part of the `assign` privilege).

## Automatic generation

You can autogenerate this format with the `RoutingIndexer`.
This service expects a format that is automatically created by the *IndexerService*.
This could be part of your deployment or testing workflow.

```php
require __DIR__ . '/../B2bContact.php';
$indexer = new Shopware\B2B\AclRoute\Framework\RoutingIndexer();
$indexer->generate(\Shopware_Controllers_Frontend_B2bContact::class, __DIR__ . '/my-acl-config.php');
```

The generated file looks like this:

```php
'NOT_MAPPED' => //resource name
      array(
          'B2bContingentGroup' => // controller name
              array(
                  'index' => 'NOT_MAPPED', // action name => privilege name
                  [...]
                  'detail' => 'NOT_MAPPED',
              ),
      ),
```

If you spot a privilege or resource that is called `NOT_MAPPED`,
the action is new, and you must update the file to add the correct privilege name.

## Template extension

The ACL implementation is safe at the PHP level.
Any route you have no access to will automatically be blocked, but for a better user experience, you should also extend the template to hide inaccessible actions.

```twig
<a href="{{ url("frontend.b2b." ~ page.route ~ ".assign") }}" class="{{ b2b_acl('b2broleaddress', 'assign') }}">
```

This will add a few vital CSS classes:

Allowed actions:

```html
<a [...] class="is--b2b-acl is--b2b-acl-controller-b2broleaddress is--b2b-acl-action-assign is--b2b-acl-allowed"/>
```

Denied actions:

```html
<a [...] class="is--b2b-acl is--b2b-acl-controller-b2broleaddress is--b2b-acl-action-assign is--b2b-acl-forbidden"/>
```

The default behavior is then just to hide the link by setting its display property to `display: none`.

But there are certain specials to this:

* applied to a `form` tag will remove the submit button and disable all form items.
* applied to a table row in the b2b default grid will mute the applied ajax panel action.

## Download

Refer here for [simple example plugin](../example-plugins/B2bAcl.zip).

---

---
url: /resources/admin-extension-sdk/api-reference/ui/actionButton.md
---

# Action Button

An action button adds a clickable button to an existing area of the Shopware Administration.

Action buttons are typically used to trigger extension-specific actions such as opening a modal, executing a workflow, or navigating to an extension module.

## actionButton.add()

#### Usage

```ts
import { location, ui } from "@shopware-ag/meteor-admin-sdk";

if (location.is(location.MAIN_HIDDEN)) {
  ui.actionButton.add({
    name: "your-app_customer-detail-action",
    entity: "customer",
    view: "detail",
    label: "Test action",
    callback: (entity, entityIds) => {
      // TODO: do something
    },
  });
}
```

#### Parameters

| Name         | Required | Description                                                                                                                                                                       |
| :----------- | :------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`       | true     | A unique identifier for your action                                                                                                                                                |
| `entity`     | true     | The entity this action is for possible values: `product`, `order`, `category`, `promotion`, `customer` or `media`. Value `media` is available in Shopware version 6.7.1           |
| `view`       | true     | Determines if the action button appears on the listing or detail page, possible values: `detail`,`list` or item. View `item` is only used for entity `media` and in version 6.7.1 |
| `label`      | true     | The label of your action button                                                                                                                                                   |
| `meteorIcon` | false    | Meteor icon before label. Available since Shopware v6.7.4.0. Check icon name on https://developer.shopware.com/resources/meteor-icon-kit/                                         |
| `fileTypes`  | false    | Media file types you want the action button to be displayed for. Available since Shopware v6.7.6.0.                                                                               |
| `callback`   | true     | The callback function where you receive the entity and the entityIds for further processing                                                                                       |

#### Return value

Returns a promise without data.

## Calling app actions

As an app developer you may want to receive the information of the callback function server side.
The following example will render the same action button as the above example but once it gets clicked you will receive a POST request to your app server.

**This will only work for apps. Plugin developers must use an API client directly in their callback.**.

```ts
import { location, ui } from "@shopware-ag/meteor-admin-sdk";

if (location.is(location.MAIN_HIDDEN)) {
  ui.actionButton.add({
    name: "your-app_customer-detail-action",
    entity: "customer",
    view: "detail",
    label: "Test action",
    callback: (entity /* "customer" */, entityIds /* ["..."] */) => {
      app.webhook.actionExecute({
        url: "http://your-app.com/customer-detail-action",
        entityIds,
        entity,
      });
    },
  });
}
```

## Example: Add action button in customer detail page

![Action button example](./assets/add-action-button-example.png)

```ts
import { ui } from "@shopware-ag/meteor-admin-sdk";

ui.actionButton.add({
  name: "your-app_customer-detail-action",
  entity: "customer",
  view: "detail",
  meteorIcon: "regular-analytics",
  label: "Test action",
  callback: (entity /* "customer" */, entityIds /* ["..."] */) => {
    app.webhook.actionExecute({
      url: "http://your-app.com/customer-detail-action",
      entityIds,
      entity,
    });
  },
});
```

## Example: Add action button in media item

![Action button media example](./assets/add-action-button-media-example.png)

```ts
import { ui } from "@shopware-ag/meteor-admin-sdk";

ui.actionButton.add({
  name: "test-media-button",
  entity: "media",
  view: "item",
  meteorIcon: "regular-tools-alt",
  label: "Open in Image editor",
  callback: (entity /* "media" */, entityIds /* ["..."] */) => {
    // TODO: Navigate to image editor app
  },
});
```

---

---
url: /docs/v6.5/guides/plugins/plugins/framework/flow/action-transactions.md
---

# Action transactions

## Overview

In this guide, you will learn how to run your action code inside a transaction. This may be important for you if you want to graciously handle rollbacks in certain scenarios. We have implemented various abstractions to ease this process; however, you need to opt in.

For some more background, please see the ADR [Action Transactions](../../../../../resources/references/adr/2024-02-11-transactional-flow-actions).

## Prerequisites

In order to make your action run inside a database transaction, you will need an existing Flow Action. Therefore, you can refer to the [Add Flow Builder Action Guide.](./add-flow-builder-action)

## Run your action inside a transaction

All you have to do is to implement the `Shopware\Core\Content\Flow\Dispatching\TransactionalAction` interface. It does not have any methods to implement.

When your action implements the interface the Flow Dispatcher will wrap your action in a transaction. If an exception is thrown, it will be caught, the transaction will be rolled back, and an error is logged.

::: code-group

```php [{plugin root}/src/Core/Content/Flow/Dispatching/Action/CreateTagAction.php]
<?php declare(strict_types=1);

namespace Swag\CreateTagAction\Core\Content\Flow\Dispatching\Action;

use Shopware\Core\Content\Flow\Dispatching\Action\FlowAction;
use Shopware\Core\Content\Flow\Dispatching\TransactionalAction;

class CreateTagAction extends FlowAction implements TransactionalAction
{
    public function handleFlow(StorableFlow $flow): void
    {        
        //do stuff - will be wrapped in a transaction
    }  
}
```

:::

## Force a rollback

You can also force the Flow Dispatcher to roll back the transaction by throwing an instance of `\Shopware\Core\Content\Flow\Dispatching\TransactionFailedException`. You can use the static `because` method to create the exception from another one. Eg:

::: code-group

```php [{plugin root}/src/Core/Content/Flow/Dispatching/Action/CreateTagAction.php]
<?php declare(strict_types=1);

namespace Swag\CreateTagAction\Core\Content\Flow\Dispatching\Action;

use Shopware\Core\Content\Flow\Dispatching\Action\FlowAction;
use Shopware\Core\Content\Flow\Dispatching\TransactionalAction;

class CreateTagAction extends FlowAction implements TransactionalAction
{
    public function handleFlow(StorableFlow $flow): void
    {        
        try {
            //search for some record
            $entity = $this->repo->find(...);
        } catch (NotFoundException $e) {
            throw TransactionFailedException::because($e);
        }
    }  
}
```

## Under what circumstances will the transaction be rolled back?

The transaction will be rollback if either of the following are true:

1. If Doctrine throws an instance of `Doctrine\DBAL\Exception` during commit.
2. If the action throws an instance of `TransactionFailedException` during execution.
3. If another non-handled exception is thrown during the action execution.

If the transaction fails, then an error will be logged.

Also, if the transaction has been performed inside a nested transaction without save points enabled (which is the default in Shopware), the exception will be rethrown.
This is because the calling code knows something went wrong and is able to handle it correctly, by rolling back instead of committing. In this scenario, the connection will be marked as rollback only.

---

---
url: /docs/v6.6/guides/plugins/plugins/framework/flow/action-transactions.md
---

# Action transactions

## Overview

In this guide, you will learn how to run your action code inside a transaction. This may be important for you if you want to graciously handle rollbacks in certain scenarios. We have implemented various abstractions to ease this process; however, you need to opt in.

For some more background, please see the ADR [Action Transactions](../../../../../resources/references/adr/2024-02-11-transactional-flow-actions).

## Prerequisites

In order to make your action run inside a database transaction, you will need an existing Flow Action. Therefore, you can refer to the [Add Flow Builder Action Guide.](./add-flow-builder-action)

## Run your action inside a transaction

All you have to do is to implement the `Shopware\Core\Content\Flow\Dispatching\TransactionalAction` interface. It does not have any methods to implement.

When your action implements the interface the Flow Dispatcher will wrap your action in a transaction. If an exception is thrown, it will be caught, the transaction will be rolled back, and an error is logged.

::: code-group

```php [{plugin root}/src/Core/Content/Flow/Dispatching/Action/CreateTagAction.php]
<?php declare(strict_types=1);

namespace Swag\CreateTagAction\Core\Content\Flow\Dispatching\Action;

use Shopware\Core\Content\Flow\Dispatching\Action\FlowAction;
use Shopware\Core\Content\Flow\Dispatching\TransactionalAction;

class CreateTagAction extends FlowAction implements TransactionalAction
{
    public function handleFlow(StorableFlow $flow): void
    {        
        //do stuff - will be wrapped in a transaction
    }  
}
```

:::

## Force a rollback

You can also force the Flow Dispatcher to roll back the transaction by throwing an instance of `\Shopware\Core\Content\Flow\Dispatching\TransactionFailedException`. You can use the static `because` method to create the exception from another one. Eg:

::: code-group

```php [{plugin root}/src/Core/Content/Flow/Dispatching/Action/CreateTagAction.php]
<?php declare(strict_types=1);

namespace Swag\CreateTagAction\Core\Content\Flow\Dispatching\Action;

use Shopware\Core\Content\Flow\Dispatching\Action\FlowAction;
use Shopware\Core\Content\Flow\Dispatching\TransactionalAction;

class CreateTagAction extends FlowAction implements TransactionalAction
{
    public function handleFlow(StorableFlow $flow): void
    {        
        try {
            //search for some record
            $entity = $this->repo->find(...);
        } catch (NotFoundException $e) {
            throw TransactionFailedException::because($e);
        }
    }  
}
```

## Under what circumstances will the transaction be rolled back?

The transaction will be rollback if either of the following are true:

1. If Doctrine throws an instance of `Doctrine\DBAL\Exception` during commit.
2. If the action throws an instance of `TransactionFailedException` during execution.
3. If another non-handled exception is thrown during the action execution.

If the transaction fails, then an error will be logged.

Also, if the transaction has been performed inside a nested transaction without save points enabled (which is the default in Shopware), the exception will be rethrown.
This is because the calling code knows something went wrong and is able to handle it correctly, by rolling back instead of committing. In this scenario, the connection will be marked as rollback only.

---

---
url: /docs/resources/references/core-reference/actions-reference.md
---
# Actions Reference

## B2B

| Class                                           | Description                                                    | Component           |
|:------------------------------------------------|:---------------------------------------------------------------|:--------------------|
| ChangeEmployeeStatusAction                      | Assigns the configured status to the employee                  | Employee Management |
| ChangeCustomerSpecificFeaturesAction            | Adds or removes the configured b2b components for the customer | Employee Management |

---

---
url: /docs/v6.5/resources/references/core-reference/actions-reference.md
---
# Actions Reference

## B2B

| Class                                           | Description                                                    | Component           |
|:------------------------------------------------|:---------------------------------------------------------------|:--------------------|
| ChangeEmployeeStatusAction                      | Assigns the configured status to the employee                  | Employee Management |
| ChangeCustomerSpecificFeaturesAction            | Adds or removes the configured b2b components for the customer | Employee Management |

---

---
url: /docs/v6.6/resources/references/core-reference/actions-reference.md
---
# Actions Reference

## B2B

| Class                                           | Description                                                    | Component           |
|:------------------------------------------------|:---------------------------------------------------------------|:--------------------|
| ChangeEmployeeStatusAction                      | Assigns the configured status to the employee                  | Employee Management |
| ChangeCustomerSpecificFeaturesAction            | Adds or removes the configured b2b components for the customer | Employee Management |

---

---
url: /docs/guides/development/testing/e2e-playwright/actor-pattern.md
---

# Actor pattern

The actor pattern is a basic concept that we added to our test suite. It is something not related to Playwright, but similar concepts exist in other testing frameworks. We implemented it to create reusable test logic that can be used in a human-readable form, without abstracting away Playwright as a framework. So you are free to use it or not. Any standard Playwright functionality will still be usable in your tests.

The concept adds two new entities besides the already mentioned [page objects](./page-object.md)

* **Actor**: A specific user with a given context performing actions (tasks) inside the application.
* **Task**: A specific action performed by an actor.
* **Pages**: A page of the application on which an actor performs a task.

## Actors

The Actor class is a lightweight solution to simplify the execution of reusable test logic or navigate to a specific page.

## Properties

* `name`: The human-readable name of the actor.
* `page`: A Playwright page context that the actor is navigating.

## Primary methods

* `goesTo`: Accepts a URL of a page the actor should navigate to.
* `attemptsTo`: Accepts a "task" function with reusable test logic that the actor should perform.
* `expects`: A one-to-one export of the Playwright `expect` method to use it in the actor pattern.

These methods lead to the following pattern:

* The **actor** *goes to* a **page**.
* The **actor** *attempts to* perform a certain **task**.
* The **actor** *expects* a certain result.

Translated into test code, this pattern can look like this:

```typescript
import { test } from "./../BaseTestFile";

test("Product detail test scenario", async ({
  ShopCustomer,
  StorefrontProductDetail,
  TestDataService,
}) => {
  const product = await TestDataService.createBasicProduct();

  await ShopCustomer.goesTo(StorefrontProductDetail.url(product));
  await ShopCustomer.attemptsTo(AddProductToCart(product));
  await ShopCustomer.expects(
    StorefrontProductDetail.offCanvasSummaryTotalPrice
  ).toHaveText("€99.99*");
});
```

In this example, you can see that this pattern creates very comprehensible tests, even for non-tech people. They also make it easier to abstract simple test logic that might be used in different scenarios into executable tasks, like adding a product to the cart.

The test suite offers two different actors by default:

* `ShopCustomer`: A user that is navigating the Storefront.
* `ShopAdmin`: A user who manages Shopware via the Administration.

## Accessibility methods

* `a11y_checks`: Accepts a locator and verifies if the desired locator is both focused and displays a visible focus indicator. This is automatically called via `presses`, `fillsIn`, and `selectsRadioButton`.
* `presses`: An extension of the Playwright `press` method to include `a11y_checks` as well as automatically apply a keyboard key press per default browser keyboard mappings (which can also be overridden). A keyboard focused alternative to the Playwright `click` method.
* `fillsIn`: An extension of the Playwright `fill` method to include `a11y_checks`.
* `selectsRadioButton`: Selects radio buttons using keyboard navigation in addition to verifying visible focus (via `presses`).

These methods serve as a way to enforce better accessibility practices by using keyboard navigation and checking for visible focus indicators (both of which are WCAG requirements). They can be used both in tests and tasks.

:::info
Be aware that the Playwright `click` method automatically includes a number of [actionability checks](https://playwright.dev/docs/actionability) to combat flakiness. When utilizing the Actor accessibility methods, you may need to adjust your tests to individually assert some of these actionability checks for certain locators yourself.
:::

## Tasks

Tasks are small chunks of reusable test logic that can be passed to the `attemptsTo` method of an actor. They are created via Playwright fixtures and have access to the same dependencies. Every executed task will automatically be wrapped in a test step of Playwright, so you get nicely structured reports of your tests.

**Basic Example**

```typescript
import { test as base } from "@playwright/test";
import type { Task } from "../../../types/Task";
import type { FixtureTypes } from "../../../types/FixtureTypes";
import type { Customer } from "../../../types/ShopwareTypes";

export const Login = base.extend<{ Login: Task }, FixtureTypes>({
  Login: async (
    {
      ShopCustomer,
      DefaultSalesChannel,
      StorefrontAccountLogin,
      StorefrontAccount,
    },
    use
  ) => {
    const task = (customCustomer?: Customer) => {
      return async function Login() {
        const customer = customCustomer
          ? customCustomer
          : DefaultSalesChannel.customer;

        await ShopCustomer.goesTo(StorefrontAccountLogin.url());

        await ShopCustomer.fillsIn(
          StorefrontAccountLogin.emailInput,
          customer.email
        );
        await ShopCustomer.fillsIn(
          StorefrontAccountLogin.passwordInput,
          customer.password
        );
        await ShopCustomer.presses(StorefrontAccountLogin.loginButton);

        await ShopCustomer.expects(
          StorefrontAccount.personalDataCardTitle
        ).toBeVisible();
      };
    };

    await use(task);
  },
});
```

This fixture is the "Login" task and performs a simple Storefront login of the default customer via keyboard navigation (automatically includes `a11y_checks` assertions). Every time we need a logged-in shop customer, we can simply reuse this logic in our test.

```typescript
import { test } from "./../BaseTestFile";

test("Customer login test scenario", async ({ ShopCustomer, Login }) => {
  await ShopCustomer.attemptsTo(Login());
});
```

To keep tests easily readable, use names for your tasks so that in the test itself, the code line resembles the `Actor.attemptsTo(doSomething)` pattern as closely as possible.

```typescript
// Bad example
await ShopCustomer.attemptsTo(ProductCart);

// Better example
await ShopCustomer.attemptsTo(PutProductIntoCart);
```

**Page Object Model Example**

```typescript
import type { Page, Locator } from "playwright-core";
import type { PageObject } from "../../types/PageObject";

export class CheckoutConfirm implements PageObject {
  public readonly paymentMethodRadioGroup: Locator;
  public readonly page: Page;

  constructor(page: Page) {
    this.page = page;
    this.paymentMethodRadioGroup = page.locator(".checkout-card", {
      hasText: "Payment Method",
    });
  }

  url() {
    return "checkout/confirm";
  }
}
```

This page object defines the payment method radio group locator.

```typescript
import { test as base } from "@playwright/test";
import type { Task } from "../../../types/Task";
import type { FixtureTypes } from "../../../types/FixtureTypes";

export const SelectPaymentMethod = base.extend<
  { SelectPaymentMethod: Task },
  FixtureTypes
>({
  SelectPaymentMethod: async (
    { ShopCustomer, StorefrontCheckoutConfirm },
    use
  ) => {
    const task = (paymentOptionName: string) => {
      return async function SelectPaymentMethod() {
        const paymentMethods =
          StorefrontCheckoutConfirm.paymentMethodRadioGroup;
        const paymentOptionRadioButton = paymentMethods.getByRole("radio", {
          name: paymentOptionName,
        });

        await ShopCustomer.selectsRadioButton(
          paymentMethods,
          paymentOptionName
        );
        await ShopCustomer.expects(paymentOptionRadioButton).toBeChecked();
      };
    };

    await use(task);
  },
});
```

This fixture is the "SelectPaymentMethod" task, which selects the desired radio button in the `paymentMethodRadioGroup` defined in the page object using keyboard navigation (automatically includes `a11y_checks` assertions).

To use "SelectPaymentMethod" in a test, you simply pass the name of the desired payment option. Here is a sample scenario for a successful checkout that demonstrates how to combine multiple tasks to build your test scenarios.

```typescript
import { test } from "./../BaseTestFile";

test("Customer successfully orders product", async ({
  ShopCustomer,
  TestDataService,
  Login,
  StorefrontProductDetail,
  AddProductToCart,
  ProceedFromProductToCheckout,
  SelectPaymentMethod,
  ConfirmOrder,
}) => {
  const product = await TestDataService.createBasicProduct();
  await ShopCustomer.attemptsTo(Login());
  await ShopCustomer.goesTo(StorefrontProductDetail.url(product));
  await ShopCustomer.attemptsTo(AddProductToCart(product));
  await ShopCustomer.attemptsTo(ProceedFromProductToCheckout());
  await ShopCustomer.attemptsTo(SelectPaymentMethod("Invoice"));
  await ShopCustomer.attemptsTo(ConfirmOrder());
});
```

You can create your tasks in the same way to make them available for the actor pattern. Every task is just a simple Playwright fixture containing a function call with the corresponding test logic. Make sure to merge your task fixtures with other fixtures you created in your base test file. You can use the `mergeTests` method of Playwright to combine several fixtures into one test extension. Use `/src/tasks/shop-customer-tasks.ts` or `/src/tasks/shop-admin-tasks.ts` for that.

---

---
url: /docs/products/extensions/advanced-search/How-to-modify-completion.md
---

# Add / Modify Completion

The Advanced Search does not use the default Elasticsearch completion because it only supports a fixed order and the storage size is high. As an alternative, Advanced Search uses aggregations to find the most important word combinations for your search input.

## Adding completion to your definition mapping

To index our own completion keywords, we need to inject `Shopware\Commercial\AdvancedSearch\Domain\Completion\CompletionDefinitionEnrichment` into your ES definition and call enrich methods in `getMapping` and `fetch` as following example:

Example:

*The definition is from the [previous example](./How-to-define-your-custom-Elasticsearch-definition):*

```php
<?php declare(strict_types=1);

class YourCustomElasticsearchDefinition extends AbstractElasticsearchDefinition
{
    public function __construct(
        private readonly EntityDefinition $definition,
        private readonly Connection $connection,
        private readonly AbstractSearchLogic $searchLogic,
        private readonly CompletionDefinitionEnrichment $completionDefinitionEnrichment,
        private readonly array $languageAnalyzerMapping
    ) {
    }

    public function getMapping(Context $context): array
    {
        // ...
        
        return [
            '_source' => ['includes' => ['id']],
            // to add the mapping of completion field in your definition
            'properties' => array_merge($properties, $this->completionDefinitionEnrichment->enrichMapping()),
        ];
    }

    public function fetch(array $ids, Context $context): array
    {
        // ...

        // to add the completion keywords to the existing data
        return $this->completionDefinitionEnrichment->enrichData($this->getEntityDefinition(), $documents);
    }
}
```

## Add/modify completion keywords

By default, each of Shopware's ES definitions has a set of `string` fields to be considered as completion keywords. This configuration is realized via the parameter `%advanced_search.completion%`, if the configured fields for your definition are not set, all StringFields of the definition will be used as completion keywords.

For example, you can add or modify this configuration in `config/packages/advanced_search.yaml`:

```yaml
advanced_search:
    completion:
        your_custom_entity:
            - email
            - company
```

If you want to have more control over the completion, such as using static texts from files or parsing a field from another data source as completion keywords, you might want to decorate the service `\Shopware\Commercial\AdvancedSearch\Domain\Completion\CompletionDefinitionEnrichment::enrichData` instead.

---

---
url: /docs/v6.5/products/extensions/advanced-search/How-to-modify-completion.md
---

# Add / Modify Completion

The Advanced Search does not use the default Elasticsearch completion because it only supports a fixed order and the storage size is high. As an alternative, Advanced Search uses aggregations to find the most important word combinations for your search input.

## Adding completion to your definition mapping:

To index our own completion keywords, we need to inject `Shopware\Commercial\AdvancedSearch\Domain\Completion\CompletionDefinitionEnrichment` into your ES definition and call enrich methods in `getMapping` and `fetch` as following example:

Example:

*The definition is from the [previous example](./How-to-define-your-custom-Elasticsearch-definition):*

```php
<?php declare(strict_types=1);

class YourCustomElasticsearchDefinition extends AbstractElasticsearchDefinition
{
    public function __construct(
        private readonly EntityDefinition $definition,
        private readonly Connection $connection,
        private readonly AbstractSearchLogic $searchLogic,
        private readonly CompletionDefinitionEnrichment $completionDefinitionEnrichment,
        private readonly array $languageAnalyzerMapping
    ) {
    }

    public function getMapping(Context $context): array
    {
        // ...
        
        return [
            '_source' => ['includes' => ['id']],
            // to add the mapping of completion field in your definition
            'properties' => array_merge($properties, $this->completionDefinitionEnrichment->enrichMapping()),
        ];
    }

    public function fetch(array $ids, Context $context): array
    {
        // ...

        // to add the completion keywords to the existing data
        return $this->completionDefinitionEnrichment->enrichData($this->getEntityDefinition(), $documents);
    }
}
```

## Add/modify completion keywords

By default, each of Shopware's ES definitions has a set of `string` fields to be considered as completion keywords. This configuration is realized via the parameter `%advanced_search.completion%`, if the configured fields for your definition are not set, all StringFields of the definition will be used as completion keywords. 

For example, you can add or modify this configuration in `config/packages/advanced_search.yaml`:

```yaml
advanced_search:
    completion:
        your_custom_entity:
            - email
            - company
```

If you want to have more control over the completion, such as using static texts from files or parsing a field from another data source as completion keywords, you might want to decorate the service `\Shopware\Commercial\AdvancedSearch\Domain\Completion\CompletionDefinitionEnrichment::enrichData` instead.

---

---
url: /docs/v6.6/products/extensions/advanced-search/How-to-modify-completion.md
---

# Add / Modify Completion

The Advanced Search does not use the default Elasticsearch completion because it only supports a fixed order and the storage size is high. As an alternative, Advanced Search uses aggregations to find the most important word combinations for your search input.

## Adding completion to your definition mapping

To index our own completion keywords, we need to inject `Shopware\Commercial\AdvancedSearch\Domain\Completion\CompletionDefinitionEnrichment` into your ES definition and call enrich methods in `getMapping` and `fetch` as following example:

Example:

*The definition is from the [previous example](./How-to-define-your-custom-Elasticsearch-definition):*

```php
<?php declare(strict_types=1);

class YourCustomElasticsearchDefinition extends AbstractElasticsearchDefinition
{
    public function __construct(
        private readonly EntityDefinition $definition,
        private readonly Connection $connection,
        private readonly AbstractSearchLogic $searchLogic,
        private readonly CompletionDefinitionEnrichment $completionDefinitionEnrichment,
        private readonly array $languageAnalyzerMapping
    ) {
    }

    public function getMapping(Context $context): array
    {
        // ...
        
        return [
            '_source' => ['includes' => ['id']],
            // to add the mapping of completion field in your definition
            'properties' => array_merge($properties, $this->completionDefinitionEnrichment->enrichMapping()),
        ];
    }

    public function fetch(array $ids, Context $context): array
    {
        // ...

        // to add the completion keywords to the existing data
        return $this->completionDefinitionEnrichment->enrichData($this->getEntityDefinition(), $documents);
    }
}
```

## Add/modify completion keywords

By default, each of Shopware's ES definitions has a set of `string` fields to be considered as completion keywords. This configuration is realized via the parameter `%advanced_search.completion%`, if the configured fields for your definition are not set, all StringFields of the definition will be used as completion keywords.

For example, you can add or modify this configuration in `config/packages/advanced_search.yaml`:

```yaml
advanced_search:
    completion:
        your_custom_entity:
            - email
            - company
```

If you want to have more control over the completion, such as using static texts from files or parsing a field from another data source as completion keywords, you might want to decorate the service `\Shopware\Commercial\AdvancedSearch\Domain\Completion\CompletionDefinitionEnrichment::enrichData` instead.

---

---
url: >-
  /docs/products/extensions/advanced-search/How-to-add-modify-language-analyzers-stopwords-stemmer.md
---

# Add / Modify language analyzers, stopwords, stemmer

With the introduction of the multi-language index, support for built-in [Elasticsearch language analyzers](https://www.elastic.co/docs/reference/text-analysis/analysis-lang-analyzer) was also introduced.

This would help language-based fields have different analyzers for each language's specific features, like stopwords, stemmers, and normalization, out of the box.

You can also add more or customize the language analyzer by overriding the analyzer parameter in `custom/plugins/SwagCommercial/src/AdvancedSearch/Resources/config/packages/advanced_search.yaml`

For example:

```yaml
advanced_search:
    analysis:
        analyzer:
            sw_your_custom_language_analyzer:
                type: custom
                tokenizer: standard
                filter: ['lowercase', 'my_stopwords_filter', 'my_stemmer_filter']
    filter:
        my_stopwords_filter:
            type: 'stop'
            stopwords: ['foo', 'bar']
        my_stemmer_filter:
            type: 'stemmer'
            language: 'english'
    # It's important to map your analyzer with the language iso code
    language_analyzer_mapping:
        custom_iso: sw_your_custom_language_analyzer
```

## Compound-word decomposition

German catalogs often contain closed compound nouns (for example `Lederjacke` or `Akkubohrer`). Without decomposition, a search for `Jacke` does not match a product named `Lederjacke`.

Since Commercial 7.12.0, Advanced Search ships a `dictionary_decompounder` filter that splits compound words into their parts at index time, using an editable, per-language dictionary. A curated German root-word dictionary is seeded by default. Decomposition is applied at index time only, on the technical-term index analyzer (`sw_<iso>_technical_term_index_analyzer`); the search query itself is never expanded into its parts.

The dictionaries are stored as entities and can be managed through the Admin API:

* `advanced_search_compound_dictionary` — the `wordList` of root words used to split compounds.
* `advanced_search_stopword_dictionary` — custom `stopwords`, which are stripped at both index and search time.

After editing a dictionary, run `bin/console es:index` so the updated analyzer configuration is applied to the index.

---

---
url: >-
  /docs/v6.5/products/extensions/advanced-search/How-to-add-modify-language-analyzers-stopwords-stemmer.md
---

# Add / Modify language analyzers, stopwords, stemmer

With the introduction of the multi-language index, support for built-in [Elasticsearch language analyzers](https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis-lang-analyzer.html) was also introduced.

This would help language-based fields have different analyzers for each language's specific features, like stopwords, stemmers, and normalization, out of the box.

You can also add more or customize the language analyzer by overriding the analyzer parameter in `custom/plugins/SwagCommercial/src/AdvancedSearch/Resources/config/packages/advanced_search.yaml`

For example:

```yaml
advanced_search:
    analysis:
        analyzer:
            sw_your_custom_language_analyzer:
                type: custom
                tokenizer: standard
                filter: ['lowercase', 'my_stopwords_filter', 'my_stemmer_filter']
    filter:
        my_stopwords_filter:
            type: 'stop'
            stopwords: ['foo', 'bar']
        my_stemmer_filter:
            type: 'stemmer'
            language: 'english'
    # It's important to map your analyzer with the language iso code
    language_analyzer_mapping:
        custom_iso: sw_your_custom_language_analyzer
```

---

---
url: >-
  /docs/v6.6/products/extensions/advanced-search/How-to-add-modify-language-analyzers-stopwords-stemmer.md
---

# Add / Modify language analyzers, stopwords, stemmer

With the introduction of the multi-language index, support for built-in [Elasticsearch language analyzers](https://www.elastic.co/guide/en/elasticsearch/reference/current/analysis-lang-analyzer.html) was also introduced.

This would help language-based fields have different analyzers for each language's specific features, like stopwords, stemmers, and normalization, out of the box.

You can also add more or customize the language analyzer by overriding the analyzer parameter in `custom/plugins/SwagCommercial/src/AdvancedSearch/Resources/config/packages/advanced_search.yaml`

For example:

```yaml
advanced_search:
    analysis:
        analyzer:
            sw_your_custom_language_analyzer:
                type: custom
                tokenizer: standard
                filter: ['lowercase', 'my_stopwords_filter', 'my_stemmer_filter']
    filter:
        my_stopwords_filter:
            type: 'stop'
            stopwords: ['foo', 'bar']
        my_stemmer_filter:
            type: 'stemmer'
            language: 'english'
    # It's important to map your analyzer with the language iso code
    language_analyzer_mapping:
        custom_iso: sw_your_custom_language_analyzer
```

---

---
url: /docs/guides/plugins/apps/app-scripts/add-api-endpoint.md
---

# Add an API Endpoint

::: info
This guide relies on [app scripts](../app-scripts/index.md), introduced from Shopware 6.4.8.0 version.
:::

## Overview

This guide shows how you can add a custom API endpoint that delivers dynamic data starting from zero.

After reading, you will be able to:

* Create the basic setup of an app.
* Execute app scripts and use them to model custom logic.
* Fetch, filter, and aggregate data from Shopware.
* Consume HTTP parameters and create responses.

## Prerequisites

* A Shopware cloud store
* Basic CLI usage (creating files, directories, running commands)
* Installed and configured [shopware-cli](../../../../products/tools/cli/index.md) tools
* General knowledge of [Twig Syntax](https://twig.symfony.com/)
* A text editor

## Create the app wrapper

We need to create the app "wrapper", the so-called app manifest within a new directory. Let's call that the project directory:

```text
MyApiExtension/
├─ manifest.xml
```

::: info
When using a self-hosted Shopware version, you can also create the project directory in the `custom/apps` directory of your Shopware installation. However, the descriptions in this guide apply to both Shopware cloud and self-hosted stores.
:::

Next, we will put our basic configuration into the file we just created.

::: code-group

```xml [manifest.xml]
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        <name>MyApiExtension</name>
        <label>Topsellers API</label>
        <description>This app adds a Topseller API endpoint</description>
        <author>shopware AG</author>
        <copyright>(c) shopware AG</copyright>
        <version>1.0.0</version>
        <license>MIT</license>
    </meta>
    <permissions>
        <read>order</read>
        <read>order_line_item</read>
        <read>product</read>
    </permissions>
</manifest>
```

:::

Besides some metadata, like a name, description, or version, this file contains permissions that the app requires.
We will need them later on when performing searches.

## Create the script

We will define our new API endpoint in a script file based on [app scripts](../app-scripts/index.md).
There are specific directory conventions that we have to follow to register a new API endpoint script.
The prefix for our API endpoint is one of the following and cannot be changed:

| API        | API consumers / callers      | Prefix                |
|------------|------------------------------|-----------------------|
| Store API  | Customer-facing integrations | `/store-api/script/`  |
| Admin API  | Backend integrations         | `/api/script/`        |
| Storefront | Default Storefront           | `/storefront/script/` |

::: info
You might wonder why the Storefront shows up in that table. In Storefront endpoints, you can render not only JSON but also twig templates.
But use them with care - whenever you create a Storefront endpoint, your app will not be compatible with headless consumers.

Learn more about the different endpoints in [custom endpoints](../app-scripts/custom-endpoints.md)
:::

### Directory structure

In this example, we're going to create a Store API endpoint. We want to provide logic that returns the top-selling products for a specific category.
So let's use the following endpoint naming:

`/store-api/script/swag/topseller`

You see that we have added a custom subdirectory `swag` in the route.
This is a good practice because we can prevent naming collisions between different apps.
Slashes (or subdirectories) in the endpoint path are represented by a hyphen in the name of the directory that contains the script.

```text
MyApiExtension/
├─ Resources/
│  ├─ scripts/
│  │  ├─ store-api-swag-topseller/ <-- /store-api/script/swag/topseller
│  │  │  ├─ topseller-script.twig
├─ manifest.xml
```

This directory naming causes Shopware to expose the script on two routes:

* `/store-api/script/swag/topseller` and
* `/store-api/script/swag-topseller`

### Add custom logic and install

Let's start with a simple script to see it in action:

```twig
// Resources/scripts/store-api-swag-topseller/topseller-script.twig
{% block response %}
    {% set response = services.response.json({ test: 'This is my API endpoint' }) %}
    {% do hook.setResponse(response) %}
{% endblock %}
```

Next we will install the App using the Shopware CLI.

::: info
If this is your first time using the Shopware CLI, you have to [install](../../../../products/tools/cli/index.md) it first. Next, configure it using the `shopware-cli project config init` command.
:::

Run this command from the root of the project directory.

```shell
shopware-cli project extension upload . --activate
```

This command will create a zip file from the specified extension directory (the one you are in), upload it to your configured store and activate it.

### Call the endpoint

You can call the endpoint using this curl command.

::: info
Follow this guide for more information on using the Store API : [Store API Authentication & Authorization](https://shopware.stoplight.io/docs/store-api/ZG9jOjEwODA3NjQx-authentication-and-authorisation)
:::

```shell
curl --request GET \
  --url http://<your-store-url>/store-api/script/swag/topseller \
  --header 'sw-access-key: insert-your-access-key'
```

which should return something like:

```json
{"apiAlias":"store_api_swag_topseller_response","test":"This is my API endpoint"}
```

However, instead of using curl, we recommend using visual clients to test the API - such as [Postman](https://www.postman.com/downloads/) or [Insomnia](https://insomnia.rest/download).

## Fill in the logic

For now, our script is not really doing anything. Let's change that.

```twig
// Resources/scripts/store-api-swag-topseller/topseller-script.twig
{% block response %}

    {% set categoryId = hook.request.categoryId %}

    {% set criteria = {
        aggregations: [
            {
                name: "categoryFilter",
                type: "filter",
                filter: [{
                    type: "equals",
                    field: "order.lineItems.product.categoryIds",
                    value: categoryId
                }],
                aggregation: {
                    name: "orderedProducts",
                    type: "terms",
                    field: "order.lineItems.productId",
                    aggregation: {
                        name: "quantityItemsOrdered",
                        type : "sum",
                        field: "order.lineItems.quantity"
                    }
                }
            }
        ]
    } %}

    {% set orderAggregations = services.repository.aggregate('order', criteria) %}

    {% set response = services.response.json(orderAggregations.first.jsonSerialize) %}

    {% do hook.setResponse(response) %}

{% endblock %}
```

What happened here?

We wrap everything in a block named `response`. That way, we will get access to useful objects and services, so we can build a response.

### Search criteria and fetching results

We start by reading the requested category id using `hook.request.categoryId`. In general, we can access post body parameters using `hook.request.*`.

In the following lines, we define a search criteria. The criteria contain a description of the data we want to fetch:

1. First, we filter out all products not inside the category that was requested, using a filter aggregation.
2. The following lines contain two further nested aggregations:
   1. The first one groups all products from all orders using their id.
   2. The second one sums up the number of ordered items in each order.

Ultimately, it gives a result of all products that have been ordered and the total ordered.

::: info
To learn more about the structure of search criteria, check out the [Search Criteria guide](../../../development/integrations-api/search-criteria.md).
:::

We now send a request to the database to retrieve the result using:

```twig
{% set orderAggregations = services.repository.aggregate('order', criteria) %}
```

### Building the response

In the final step, we build the response. We use the `services.response.json()` method to convert the serialized json representation of our aggregation into a json response object named `response`.

```twig
{% set response = services.response.json(orderAggregations.first.jsonSerialize) %}
```

Finally, we just set the response of the hook to the result from above:

```twig
{% do hook.setResponse(response) %}
```

It is important to do all this within the `response` block of the twig script. Otherwise, you will get errors when calling the script.

### Installing the plugin

Next, we re-install our plugin using the same command as before:

```shell
shopware-cli project extension upload . --activate
```

::: warning
Remember, if you made changes to the `manifest.xml` file in the meantime, also pass the `--increase-version` parameter, else Shopware will not pick up the changes:

```shell
shopware-cli project extension upload . --activate --increase-version
```

:::

We can now call our endpoint again:

```shell
curl --request GET \
  --url http://<your-store-url>/store-api/script/swag/topseller \
  --header 'sw-access-key: insert-your-access-key'
```

and receive a different result:

```json
{
  "apiAlias": "store_api_swag_topseller_response",
  "buckets": [
    {
      "key": "0060b9b2b3804244bf8ba98cdad50234",
      "count": 3,
      "quantityItemsOrdered": {
        "extensions": [],
        "sum": 15
      },
      "apiAlias": "aggregation_bucket"
    },
    {
      "key": "a65d918f883c47778a65b73548f456ea",
      "count": 2,
      "quantityItemsOrdered": {
        "extensions": [],
        "sum": 3
      },
      "apiAlias": "aggregation_bucket"
    },
    {
      "key": "6b67935063c84bde8e9d86f25a47c69d",
      "count": 3,
      "quantityItemsOrdered": {
        "extensions": [],
        "sum": 8
      },
      "apiAlias": "aggregation_bucket"
    }
  ]
}
```

## Wrap-Up

This tutorial covered the basics of app development using app scripts and some filtering and aggregation logic.

In a proper app, you should consider the following points:

* Input parameter validation
* Format and limit the result
* Define an API contract (endpoint structure) first and build after that
* The search result does not show actual top sellers but just the quantity of products ordered

## Where to continue

* More on adding [custom endpoints](../app-scripts/custom-endpoints.md)
* See how you can use [Twig functions](../app-scripts/index.md#extended-syntax) in app scripts
* Working with [DAL Aggregations](../../../development/troubleshooting/dal-reference/aggregations-reference.md)

---

---
url: /docs/guides/plugins/themes/assets/add-assets-to-theme.md
---

# Add Assets to a Theme

## Overview

Your theme can include custom assets like images. This short guide will show you where to store your custom assets and how you can link them in Twig and SCSS.

## Prerequisites

This guide is built upon the guide on creating a first theme:

## Using custom assets

There are basically two ways of adding custom assets to your theme. The first one is using the `theme.json` to define the path to your custom assets, the second being the default way of using custom assets in plugins. We'll take a closer look at them in the following sections.

### Adding assets in theme.json file

While working with a theme you might have noted the [Theme configuration](../configuration/theme-configuration.md), where you can configure paths to custom assets like images, fonts, etc. Configure your asset path accordingly:

```javascript
// <plugin root>/src/Resources/theme.json
{
  ...
  "asset": [
     "app/storefront/src/assets"
   ]
  ...
}
```

Next, run the command `bin/console theme:compile`. The assets from the path defined in the `theme.json` file will be copied by the `theme:compile` command to `<shopware root>/public/theme/<theme-asset-uuid>` along with the compiled CSS and JS, which are stored in a separate folder.

```text
// <shopware root>/public
# 
.
└── theme
    ├── <theme-uuid>
    │   ├── css
    │   │   └── all.css
    │   └── js
    │       └── all.js
    └── <theme-asset-uuid>
        └── asset
            └── your-image.png <-- Your asset is copied here  
```

### Adding assets the plugin way

This way of adding custom assets refers to the default way of dealing with assets. For more details, please check out the article that specifically addresses this topic:

## Linking to assets

You can link to the asset with the Twig [asset](https://symfony.com/doc/current/templates.html#linking-to-css-javascript-and-image-assets) function:

```html
<img src="{{ asset('/assets/your-image.png', 'theme') }}">
```

In SCSS, you can link to the asset like the following:

```css
body {
    background-image: url('#{$app-css-relative-asset-path}/your-image.png');
}
```

## Next steps

Now that you know how to use your assets in a theme, here is a list of other related topics where assets can be used.

* [Customize templates](../../plugins/storefront/templates/customize-templates.md)

---

---
url: /docs/v6.5/guides/plugins/themes/add-assets-to-theme.md
---

# Add Assets to a Theme

## Overview

Your theme can include custom assets like images. This short guide will show you where to store your custom assets and how you can link them in Twig and SCSS.

## Prerequisites

This guide is built upon the guide on creating a first theme:

## Using custom assets

There are basically two ways of adding custom assets to your theme. The first one is using the `theme.json` to define the path to your custom assets, the second being the default way of using custom assets in plugins. We'll take a closer look at them in the following sections.

### Adding assets in theme.json file

While working with your own theme, you might have already come across the [Theme configuration](theme-configuration). In there, you have the possibility to configure your paths to your custom assets like images, fonts, etc. This way, please configure your asset path accordingly.

```javascript
// <plugin root>/src/Resources/theme.json
{
  ...
  "asset": [
     "app/storefront/src/assets"
   ]
  ...
}
```

Next, run the command `bin/console theme:compile`. The assets from the path defined in the `theme.json` file will be copied by the `theme:compile` command to `<shopware root>/public/theme/<theme-asset-uuid>` along with the compiled CSS and JS, which are stored in a separate folder.

```text
// <shopware root>/public
# 
.
└── theme
    ├── <theme-uuid>
    │   ├── css
    │   │   └── all.css
    │   └── js
    │       └── all.js
    └── <theme-asset-uuid>
        └── asset
            └── your-image.png <-- Your asset is copied here  
```

### Adding assets the plugin way

This way of adding custom assets refers to the default way of dealing with assets. For more details, please check out the article that specifically addresses this topic:

## Linking to assets

You can link to the asset with the twig [asset](https://symfony.com/doc/current/templates.html#linking-to-css-javascript-and-image-assets) function:

```html
<img src="{{ asset('/assets/your-image.png', 'theme') }}">
```

In SCSS, you can link to the asset like the following:

```css
body {
    background-image: url('#{$app-css-relative-asset-path}/your-image.png');
}
```

## Next steps

Now that you know how to use your assets in a theme, here is a list of other related topics where assets can be used.

* [Customize templates](../plugins/storefront/customize-templates)

---

---
url: /docs/v6.6/guides/plugins/themes/add-assets-to-theme.md
---

# Add Assets to a Theme

## Overview

Your theme can include custom assets like images. This short guide will show you where to store your custom assets and how you can link them in Twig and SCSS.

## Prerequisites

This guide is built upon the guide on creating a first theme:

## Using custom assets

There are basically two ways of adding custom assets to your theme. The first one is using the `theme.json` to define the path to your custom assets, the second being the default way of using custom assets in plugins. We'll take a closer look at them in the following sections.

### Adding assets in theme.json file

While working with your own theme, you might have already come across the [Theme configuration](theme-configuration). In there, you have the possibility to configure your paths to your custom assets like images, fonts, etc. This way, please configure your asset path accordingly.

```javascript
// <plugin root>/src/Resources/theme.json
{
  ...
  "asset": [
     "app/storefront/src/assets"
   ]
  ...
}
```

Next, run the command `bin/console theme:compile`. The assets from the path defined in the `theme.json` file will be copied by the `theme:compile` command to `<shopware root>/public/theme/<theme-asset-uuid>` along with the compiled CSS and JS, which are stored in a separate folder.

```text
// <shopware root>/public
# 
.
└── theme
    ├── <theme-uuid>
    │   ├── css
    │   │   └── all.css
    │   └── js
    │       └── all.js
    └── <theme-asset-uuid>
        └── asset
            └── your-image.png <-- Your asset is copied here  
```

### Adding assets the plugin way

This way of adding custom assets refers to the default way of dealing with assets. For more details, please check out the article that specifically addresses this topic:

## Linking to assets

You can link to the asset with the twig [asset](https://symfony.com/doc/current/templates.html#linking-to-css-javascript-and-image-assets) function:

```html
<img src="{{ asset('/assets/your-image.png', 'theme') }}">
```

In SCSS, you can link to the asset like the following:

```css
body {
    background-image: url('#{$app-css-relative-asset-path}/your-image.png');
}
```

## Next steps

Now that you know how to use your assets in a theme, here is a list of other related topics where assets can be used.

* [Customize templates](../plugins/storefront/customize-templates)

---

---
url: /docs/resources/references/adr/2022-09-23-add-bootstrap-util.md
---

# Add bootstrap JS-plugin initialization utility to storefront JS

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-09-23-add-bootstrap-util.md)
:::

## Context

* Some Bootstrap JavaScript plugins have to be initialized manually to the desired DOM elements, see: https://getbootstrap.com/docs/4.3/components/tooltips/#example-enable-tooltips-everywhere
* This is not needed for all Bootstrap plugins. Modals for example work out of the box without extra initialization.
* Currently, we only initialize Tooltips using `src/utility/tooltip/tooltip.util.js`
* On dynamic content changes (listing pagination, ajax OffCanvas cart, etc.) Bootstrap plugins like Tooltip are no longer working.
* For example: It is not possible to show Tooltips in the OffCanvas cart without extra/manual work in JavaScript.

## Decision

* Add a new module `src/utility/bootstrap/bootstrap.util` in favor of `TooltipUtil` to consider more Bootstrap plugins in the future.
* Currently, it initializes `Tooltip` and `Popover` because those are the only Bootstrap plugins which have a documented manual initialization.
* We use the "selector" option in order to initialize Bootstrap plugins on selectors, which are added dynamically to the HTML. See: https://getbootstrap.com/docs/4.3/components/tooltips/#options

## Consequences

* In the main.js, `BootstrapUtil.initBootstrapPlugins()` is used instead of `new TooltipUtil()` to initialize Popovers as well.
* `TooltipUtil` is deprecated.
* Since we use event delegation ("selector" option) inside `BootstrapUtil` we don't need to manually re-initialize the Bootstrap plugins after dynamic content changes,
  so it works automatically for all `[data-toogle="tooltip"]` and `[data-toogle="popover"]` selectors.

---

---
url: /docs/v6.5/resources/references/adr/2022-09-23-add-bootstrap-util.md
---

# Add bootstrap JS-plugin initialization utility to storefront JS

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-09-23-add-bootstrap-util.md)
:::

## Context

* Some Bootstrap JavaScript plugins have to be initialized manually to the desired DOM elements, see: https://getbootstrap.com/docs/4.3/components/tooltips/#example-enable-tooltips-everywhere
* This is not needed for all Bootstrap plugins. Modals for example work out of the box without extra initialization.
* Currently, we only initialize Tooltips using `src/utility/tooltip/tooltip.util.js`
* On dynamic content changes (listing pagination, ajax OffCanvas cart, etc.) Bootstrap plugins like Tooltip are no longer working.
* For example: It is not possible to show Tooltips in the OffCanvas cart without extra/manual work in JavaScript.

## Decision

* Add a new module `src/utility/bootstrap/bootstrap.util` in favor of `TooltipUtil` to consider more Bootstrap plugins in the future.
* Currently, it initializes `Tooltip` and `Popover` because those are the only Bootstrap plugins which have a documented manual initialization.
* We use the "selector" option in order to initialize Bootstrap plugins on selectors, which are added dynamically to the HTML. See: https://getbootstrap.com/docs/4.3/components/tooltips/#options

## Consequences

* In the main.js, `BootstrapUtil.initBootstrapPlugins()` is used instead of `new TooltipUtil()` to initialize Popovers as well.
* `TooltipUtil` is deprecated.
* Since we use event delegation ("selector" option) inside `BootstrapUtil` we don't need to manually re-initialize the Bootstrap plugins after dynamic content changes,
  so it works automatically for all `[data-toogle="tooltip"]` and `[data-toogle="popover"]` selectors.

---

---
url: /docs/v6.6/resources/references/adr/2022-09-23-add-bootstrap-util.md
---

# Add bootstrap JS-plugin initialization utility to storefront JS

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-09-23-add-bootstrap-util.md)
:::

## Context

* Some Bootstrap JavaScript plugins have to be initialized manually to the desired DOM elements, see: https://getbootstrap.com/docs/4.3/components/tooltips/#example-enable-tooltips-everywhere
* This is not needed for all Bootstrap plugins. Modals for example work out of the box without extra initialization.
* Currently, we only initialize Tooltips using `src/utility/tooltip/tooltip.util.js`
* On dynamic content changes (listing pagination, ajax OffCanvas cart, etc.) Bootstrap plugins like Tooltip are no longer working.
* For example: It is not possible to show Tooltips in the OffCanvas cart without extra/manual work in JavaScript.

## Decision

* Add a new module `src/utility/bootstrap/bootstrap.util` in favor of `TooltipUtil` to consider more Bootstrap plugins in the future.
* Currently, it initializes `Tooltip` and `Popover` because those are the only Bootstrap plugins which have a documented manual initialization.
* We use the "selector" option in order to initialize Bootstrap plugins on selectors, which are added dynamically to the HTML. See: https://getbootstrap.com/docs/4.3/components/tooltips/#options

## Consequences

* In the main.js, `BootstrapUtil.initBootstrapPlugins()` is used instead of `new TooltipUtil()` to initialize Popovers as well.
* `TooltipUtil` is deprecated.
* Since we use event delegation ("selector" option) inside `BootstrapUtil` we don't need to manually re-initialize the Bootstrap plugins after dynamic content changes,
  so it works automatically for all `[data-toogle="tooltip"]` and `[data-toogle="popover"]` selectors.

---

---
url: >-
  /docs/v6.5/guides/plugins/plugins/framework/store-api/add-caching-for-store-api-route.md
---

# Add caching for Store API route

## Overview

In this guide you will learn how to add a cache layer to your custom Store API route. In this example, we will add a cache layer for the `ExampleRoute`, which is created in the [Add Store API route](./add-store-api-route) guide. For the cache invalidation we will write a invalidation subscriber.

## Prerequisites

In order to add a cache layer for the Store API route, you first need a Store API route as base. Therefore, you can refer to the [Add Store API route](./add-store-api-route) guide.

You also should have a look at our [Adding custom complex data](../data-handling/add-custom-complex-data) guide, since this guide is built upon it.

## Add cache layer

As you might have learned already from the [Add Store API route](./add-store-api-route) guide, we use abstract classes to make our routes more decoratable.

This concept is very advantageous if we now want to include a cache layer for the route. There are of course different ways to do this - but in this guide we show how we implemented it in the core.

### Add cached route class

First, we create an abstract class called `CachedExampleRoute` which extends the `AbstractExampleRoute`.

```php
// <plugin root>/src/Core/Content/Example/SalesChannel/CachedExampleRoute.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\SalesChannel;

use Psr\Log\LoggerInterface;
use Shopware\Core\Framework\Adapter\Cache\CacheStateSubscriber;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Core\Framework\Adapter\Cache\AbstractCacheTracer;
use Shopware\Core\Framework\Adapter\Cache\CacheCompressor;
use Shopware\Core\Framework\DataAbstractionLayer\Cache\EntityCacheKeyGenerator;
use Shopware\Core\Framework\Util\Json;
use Shopware\Core\Framework\Routing\Annotation\Entity;
use Shopware\Core\Framework\Routing\Annotation\Since;
use Symfony\Component\Cache\Adapter\TagAwareAdapterInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Annotation\Route;
use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;

#[Route(defaults: ['_routeScope' => ['store-api']])]
class CachedExampleRoute extends AbstractExampleRoute
{
    private AbstractExampleRoute $decorated;

    private TagAwareAdapterInterface $cache;

    private EntityCacheKeyGenerator $generator;

    private AbstractCacheTracer $tracer;

    private array $states;

    private LoggerInterface $logger;

    public function __construct(
        AbstractExampleRoute $decorated,
        TagAwareAdapterInterface $cache,
        EntityCacheKeyGenerator $generator,
        AbstractCacheTracer $tracer,
        LoggerInterface $logger
    ) {
        $this->decorated = $decorated;
        $this->cache = $cache;
        $this->generator = $generator;
        $this->tracer = $tracer;
        
        // declares that this route can not be cached if the customer is logged in
        $this->states = [CacheStateSubscriber::STATE_LOGGED_IN];
        $this->logger = $logger;
    }
    
    public function getDecorated(): AbstractExampleRoute
    {
        return $this->decorated;
    }

    #[Route(path: '/store-api/example', name: 'store-api.example.search', methods: ['GET','POST'], defaults: ['_entity' => 'swag_example'])]
    public function load(Criteria $criteria, SalesChannelContext $context): ExampleRouteResponse
    {
        // The context is provided with a state where the route cannot be cached
        if ($context->hasState(...$this->states)) {
            return $this->getDecorated()->load($criteria, $context);
        }

        // Fetch item from the cache pool
        $item = $this->cache->getItem(
            $this->generateKey($criteria, $context)
        );

        try {
            if ($item->isHit() && $item->get()) {
                // Use cache compressor to uncompress the cache value
                return CacheCompressor::uncompress($item);
            }
        } catch (\Throwable $e) {
            // Something went wrong when uncompress the cache item - we log the error and continue to overwrite the invalid cache item 
            $this->logger->error($e->getMessage());
        }

        $name = self::buildName();
        // start tracing of nested cache tags and system config keys
        $response = $this->tracer->trace($name, function () use ($criteria, $context) {
            return $this->getDecorated()->load($criteria, $context);
        });
        
        // compress cache content to reduce cache size
        $item = CacheCompressor::compress($item, $response);

        $item->tag(array_merge(
            // get traced tags and configs        
            $this->tracer->get(self::buildName()),
            [self::buildName()]
        ));

        $this->cache->save($item);

        return $response;
    }
    
    public static function buildName(): string 
    {
        return 'example-route';
    }
  
    private function generateKey(SalesChannelContext $context, Criteria $criteria): string
    {
        $parts = [
            self::buildName(),
            // generate a hash for the route criteria
            $this->generator->getCriteriaHash($criteria),
            // generate a hash for the current context 
            $this->generator->getSalesChannelContextHash($context),
        ];
          
        return md5(Json::encode($parts));
    }
}
```

```xml
// <plugin root>/src/Resources/config/services.xml

<?xml version="1.0" ?> 

<container xmlns="http://symfony.com/schema/dic/services" 
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
    
    <services> 
        <service id="Swag\BasicExample\Core\Content\Example\SalesChannel\CachedExampleRoute" decorates="Swag\BasicExample\Core\Content\Example\SalesChannel\ExampleRoute" decoration-priority="-1000">
            <argument type="service" id="Swag\BasicExample\Core\Content\Example\SalesChannel\CachedExampleRoute.inner"/>
            <argument type="service" id="cache.object"/>
            <argument type="service" id="Shopware\Core\Framework\DataAbstractionLayer\Cache\EntityCacheKeyGenerator"/>
            <argument type="service" id="Shopware\Core\Framework\Adapter\Cache\CacheTracer"/>
            <argument type="service" id="logger" />
        </service>
    </services>
</container>
```

In the new `CachedExampleRoute` some core classes are used which simplify the caching.

* `TagAwareAdapterInterface` - Used to read, write and tag cache items.

* `EntityCacheKeyGenerator` - Used to generate hashes for the context and/or criteria;

* `AbstractCacheTracer` - Traces all system config keys that were accessed. The data is needed later for cache invalidation.

* `CacheCompressor` - Provides an optimal compression of the cache entries to use as little disk space as possible.

### Add cache invalidation

Cache invalidation is much harder to implement than the actual caching. Finding the right balance between too much and too little invalidation is difficult. Therefore, there is no precise guidance or documentation on when to invalidate what. What and how to invalidate depends on what has been cached. For example, the product routes in the core are always invalidated when the product is written, but also when the product is ordered and reaches the out-of-stock status. The entire cache invalidation in Shopware is controlled via events. On the one hand there is the entity written event and on the other hand the corresponding business events like `ProductNoLongerAvailableEvent`.

```php
// <plugin root>/src/Core/Content/Example/SalesChannel/CacheInvalidationSubscriber.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\SalesChannel;

use Shopware\Core\Framework\DataAbstractionLayer\Event\EntityWrittenContainerEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Swag\BasicExample\Core\Content\Example\ExampleDefinition;
use Shopware\Core\Framework\Adapter\Cache\CacheInvalidator;

class CacheInvalidationSubscriber implements EventSubscriberInterface
{
    private CacheInvalidator $cacheInvalidator;

    public function __construct(CacheInvalidator $cacheInvalidator) 
    {
        $this->cacheInvalidator = $cacheInvalidator;
    }
    
    public static function getSubscribedEvents()
    {
        return [
            // The EntityWrittenContainerEvent is a generic event that is always thrown when an entities are written. This contains all changed entities
            EntityWrittenContainerEvent::class => [
                ['invalidate', 2001]
            ],
        ];
    }
    
    public function invalidate(EntityWrittenContainerEvent $event): void
    {
        // check if own entity written. In some cases you want to use the primary keys for further cache invalidation
        $changes = $event->getPrimaryKeys(ExampleDefinition::ENTITY_NAME);
        
        // no example entity changed? Then the cache does not need to be invalidated
        if (empty($changes)) {
            return;
        }

        $this->cacheInvalidator->invalidate([
            CachedExampleRoute::buildName()  
        ]);
    }
}
```

```xml
// <plugin root>/src/Resources/config/services.xml

<?xml version="1.0" ?> 

<container xmlns="http://symfony.com/schema/dic/services" 
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
    
    <services> 
        <service id=" Swag\BasicExample\Core\Content\Example\SalesChannel\CacheInvalidationSubscriber">
            <argument type="service" id="Shopware\Core\Framework\Adapter\Cache\CacheInvalidator"/>
        </service>
    </services>
</container>
```

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/framework/store-api/add-caching-for-store-api-route.md
---

# Add caching for Store API route

## Overview

In this guide you will learn how to add a cache layer to your custom Store API route. In this example, we will add a cache layer for the `ExampleRoute`, which is created in the [Add Store API route](./add-store-api-route) guide. For the cache invalidation we will write a invalidation subscriber.

## Prerequisites

In order to add a cache layer for the Store API route, you first need a Store API route as base. Therefore, you can refer to the [Add Store API route](./add-store-api-route) guide.

You also should have a look at our [Adding custom complex data](../data-handling/add-custom-complex-data) guide, since this guide is built upon it.

## Add cache layer

As you might have learned already from the [Add Store API route](./add-store-api-route) guide, we use abstract classes to make our routes more decoratable.

This concept is very advantageous if we now want to include a cache layer for the route. There are of course different ways to do this - but in this guide we show how we implemented it in the core.

### Add cached route class

First, we create an abstract class called `CachedExampleRoute` which extends the `AbstractExampleRoute`.

```php
// <plugin root>/src/Core/Content/Example/SalesChannel/CachedExampleRoute.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\SalesChannel;

use Psr\Log\LoggerInterface;
use Shopware\Core\Framework\Adapter\Cache\CacheStateSubscriber;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Core\Framework\Adapter\Cache\AbstractCacheTracer;
use Shopware\Core\Framework\Adapter\Cache\CacheCompressor;
use Shopware\Core\Framework\DataAbstractionLayer\Cache\EntityCacheKeyGenerator;
use Shopware\Core\Framework\Util\Json;
use Symfony\Component\Cache\Adapter\TagAwareAdapterInterface;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\Routing\Attribute\Route;
use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;

#[Route(defaults: ['_routeScope' => ['store-api']])]
class CachedExampleRoute extends AbstractExampleRoute
{
    private AbstractExampleRoute $decorated;

    private TagAwareAdapterInterface $cache;

    private EntityCacheKeyGenerator $generator;

    private AbstractCacheTracer $tracer;

    private array $states;

    private LoggerInterface $logger;

    public function __construct(
        AbstractExampleRoute $decorated,
        TagAwareAdapterInterface $cache,
        EntityCacheKeyGenerator $generator,
        AbstractCacheTracer $tracer,
        LoggerInterface $logger
    ) {
        $this->decorated = $decorated;
        $this->cache = $cache;
        $this->generator = $generator;
        $this->tracer = $tracer;
        
        // declares that this route can not be cached if the customer is logged in
        $this->states = [CacheStateSubscriber::STATE_LOGGED_IN];
        $this->logger = $logger;
    }
    
    public function getDecorated(): AbstractExampleRoute
    {
        return $this->decorated;
    }

    #[Route(path: '/store-api/example', name: 'store-api.example.search', methods: ['GET','POST'], defaults: ['_entity' => 'swag_example'])]
    public function load(Criteria $criteria, SalesChannelContext $context): ExampleRouteResponse
    {
        // The context is provided with a state where the route cannot be cached
        if ($context->hasState(...$this->states)) {
            return $this->getDecorated()->load($criteria, $context);
        }

        // Fetch item from the cache pool
        $item = $this->cache->getItem(
            $this->generateKey($context, $criteria)
        );

        try {
            if ($item->isHit() && $item->get()) {
                // Use cache compressor to uncompress the cache value
                return CacheCompressor::uncompress($item);
            }
        } catch (\Throwable $e) {
            // Something went wrong when uncompress the cache item - we log the error and continue to overwrite the invalid cache item 
            $this->logger->error($e->getMessage());
        }

        $name = self::buildName();
        // start tracing of nested cache tags and system config keys
        $response = $this->tracer->trace($name, function () use ($criteria, $context) {
            return $this->getDecorated()->load($criteria, $context);
        });
        
        // compress cache content to reduce cache size
        $item = CacheCompressor::compress($item, $response);

        $item->tag(array_merge(
            // get traced tags and configs        
            $this->tracer->get(self::buildName()),
            [self::buildName()]
        ));

        $this->cache->save($item);

        return $response;
    }
    
    public static function buildName(): string 
    {
        return 'example-route';
    }
  
    private function generateKey(SalesChannelContext $context, Criteria $criteria): string
    {
        $parts = [
            self::buildName(),
            // generate a hash for the route criteria
            $this->generator->getCriteriaHash($criteria),
            // generate a hash for the current context 
            $this->generator->getSalesChannelContextHash($context),
        ];
          
        return md5(Json::encode($parts));
    }
}
```

```xml
// <plugin root>/src/Resources/config/services.xml

<?xml version="1.0" ?> 

<container xmlns="http://symfony.com/schema/dic/services" 
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
    
    <services> 
        <service id="Swag\BasicExample\Core\Content\Example\SalesChannel\CachedExampleRoute" decorates="Swag\BasicExample\Core\Content\Example\SalesChannel\ExampleRoute" decoration-priority="-1000">
            <argument type="service" id="Swag\BasicExample\Core\Content\Example\SalesChannel\CachedExampleRoute.inner"/>
            <argument type="service" id="cache.object"/>
            <argument type="service" id="Shopware\Core\Framework\DataAbstractionLayer\Cache\EntityCacheKeyGenerator"/>
            <argument type="service" id="Shopware\Core\Framework\Adapter\Cache\CacheTracer"/>
            <argument type="service" id="logger" />
        </service>
    </services>
</container>
```

In the new `CachedExampleRoute` some core classes are used which simplify the caching.

* `TagAwareAdapterInterface` - Used to read, write and tag cache items.

* `EntityCacheKeyGenerator` - Used to generate hashes for the context and/or criteria;

* `AbstractCacheTracer` - Traces all system config keys that were accessed. The data is needed later for cache invalidation.

* `CacheCompressor` - Provides an optimal compression of the cache entries to use as little disk space as possible.

### Add cache invalidation

Cache invalidation is much harder to implement than the actual caching. Finding the right balance between too much and too little invalidation is difficult. Therefore, there is no precise guidance or documentation on when to invalidate what. What and how to invalidate depends on what has been cached. For example, the product routes in the core are always invalidated when the product is written, but also when the product is ordered and reaches the out-of-stock status. The entire cache invalidation in Shopware is controlled via events. On the one hand there is the entity written event and on the other hand the corresponding business events like `ProductNoLongerAvailableEvent`.

```php
// <plugin root>/src/Core/Content/Example/SalesChannel/CacheInvalidationSubscriber.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\SalesChannel;

use Shopware\Core\Framework\DataAbstractionLayer\Event\EntityWrittenContainerEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Swag\BasicExample\Core\Content\Example\ExampleDefinition;
use Shopware\Core\Framework\Adapter\Cache\CacheInvalidator;

class CacheInvalidationSubscriber implements EventSubscriberInterface
{
    private CacheInvalidator $cacheInvalidator;

    public function __construct(CacheInvalidator $cacheInvalidator) 
    {
        $this->cacheInvalidator = $cacheInvalidator;
    }
    
    public static function getSubscribedEvents()
    {
        return [
            // The EntityWrittenContainerEvent is a generic event that is always thrown when an entities are written. This contains all changed entities
            EntityWrittenContainerEvent::class => [
                ['invalidate', 2001]
            ],
        ];
    }
    
    public function invalidate(EntityWrittenContainerEvent $event): void
    {
        // check if own entity written. In some cases you want to use the primary keys for further cache invalidation
        $changes = $event->getPrimaryKeys(ExampleDefinition::ENTITY_NAME);
        
        // no example entity changed? Then the cache does not need to be invalidated
        if (empty($changes)) {
            return;
        }

        $this->cacheInvalidator->invalidate([
            CachedExampleRoute::buildName()  
        ]);
    }
}
```

```xml
// <plugin root>/src/Resources/config/services.xml

<?xml version="1.0" ?> 

<container xmlns="http://symfony.com/schema/dic/services" 
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" 
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
    
    <services> 
        <service id=" Swag\BasicExample\Core\Content\Example\SalesChannel\CacheInvalidationSubscriber">
            <argument type="service" id="Shopware\Core\Framework\Adapter\Cache\CacheInvalidator"/>
        </service>
    </services>
</container>
```

---

---
url: >-
  /docs/guides/plugins/plugins/storefront/advanced/add-caching-to-custom-controller.md
---

# Add Caching to Custom Controller

In this guide you will learn how to define a controller route as cacheable for the HTTP cache.

## Prerequisites

In order to add a cache to an own controller route, you first need a plugin with a controller. Refer to the [Add custom controller guide](../controllers/add-custom-controller.md).

## Define the controller as cacheable

To define a controller route as cacheable, the default option of the route attribute `_httpCache` must be set to `true`. Once this option is set, the core takes care of everything else. If the route is called several times in the same state, a response is generated only for the first request and the second request gets the same response as the first one. It is also possible to exclude certain states from the cache. Shopware sets two different user states to which the HTTP cache reacts:

* state: `logged-in` - means that the user is logged in.

* state: `cart-filled` - means that there are products in the shopping cart.

```php
// <plugin root>/src/Storefront/Controller/ExampleController.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

use Shopware\Core\PlatformRequest;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Controller\StorefrontController;
use Shopware\Storefront\Framework\Routing\StorefrontRouteScope;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

#[Route(defaults: [PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [StorefrontRouteScope::ID]])]
class ExampleController extends StorefrontController
{

    #[Route(path: '/example', name: 'frontend.example.example', methods: ['GET'], defaults: ['_httpCache' => true])]
    public function showExample(): Response
    {
        return $this->renderStorefront('@SwagBasicExample/storefront/page/example/index.html.twig', [
            'example' => 'Hello world'
        ]);
    }
}
```

## Cache invalidation

As soon as a controller route has been defined as cacheable, and the corresponding response is written to the cache, it is tagged accordingly. For this purpose, the core uses all cache tags generated during the request or loaded from existing cache entries. The cache invalidation of the Storefront controller routes is controlled by the cache invalidation of the store API routes.

For more information about Store API cache invalidation, refer to the [Caching Guide](../../framework/caching/index.md).

This is because all data loaded in a controller route, is loaded in the core via the corresponding Store API routes and provided with corresponding cache tags. So the tags of the HTTP cache entries we have in the core consists of the sum of all store api tags generated or loaded during the request. Therefore the invalidation of a controller route that loads all data via the store API, no additional invalidation needs to be written.

---

---
url: >-
  /docs/v6.5/guides/plugins/plugins/storefront/add-caching-to-custom-controller.md
---

# Add Caching to Custom Controller

## Overview

In this guide you will learn how to define a controller route as cacheable for the HTTP cache.

## Prerequisites

In order to add a cache to an own controller route, you first need a plugin with a controller. Therefore, you can refer to the [Add custom controller guide](./add-custom-controller).

## Define the controller as cacheable

To define a controller route as cacheable, it must be annotated with `@HttpCache()`. Once this annotation is set, the core takes care of everything else. If the route is called several times in the same state, a response is generated only for the first request and the second request gets the same response as the first one. It is also possible to exclude certain states from the cache. Shopware sets two different user states to which the HTTP cache reacts:

* state: `logged-in` - means that the user is logged in.

* state: `cart-filled` - means that there are products in the shopping cart.

If the controller route is not to be cached for one or both of these states, the annotation can be defined as follows: `@HttpCache(states={"cart-filled", "logged-in"})`

```php
// <plugin root>/src/Storefront/Controller/ExampleController.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

use Shopware\Storefront\Framework\Cache\Annotation\HttpCache;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Controller\StorefrontController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

#[Route(defaults: ['_routeScope' => ['storefront']])]
class ExampleController extends StorefrontController
{

    #[Route(path: '/example', name: 'frontend.example.example', methods: ['GET'], defaults: ['_httpCache' => true])]
    public function showExample(): Response
    {
        return $this->renderStorefront('@SwagBasicExample/storefront/page/example/index.html.twig', [
            'example' => 'Hello world'
        ]);
    }
}
```

## Cache invalidation

As soon as a controller route has been defined as cacheable, and the corresponding response is written to the cache, it is tagged accordingly. For this purpose, the core uses all cache tags generated during the request or loaded from existing cache entries. The cache invalidation of the Storefront controller routes is controlled by the cache invalidation of the store API routes.

For more information about Store API cache invalidation, you can refer to the [Add Cache for Store Api Route Guide](../framework/store-api/add-caching-for-store-api-route).

This is because all data loaded in a controller route, is loaded in the core via the corresponding Store API routes and provided with corresponding cache tags. So the tags of the HTTP cache entries we have in the core consists of the sum of all store api tags generated or loaded during the request. Therefore the invalidation of a controller route that loads all data via the store API, no additional invalidation needs to be written.

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/storefront/add-caching-to-custom-controller.md
---

# Add Caching to Custom Controller

## Overview

In this guide you will learn how to define a controller route as cacheable for the HTTP cache.

## Prerequisites

In order to add a cache to an own controller route, you first need a plugin with a controller. Therefore, you can refer to the [Add custom controller guide](./add-custom-controller).

## Define the controller as cacheable

To define a controller route as cacheable, the default option of the route attribute `_httpCache` must be set to `true`. Once this option is set, the core takes care of everything else. If the route is called several times in the same state, a response is generated only for the first request and the second request gets the same response as the first one. It is also possible to exclude certain states from the cache. Shopware sets two different user states to which the HTTP cache reacts:

* state: `logged-in` - means that the user is logged in.

* state: `cart-filled` - means that there are products in the shopping cart.

```php
// <plugin root>/src/Storefront/Controller/ExampleController.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Controller\StorefrontController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

#[Route(defaults: ['_routeScope' => ['storefront']])]
class ExampleController extends StorefrontController
{

    #[Route(path: '/example', name: 'frontend.example.example', methods: ['GET'], defaults: ['_httpCache' => true])]
    public function showExample(): Response
    {
        return $this->renderStorefront('@SwagBasicExample/storefront/page/example/index.html.twig', [
            'example' => 'Hello world'
        ]);
    }
}
```

## Cache invalidation

As soon as a controller route has been defined as cacheable, and the corresponding response is written to the cache, it is tagged accordingly. For this purpose, the core uses all cache tags generated during the request or loaded from existing cache entries. The cache invalidation of the Storefront controller routes is controlled by the cache invalidation of the store API routes.

For more information about Store API cache invalidation, you can refer to the [Add Cache for Store Api Route Guide](../framework/store-api/add-caching-for-store-api-route).

This is because all data loaded in a controller route, is loaded in the core via the corresponding Store API routes and provided with corresponding cache tags. So the tags of the HTTP cache entries we have in the core consists of the sum of all store api tags generated or loaded during the request. Therefore the invalidation of a controller route that loads all data via the store API, no additional invalidation needs to be written.

---

---
url: /docs/guides/plugins/plugins/checkout/cart/add-cart-processor-collector.md
---

# Add Cart Collector/Processor

## Overview

In order to change the cart at runtime, you can use a custom [collector](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Core/Checkout/Cart/CartDataCollectorInterface.php)
or a custom [processor](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Core/Checkout/Cart/CartProcessorInterface.php).

Their main purpose is explained in their respective section.

## Collector class

A collector can and should be used to retrieve additional data for the cart, e.g. by querying the database, hence the name "collector".
This could also be querying an API endpoint, querying the database or fetching data in any other way you can think of.

Very often a collector is used to fetch data necessary for a processor.

It has to implement the interface `Shopware\Core\Checkout\Cart\CartDataCollectorInterface` and therefore implement a `collect` method.

But let's have a look at an example collector class.

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout\Cart;

use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Cart\CartBehavior;
use Shopware\Core\Checkout\Cart\CartDataCollectorInterface;
use Shopware\Core\Checkout\Cart\LineItem\CartDataCollection;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class CustomCartCollector implements CartDataCollectorInterface
{
    public function collect(CartDataCollection $data, Cart $original, SalesChannelContext $context, CartBehavior $behavior): void
    {
        // Do your stuff in order to collect data, this is just an example method call
        $newData = $this->collectData();

        $data->set('uniqueKey', $newData);
    }
}
```

The `collect` method's parameters are the following:

* `CartDataCollection`: Use this object to save your new cart data. You'll most likely use the `set` method here, which expects
  a unique key and its value. This object will be available in all processors.
* `Cart`: The current cart and its line items.
* `SalesChannelContext`: The current sales channel context, containing information about the currency, the country, etc.
* `CartBehavior`: It contains a cart state, which describes which actions are allowed. E.g. in the [product processor](https://github.com/shopware/shopware/blob/trunk/src/Core/Content/Product/Cart/ProductCartProcessor.php#L33), there's
  a permission to check if the product stock validation should be skipped.

Your collector has to be defined in the service container using the tag `shopware.cart.collector`.

## Processor class

A processor is the class that will actually process the cart and is supposed to apply changes to the cart.
It will most likely use data, that was previously fetched by a collector.

::: warning
Do not query data in the process method, since it may be executed a lot of times. Always use the collect method of a collector for this case!
:::

Your processor class has to implement the interface `Shopware\Core\Checkout\Cart\CartProcessorInterface` and its `process` method.

Let's have a look at an example processor.

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout\Cart;

use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Cart\CartBehavior;
use Shopware\Core\Checkout\Cart\CartProcessorInterface;
use Shopware\Core\Checkout\Cart\LineItem\CartDataCollection;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class CustomCartProcessor implements CartProcessorInterface
{
    public function process(CartDataCollection $data, Cart $original, Cart $toCalculate, SalesChannelContext $context, CartBehavior $behavior): void
    {
        $newData = $data->get('uniqueKey');

        // Do stuff to the `$toCalculate` cart with your new data
        foreach ($toCalculate->getLineItems()->getFlat() as $lineItem) {
            $lineItem->setPayload($newData['stuff']);
        }
    }
}
```

The `process` method contains the same parameters as the `collect` method, but there's one main difference:

Next to the `$original` `Cart`, you've got another `Cart` parameter being called `$toCalculate` here.
Make sure to do all the changes on the `$toCalculate` instance, since this is the cart that's going to be considered in the end.

Your processor has to be defined in the service container using the tag `shopware.cart.processor`.

## Next steps

If you want to see a better example on what can be done with a collector and a processor, you might want to have a look at our guide
regarding [Changing the price of an item in the cart](./change-price-of-item.md).

---

---
url: >-
  /docs/v6.5/guides/plugins/plugins/checkout/cart/add-cart-processor-collector.md
---

# Add Cart Collector/Processor

## Overview

In order to change the cart at runtime, you can use a custom [collector](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Core/Checkout/Cart/CartDataCollectorInterface.php)
or a custom [processor](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Core/Checkout/Cart/CartProcessorInterface.php).

Their main purpose is explained in their respective section.

## Collector class

A collector can and should be used to retrieve additional data for the cart, e.g. by querying the database, hence the name "collector".
This could also be querying an API endpoint, querying the database or fetching data in any other way you can think of.

Very often a collector is used to fetch data necessary for a processor.

It has to implement the interface `Shopware\Core\Checkout\Cart\CartDataCollectorInterface` and therefore implement a `collect` method.

But let's have a look at an example collector class.

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout\Cart;

use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Cart\CartBehavior;
use Shopware\Core\Checkout\Cart\CartDataCollectorInterface;
use Shopware\Core\Checkout\Cart\LineItem\CartDataCollection;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class CustomCartCollector implements CartDataCollectorInterface
{
    public function collect(CartDataCollection $data, Cart $original, SalesChannelContext $context, CartBehavior $behavior): void
    {
        // Do your stuff in order to collect data, this is just an example method call
        $newData = $this->collectData();

        $data->set('uniqueKey', $newData);
    }
}
```

The `collect` method's parameters are the following:

* `CartDataCollection`: Use this object to save your new cart data. You'll most likely use the `set` method here, which expects
  a unique key and its value. This object will be available in all processors.
* `Cart`: The current cart and its line items.
* `SalesChannelContext`: The current sales channel context, containing information about the currency, the country, etc.
* `CartBehavior`: It contains a cart state, which describes which actions are allowed. E.g. in the [product processor](https://github.com/shopware/shopware/blob/trunk/src/Core/Content/Product/Cart/ProductCartProcessor.php#L33), there's
  a permission to check if the product stock validation should be skipped.

Your collector has to be defined in the service container using the tag `shopware.cart.collector`.

## Processor class

A processor is the class that will actually process the cart and is supposed to apply changes to the cart.
It will most likely use data, that was previously fetched by a collector.

::: warning
Do not query data in the process method, since it may be executed a lot of times. Always use the collect method of a collector for this case!
:::

Your processor class has to implement the interface `Shopware\Core\Checkout\Cart\CartProcessorInterface` and its `process` method.

Let's have a look at an example processor.

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout\Cart;

use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Cart\CartBehavior;
use Shopware\Core\Checkout\Cart\CartProcessorInterface;
use Shopware\Core\Checkout\Cart\LineItem\CartDataCollection;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class CustomCartProcessor implements CartProcessorInterface
{
    public function process(CartDataCollection $data, Cart $original, Cart $toCalculate, SalesChannelContext $context, CartBehavior $behavior): void
    {
        $newData = $data->get('uniqueKey');

        // Do stuff to the `$toCalculate` cart with your new data
        foreach ($toCalculate->getLineItems()->getFlat() as $lineItem) {
            $lineItem->setPayload($newData['stuff']);
        }
    }
}
```

The `process` method contains the same parameters as the `collect` method, but there's one main difference:

Next to the `$original` `Cart`, you've got another `Cart` parameter being called `$toCalculate` here.
Make sure to do all the changes on the `$toCalculate` instance, since this is the cart that's going to be considered in the end.

Your processor has to be defined in the service container using the tag `shopware.cart.processor`.

## Next steps

If you want to see a better example on what can be done with a collector and a processor, you might want to have a look at our guide
regarding [Changing the price of an item in the cart](./change-price-of-item).

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/checkout/cart/add-cart-processor-collector.md
---

# Add Cart Collector/Processor

## Overview

In order to change the cart at runtime, you can use a custom [collector](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Core/Checkout/Cart/CartDataCollectorInterface.php)
or a custom [processor](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Core/Checkout/Cart/CartProcessorInterface.php).

Their main purpose is explained in their respective section.

## Collector class

A collector can and should be used to retrieve additional data for the cart, e.g. by querying the database, hence the name "collector".
This could also be querying an API endpoint, querying the database or fetching data in any other way you can think of.

Very often a collector is used to fetch data necessary for a processor.

It has to implement the interface `Shopware\Core\Checkout\Cart\CartDataCollectorInterface` and therefore implement a `collect` method.

But let's have a look at an example collector class.

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout\Cart;

use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Cart\CartBehavior;
use Shopware\Core\Checkout\Cart\CartDataCollectorInterface;
use Shopware\Core\Checkout\Cart\LineItem\CartDataCollection;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class CustomCartCollector implements CartDataCollectorInterface
{
    public function collect(CartDataCollection $data, Cart $original, SalesChannelContext $context, CartBehavior $behavior): void
    {
        // Do your stuff in order to collect data, this is just an example method call
        $newData = $this->collectData();

        $data->set('uniqueKey', $newData);
    }
}
```

The `collect` method's parameters are the following:

* `CartDataCollection`: Use this object to save your new cart data. You'll most likely use the `set` method here, which expects
  a unique key and its value. This object will be available in all processors.
* `Cart`: The current cart and its line items.
* `SalesChannelContext`: The current sales channel context, containing information about the currency, the country, etc.
* `CartBehavior`: It contains a cart state, which describes which actions are allowed. E.g. in the [product processor](https://github.com/shopware/shopware/blob/trunk/src/Core/Content/Product/Cart/ProductCartProcessor.php#L33), there's
  a permission to check if the product stock validation should be skipped.

Your collector has to be defined in the service container using the tag `shopware.cart.collector`.

## Processor class

A processor is the class that will actually process the cart and is supposed to apply changes to the cart.
It will most likely use data, that was previously fetched by a collector.

::: warning
Do not query data in the process method, since it may be executed a lot of times. Always use the collect method of a collector for this case!
:::

Your processor class has to implement the interface `Shopware\Core\Checkout\Cart\CartProcessorInterface` and its `process` method.

Let's have a look at an example processor.

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout\Cart;

use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Cart\CartBehavior;
use Shopware\Core\Checkout\Cart\CartProcessorInterface;
use Shopware\Core\Checkout\Cart\LineItem\CartDataCollection;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class CustomCartProcessor implements CartProcessorInterface
{
    public function process(CartDataCollection $data, Cart $original, Cart $toCalculate, SalesChannelContext $context, CartBehavior $behavior): void
    {
        $newData = $data->get('uniqueKey');

        // Do stuff to the `$toCalculate` cart with your new data
        foreach ($toCalculate->getLineItems()->getFlat() as $lineItem) {
            $lineItem->setPayload($newData['stuff']);
        }
    }
}
```

The `process` method contains the same parameters as the `collect` method, but there's one main difference:

Next to the `$original` `Cart`, you've got another `Cart` parameter being called `$toCalculate` here.
Make sure to do all the changes on the `$toCalculate` instance, since this is the cart that's going to be considered in the end.

Your processor has to be defined in the service container using the tag `shopware.cart.processor`.

## Next steps

If you want to see a better example on what can be done with a collector and a processor, you might want to have a look at our guide
regarding [Changing the price of an item in the cart](./change-price-of-item).

---

---
url: /docs/guides/plugins/plugins/checkout/cart/add-cart-discounts.md
---

# Add Cart Discounts

## Overview

This guide explains how to create discounts for your cart. In this example, we will create a discount for products that have 'Example' in their name.

## Prerequisites

Refer to the [Plugin Base Guide](../../plugin-base-guide) for information on creating plugins, and to the [Add custom service](../../services/add-custom-service.md) guide for details on service registration.

## Creating the processor

To add a discount to the cart, you should use the processor pattern. For this you need to create your own cart processor. We'll start with creating a new class called `ExampleProcessor` in the directory `<plugin root>/src/Core/Checkout`. Our class has to implement `Shopware\Core\Checkout\Cart\CartProcessorInterface` and we have to inject `Shopware\Core\Checkout\Cart\Price\PercentagePriceCalculator` in our constructor. All adjustments are done in the `process` method, where the product items already own a name and a price.

Let's start with the actual example code:

```php
// <plugin root>/src/Core/Checkout/ExampleProcessor.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout;

use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Cart\CartBehavior;
use Shopware\Core\Checkout\Cart\CartProcessorInterface;
use Shopware\Core\Checkout\Cart\LineItem\CartDataCollection;
use Shopware\Core\Checkout\Cart\LineItem\LineItem;
use Shopware\Core\Checkout\Cart\LineItem\LineItemCollection;
use Shopware\Core\Checkout\Cart\Price\PercentagePriceCalculator;
use Shopware\Core\Checkout\Cart\Price\Struct\PercentagePriceDefinition;
use Shopware\Core\Checkout\Cart\Rule\LineItemRule;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class ExampleProcessor implements CartProcessorInterface
{
    private PercentagePriceCalculator $calculator;

    public function __construct(PercentagePriceCalculator $calculator)
    {
        $this->calculator = $calculator;
    }

    public function process(CartDataCollection $data, Cart $original, Cart $toCalculate, SalesChannelContext $context, CartBehavior $behavior): void
    {
        $products = $this->findExampleProducts($toCalculate);

        // no example products found? early return
        if ($products->count() === 0) {
            return;
        }

        $discountLineItem = $this->createDiscount('EXAMPLE_DISCOUNT');

        // declare price definition to define how this price is calculated
        $definition = new PercentagePriceDefinition(
            -10,
            new LineItemRule(LineItemRule::OPERATOR_EQ, $products->getKeys())
        );

        $discountLineItem->setPriceDefinition($definition);

        // calculate price
        $discountLineItem->setPrice(
            $this->calculator->calculate($definition->getPercentage(), $products->getPrices(), $context)
        );

        // add discount to new cart
        $toCalculate->add($discountLineItem);
    }

    private function findExampleProducts(Cart $cart): LineItemCollection
    {
        return $cart->getLineItems()->filter(function (LineItem $item) {
            // Only consider products, not custom line items or promotional line items
            if ($item->getType() !== LineItem::PRODUCT_LINE_ITEM_TYPE) {
                return false;
            }

            $exampleInLabel = stripos($item->getLabel(), 'example') !== false;

            if (!$exampleInLabel) {
                return false;
            }

            return $item;
        });
    }

    private function createDiscount(string $name): LineItem
    {
        $discountLineItem = new LineItem($name, 'example_discount', null, 1);

        $discountLineItem->setLabel('Our example discount!');
        $discountLineItem->setGood(false);
        $discountLineItem->setStackable(false);
        $discountLineItem->setRemovable(false);

        return $discountLineItem;
    }
}
```

As you can see, all line items of type product containing the string 'example' in their name are fetched. Also, a few information are saved into variables, since we'll need them several times. If no product in the cart matches your condition, we can early return in the `process` method. Afterwards we create a new line item for the new discount. For the latter, we don't want that the line item is stackable and it shouldn't be removable either.

So let's get to the important part, which is the price. For a percentage discount, we have to use the `PercentagePriceDefinition`. It consists of an actual value, the currency precision and, if necessary, some rules to apply to. This definition is required for the cart to tell the core how this price can be recalculated even if the plugin would be uninstalled.

Shopware comes with a called `LineItemRule`, which requires two parameters:

* The operator being used, e.g. `LineItemRule::OPERATOR_EQ` (Equals) or `LineItemRule::OPERATOR_NEQ` (Not equals)
* The identifiers to apply the rule to. Pass the line item identifiers here, in this case the identifiers of the previously filtered products

After adding the definition to the line item, we have to calculate the current price of the discount. Therefore we can use the `PercentagePriceCalculator` of the core. The last step is to add the discount to the new cart which is provided as `Cart $toCalculate`.

That's it for the main code of our custom `CartProcessor`. Now we only have to register it in our `services.php` using the tag `shopware.cart.processor` and priority `4500`, which is used to get access to the calculation after the [product processor](https://github.com/shopware/shopware/blob/v6.7.14.0/src/Core/Checkout/DependencyInjection/cart.php#L505-L516) handled the products.

---

---
url: /docs/v6.5/guides/plugins/plugins/checkout/cart/add-cart-discounts.md
---

# Add Cart Discounts

## Overview

In this guide you'll learn how to create discounts for your cart. In this example, we will create a discount for products that have 'Example' in their name.

## Prerequisites

In order to create cart discounts for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../../plugin-base-guide).

Furthermore you should be familiar with the service registration in Shopware, otherwise head over to our [Add custom service](../../plugin-fundamentals/add-custom-service) guide.

## Creating the processor

To add a discount to the cart, you should use the processor pattern. For this you need to create your own cart processor. We'll start with creating a new class called `ExampleProcessor` in the directory `<plugin root>/src/Core/Checkout`. Our class has to implement `Shopware\Core\Checkout\Cart\CartProcessorInterface` and we have to inject `Shopware\Core\Checkout\Cart\Price\PercentagePriceCalculator` in our constructor. All adjustments are done in the `process` method, where the product items already own a name and a price.

Let's start with the actual example code:

```php
// <plugin root>/src/Core/Checkout/ExampleProcessor.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout;

use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Cart\CartBehavior;
use Shopware\Core\Checkout\Cart\CartProcessorInterface;
use Shopware\Core\Checkout\Cart\LineItem\CartDataCollection;
use Shopware\Core\Checkout\Cart\LineItem\LineItem;
use Shopware\Core\Checkout\Cart\LineItem\LineItemCollection;
use Shopware\Core\Checkout\Cart\Price\PercentagePriceCalculator;
use Shopware\Core\Checkout\Cart\Price\Struct\PercentagePriceDefinition;
use Shopware\Core\Checkout\Cart\Rule\LineItemRule;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class ExampleProcessor implements CartProcessorInterface
{
    private PercentagePriceCalculator $calculator;

    public function __construct(PercentagePriceCalculator $calculator)
    {
        $this->calculator = $calculator;
    }

    public function process(CartDataCollection $data, Cart $original, Cart $toCalculate, SalesChannelContext $context, CartBehavior $behavior): void
    {
        $products = $this->findExampleProducts($toCalculate);

        // no example products found? early return
        if ($products->count() === 0) {
            return;
        }

        $discountLineItem = $this->createDiscount('EXAMPLE_DISCOUNT');

        // declare price definition to define how this price is calculated
        $definition = new PercentagePriceDefinition(
            -10,
            new LineItemRule(LineItemRule::OPERATOR_EQ, $products->getKeys())
        );

        $discountLineItem->setPriceDefinition($definition);

        // calculate price
        $discountLineItem->setPrice(
            $this->calculator->calculate($definition->getPercentage(), $products->getPrices(), $context)
        );

        // add discount to new cart
        $toCalculate->add($discountLineItem);
    }

    private function findExampleProducts(Cart $cart): LineItemCollection
    {
        return $cart->getLineItems()->filter(function (LineItem $item) {
            // Only consider products, not custom line items or promotional line items
            if ($item->getType() !== LineItem::PRODUCT_LINE_ITEM_TYPE) {
                return false;
            }

            $exampleInLabel = stripos($item->getLabel(), 'example') !== false;

            if (!$exampleInLabel) {
                return false;
            }

            return $item;
        });
    }

    private function createDiscount(string $name): LineItem
    {
        $discountLineItem = new LineItem($name, 'example_discount', null, 1);

        $discountLineItem->setLabel('Our example discount!');
        $discountLineItem->setGood(false);
        $discountLineItem->setStackable(false);
        $discountLineItem->setRemovable(false);

        return $discountLineItem;
    }
}
```

As you can see, all line items of type product containing the string 'example' in their name are fetched. Also, a few information are saved into variables, since we'll need them several times. If no product in the cart matches your condition, we can early return in the `process` method. Afterwards we create a new line item for the new discount. For the latter, we don't want that the line item is stackable and it shouldn't be removable either.

So let's get to the important part, which is the price. For a percentage discount, we have to use the `PercentagePriceDefinition`. It consists of an actual value, the currency precision and, if necessary, some rules to apply to. This definition is required for the cart to tell the core how this price can be recalculated even if the plugin would be uninstalled.

Shopware comes with a called `LineItemRule`, which requires two parameters:

* The operator being used, e.g. `LineItemRule::OPERATOR_EQ` (Equals) or `LineItemRule::OPERATOR_NEQ` (Not equals)
* The identifiers to apply the rule to. Pass the line item identifiers here, in this case the identifiers of the previously filtered products

After adding the definition to the line item, we have to calculate the current price of the discount. Therefore we can use the `PercentagePriceCalculator` of the core. The last step is to add the discount to the new cart which is provided as `Cart $toCalculate`.

That's it for the main code of our custom `CartProcessor`. Now we only have to register it in our `services.xml` using the tag `shopware.cart.processor` and priority `4500`, which is used to get access to the calculation after the [product processor](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Core/Checkout/DependencyInjection/cart.xml#L223-L231) handled the products.

---

---
url: /docs/v6.6/guides/plugins/plugins/checkout/cart/add-cart-discounts.md
---

# Add Cart Discounts

## Overview

In this guide you'll learn how to create discounts for your cart. In this example, we will create a discount for products that have 'Example' in their name.

## Prerequisites

In order to create cart discounts for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../../plugin-base-guide).

Furthermore you should be familiar with the service registration in Shopware, otherwise head over to our [Add custom service](../../plugin-fundamentals/add-custom-service) guide.

## Creating the processor

To add a discount to the cart, you should use the processor pattern. For this you need to create your own cart processor. We'll start with creating a new class called `ExampleProcessor` in the directory `<plugin root>/src/Core/Checkout`. Our class has to implement `Shopware\Core\Checkout\Cart\CartProcessorInterface` and we have to inject `Shopware\Core\Checkout\Cart\Price\PercentagePriceCalculator` in our constructor. All adjustments are done in the `process` method, where the product items already own a name and a price.

Let's start with the actual example code:

```php
// <plugin root>/src/Core/Checkout/ExampleProcessor.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout;

use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Cart\CartBehavior;
use Shopware\Core\Checkout\Cart\CartProcessorInterface;
use Shopware\Core\Checkout\Cart\LineItem\CartDataCollection;
use Shopware\Core\Checkout\Cart\LineItem\LineItem;
use Shopware\Core\Checkout\Cart\LineItem\LineItemCollection;
use Shopware\Core\Checkout\Cart\Price\PercentagePriceCalculator;
use Shopware\Core\Checkout\Cart\Price\Struct\PercentagePriceDefinition;
use Shopware\Core\Checkout\Cart\Rule\LineItemRule;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class ExampleProcessor implements CartProcessorInterface
{
    private PercentagePriceCalculator $calculator;

    public function __construct(PercentagePriceCalculator $calculator)
    {
        $this->calculator = $calculator;
    }

    public function process(CartDataCollection $data, Cart $original, Cart $toCalculate, SalesChannelContext $context, CartBehavior $behavior): void
    {
        $products = $this->findExampleProducts($toCalculate);

        // no example products found? early return
        if ($products->count() === 0) {
            return;
        }

        $discountLineItem = $this->createDiscount('EXAMPLE_DISCOUNT');

        // declare price definition to define how this price is calculated
        $definition = new PercentagePriceDefinition(
            -10,
            new LineItemRule(LineItemRule::OPERATOR_EQ, $products->getKeys())
        );

        $discountLineItem->setPriceDefinition($definition);

        // calculate price
        $discountLineItem->setPrice(
            $this->calculator->calculate($definition->getPercentage(), $products->getPrices(), $context)
        );

        // add discount to new cart
        $toCalculate->add($discountLineItem);
    }

    private function findExampleProducts(Cart $cart): LineItemCollection
    {
        return $cart->getLineItems()->filter(function (LineItem $item) {
            // Only consider products, not custom line items or promotional line items
            if ($item->getType() !== LineItem::PRODUCT_LINE_ITEM_TYPE) {
                return false;
            }

            $exampleInLabel = stripos($item->getLabel(), 'example') !== false;

            if (!$exampleInLabel) {
                return false;
            }

            return $item;
        });
    }

    private function createDiscount(string $name): LineItem
    {
        $discountLineItem = new LineItem($name, 'example_discount', null, 1);

        $discountLineItem->setLabel('Our example discount!');
        $discountLineItem->setGood(false);
        $discountLineItem->setStackable(false);
        $discountLineItem->setRemovable(false);

        return $discountLineItem;
    }
}
```

As you can see, all line items of type product containing the string 'example' in their name are fetched. Also, a few information are saved into variables, since we'll need them several times. If no product in the cart matches your condition, we can early return in the `process` method. Afterwards we create a new line item for the new discount. For the latter, we don't want that the line item is stackable and it shouldn't be removable either.

So let's get to the important part, which is the price. For a percentage discount, we have to use the `PercentagePriceDefinition`. It consists of an actual value, the currency precision and, if necessary, some rules to apply to. This definition is required for the cart to tell the core how this price can be recalculated even if the plugin would be uninstalled.

Shopware comes with a called `LineItemRule`, which requires two parameters:

* The operator being used, e.g. `LineItemRule::OPERATOR_EQ` (Equals) or `LineItemRule::OPERATOR_NEQ` (Not equals)
* The identifiers to apply the rule to. Pass the line item identifiers here, in this case the identifiers of the previously filtered products

After adding the definition to the line item, we have to calculate the current price of the discount. Therefore we can use the `PercentagePriceCalculator` of the core. The last step is to add the discount to the new cart which is provided as `Cart $toCalculate`.

That's it for the main code of our custom `CartProcessor`. Now we only have to register it in our `services.xml` using the tag `shopware.cart.processor` and priority `4500`, which is used to get access to the calculation after the [product processor](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Core/Checkout/DependencyInjection/cart.xml#L223-L231) handled the products.

---

---
url: /docs/guides/plugins/plugins/checkout/cart/add-cart-items.md
---

# Add Cart Items

## Overview

This guide will show you how to create line items like products, promotion and other types and add them to the cart. It will also cover creating a custom LineItemHandler.

## Prerequisites

Review the [Plugin base guide](../../plugin-base-guide) for general information about plugins. The guides on [Adding a custom page](../../storefront/controllers/add-custom-page.md), which explains how to add a custom Storefront controller, and [Dependency injection](../../services/dependency-injection.md), which addresses registering classes or services to the DI container, are also recommended.

## Adding a simple item

For this guide, we will use an example controller, that is already registered. The process of creating such a controller is not explained here, for that case head over to our guide about [Adding a custom page](../../storefront/controllers/add-custom-page.md).

However, having a controller is not a necessity here, it just comes with the advantage of fetching the current cart by adding `\Shopware\Core\Checkout\Cart\Cart` as a method argument, which will automatically be filled by our argument resolver.

If you're planning to use this guide for something else but a controller, you can fetch the current cart with the `\Shopware\Core\Checkout\Cart\SalesChannel\CartService::getCart` method.

So let's add an example product to the cart using code. For that case, you'll need to have access to both the services `\Shopware\Core\Checkout\Cart\LineItemFactoryRegistry` and `\Shopware\Core\Checkout\Cart\SalesChannel\CartService` supplied to your controller or service via [Dependency injection](../../services/dependency-injection.md).

Let's have a look at an example.

```php
// <plugin root>/src/Service/ExampleController.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Cart\LineItem\LineItem;
use Shopware\Core\Checkout\Cart\LineItemFactoryRegistry;
use Shopware\Core\Checkout\Cart\SalesChannel\CartService;
use Shopware\Core\PlatformRequest;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Controller\StorefrontController;
use Shopware\Storefront\Framework\Routing\StorefrontResponse;
use Shopware\Storefront\Framework\Routing\StorefrontRouteScope;
use Symfony\Component\Routing\Attribute\Route;

#[Route(defaults: [PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [StorefrontRouteScope::ID]])]
class ExampleController extends StorefrontController
{
    private LineItemFactoryRegistry $factory;

    private CartService $cartService;

    public function __construct(LineItemFactoryRegistry $factory, CartService $cartService)
    {
        $this->factory = $factory;
        $this->cartService = $cartService;
    }

    #[Route(path: '/cartAdd', name: 'frontend.example', methods: ['GET'])]
    public function add(Cart $cart, SalesChannelContext $context): StorefrontResponse
    {
        // Create product line item
        $lineItem = $this->factory->create([
            'type' => LineItem::PRODUCT_LINE_ITEM_TYPE, // Results in 'product'
            'referencedId' => 'myExampleId', // this is not a valid UUID, change this to your actual ID!
            'quantity' => 5,
            'payload' => ['key' => 'value']
        ], $context);

        $this->cartService->add($cart, $lineItem, $context);

        return $this->renderStorefront('@Storefront/storefront/base.html.twig');
    }
}
```

As mentioned earlier, you can just apply the `Cart` argument to your method and it will be automatically filled.

Afterwards you create a line item using the `LineItemFactoryRegistry` and its `create` method. It is mandatory to supply the `type` property, which can be one of the following by default:

* product
* promotion
* credit
* custom

The `LineItemFactoryRegistry` holds a collection of handlers to create a line item of a specific type. Each line item type needs an own handler, which is covered later in this guide. If the type is not supported, it will throw a `\Shopware\Core\Checkout\Cart\Exception\LineItemTypeNotSupportedException` exception.

Other than that, we apply the `referencedId`, which in this case points to the product ID that we want to add. If you were to add a line item of type `promotion`, the `referencedId` would have to point to the respective promotion ID. The `quantity` field just contains the quantity of line items which you want to add to the cart.

Now have a look at the `payload` field, which only contains dummy data in this example. The `payload` field can contain any additional data that you need to attach to a line item in order to properly handle your business logic. E.g. the information about the chosen options of a configurable product are saved in there. Feel free to use this one to apply important information to your line item, that you might have to process later on, e.g. in the template.

You can find a list of all available fields in the [createValidatorDefinition method of the LineItemFactoryRegistry](https://github.com/shopware/shopware/blob/v6.3.5.0/src/Core/Checkout/Cart/LineItemFactoryRegistry.php#L113-L142).

If you now call the route `/cartAdd`, it should add the product with the ID `myExampleId` to the cart, 5 times.

## Create new factory handler

Sometimes you really want to have a custom line item handler, e.g. for your own new entity, such as a bundle entity or alike. For that case, you can create your own line item handler, which will then be available in the `LineItemFactoryRegistry` as a valid `type` option.

You need to create a new class which implements the interface `\Shopware\Core\Checkout\Cart\LineItemFactoryHandler\LineItemFactoryInterface` and it needs to be registered in the DI container with the tag `shopware.cart.line_item.factory`.

```php
// <plugin root>/src/Resources/config/services.php
<?php declare(strict_types=1);

use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Swag\BasicExample\Service\ExampleHandler;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(ExampleHandler::class)
        ->tag('shopware.cart.line_item.factory');
};
```

Let's first have a look at an example handler:

```php
// <plugin root>/src/Service/ExampleHandler.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Checkout\Cart\LineItem\LineItem;
use Shopware\Core\Checkout\Cart\LineItemFactoryHandler\LineItemFactoryInterface;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class ExampleHandler implements LineItemFactoryInterface
{
    public const TYPE = 'example';

    public function supports(string $type): bool
    {
        return $type === self::TYPE;
    }

    public function create(array $data, SalesChannelContext $context): LineItem
    {
        return new LineItem($data['id'], self::TYPE, $data['referencedId'] ?? null, 1);
    }

    public function update(LineItem $lineItem, array $data, SalesChannelContext $context): void
    {
        if (isset($data['referencedId'])) {
            $lineItem->setReferencedId($data['referencedId']);
        }
    }
}
```

Implementing the `LineItemFactoryInterface` will force you to also implement three new methods:

* `supports`: A method that is applied a string `$type`. This method has to return a bool whether or not it supports this type.

  In this example, this handler supports the line item type `example`.

* `create`: This method is responsible for actually creating an instance of a `LineItem`. Apply everything necessary for your custom line item type

  here, such as fields, that always have to be set for your case. It is called when the method `create` of the `LineItemFactoryRegistry` is called,

  just like in the example earlier in this guide.

* `update`: This method is called the method `update` of the `LineItemFactoryRegistry` is called. Just as the name suggests, your line item will be updated.

  Here you can define which properties of your line item may actually be updated. E.g. if you really want property X to contain "Y", you can do so here.

Now you'll need to add a processor for your type. Otherwise your item won't be persisted in the cart. A simple processor for our ExampleHandler could look like this:

```php
// <plugin root>/Core/Checkout/Cart/ExampleProcessor.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout\Cart;

use Swag\BasicExample\Service\ExampleHandler;
use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Cart\CartBehavior;
use Shopware\Core\Checkout\Cart\CartProcessorInterface;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Core\Checkout\Cart\LineItem\CartDataCollection;

class ExampleProcessor implements CartProcessorInterface
{

    public function process(CartDataCollection $data, Cart $original, Cart $toCalculate, SalesChannelContext $context, CartBehavior $behavior): void
    {
        $lineItems = $original->getLineItems()->filterFlatByType(ExampleHandler::TYPE);

        foreach ($lineItems as $lineItem){
            $toCalculate->add($lineItem);
        }
    }
}
```

As you can see, this processor takes an "original cart" as an input and adds all instances of our example type to a second cart, which will actually be persisted.

Of course you can use processors to do much more than this. Have a look at [adding cart processors and collectors](./add-cart-processor-collector).

Now register this processor in your `services.php` like this:

```php
// <plugin root>/src/Resources/config/services.php
<?php declare(strict_types=1);

use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Swag\BasicExample\Core\Checkout\Cart\ExampleProcessor;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(ExampleProcessor::class)
        ->tag('shopware.cart.processor', ['priority' => 4800]);
};
```

And that's it. You should now be able to create line items of type `example`.

## Adding nested line item

When implementing nested line items, the plugins have to implement their own processing logic or alternatively extend Shopware's cart processors.

A plugin that reuses core line items can easily call the other processors to handle the nested line items themselves. Refer to [nested line items](../../../../../resources/references/adr/2021-03-24-nested-line-items.md) section of the guide for more information.

---

---
url: /docs/v6.5/guides/plugins/plugins/checkout/cart/add-cart-items.md
---

# Add Cart Items

## Overview

This guide will show you how to create line items like products, promotion and other types and add them to the cart. It will also cover creating a custom LineItemHandler.

## Prerequisites

As most guides, this guide is also built upon the [Plugin base guide](../../plugin-base-guide), but you don't necessarily need that. It will use an example Storefront controller, so if you don't know how to add a custom Storefront controller yet, have a look at our guide about [Adding a custom page](../../storefront/add-custom-page). Furthermore, registering classes or services to the DI container is also not explained here, but it's covered in our guide about [Dependency injection](../../plugin-fundamentals/dependency-injection), so having this open in another tab won't hurt.

## Adding a simple item

For this guide, we will use an example controller, that is already registered. The process of creating such a controller is not explained here, for that case head over to our guide about [Adding a custom page](../../storefront/add-custom-page).

However, having a controller is not a necessity here, it just comes with the advantage of fetching the current cart by adding `\Shopware\Core\Checkout\Cart\Cart` as a method argument, which will automatically be filled by our argument resolver.

If you're planning to use this guide for something else but a controller, you can fetch the current cart with the `\Shopware\Core\Checkout\Cart\SalesChannel\CartService::getCart` method.

So let's add an example product to the cart using code. For that case, you'll need to have access to both the services `\Shopware\Core\Checkout\Cart\LineItemFactoryRegistry` and `\Shopware\Core\Checkout\Cart\SalesChannel\CartService` supplied to your controller or service via [Dependency injection](../../plugin-fundamentals/dependency-injection).

Let's have a look at an example.

```php
// <plugin root>/src/Service/ExampleController.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Checkout\Cart\LineItem\LineItem;
use Shopware\Core\Checkout\Cart\LineItemFactoryRegistry;
use Shopware\Core\Checkout\Cart\SalesChannel\CartService;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Controller\StorefrontController;
use Shopware\Storefront\Framework\Routing\StorefrontResponse;
use Symfony\Component\Routing\Annotation\Route;
use Shopware\Core\Checkout\Cart\Cart;

#[Route(defaults: ['_routeScope' => ['storefront']])]
class ExampleController extends StorefrontController
{
    private LineItemFactoryRegistry $factory;

    private CartService $cartService;

    public function __construct(LineItemFactoryRegistry $factory, CartService $cartService)
    {
        $this->factory = $factory;
        $this->cartService = $cartService;
    }

    #[Route(path: '/cartAdd', name: 'frontend.example', methods: ['GET'])]
    public function add(Cart $cart, SalesChannelContext $context): StorefrontResponse
    {
        // Create product line item
        $lineItem = $this->factory->create([
            'type' => LineItem::PRODUCT_LINE_ITEM_TYPE, // Results in 'product'
            'referencedId' => 'myExampleId', // this is not a valid UUID, change this to your actual ID!
            'quantity' => 5,
            'payload' => ['key' => 'value']
        ], $context);

        $this->cartService->add($cart, $lineItem, $context);

        return $this->renderStorefront('@Storefront/storefront/base.html.twig');
    }
}
```

As mentioned earlier, you can just apply the `Cart` argument to your method and it will be automatically filled.

Afterwards you create a line item using the `LineItemFactoryRegistry` and its `create` method. It is mandatory to supply the `type` property, which can be one of the following by default:

* product
* promotion
* credit
* custom

The `LineItemFactoryRegistry` holds a collection of handlers to create a line item of a specific type. Each line item type needs an own handler, which is covered later in this guide. If the type is not supported, it will throw a `\Shopware\Core\Checkout\Cart\Exception\LineItemTypeNotSupportedException` exception.

Other than that, we apply the `referencedId`, which in this case points to the product ID that we want to add. If you were to add a line item of type `promotion`, the `referencedId` would have to point to the respective promotion ID. The `quantity` field just contains the quantity of line items which you want to add to the cart.

Now have a look at the `payload` field, which only contains dummy data in this example. The `payload` field can contain any additional data that you need to attach to a line item in order to properly handle your business logic. E.g. the information about the chosen options of a configurable product are saved in there. Feel free to use this one to apply important information to your line item, that you might have to process later on, e.g. in the template.

You can find a list of all available fields in the [createValidatorDefinition method of the LineItemFactoryRegistry](https://github.com/shopware/shopware/blob/v6.3.5.0/src/Core/Checkout/Cart/LineItemFactoryRegistry.php#L113-L142).

If you now call the route `/cartAdd`, it should add the product with the ID `myExampleId` to the cart, 5 times.

## Create new factory handler

Sometimes you really want to have a custom line item handler, e.g. for your own new entity, such as a bundle entity or alike. For that case, you can create your own line item handler, which will then be available in the `LineItemFactoryRegistry` as a valid `type` option.

You need to create a new class which implements the interface `\Shopware\Core\Checkout\Cart\LineItemFactoryHandler\LineItemFactoryInterface` and it needs to be registered in the DI container with the tag `shopware.cart.line_item.factory`.

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Service\ExampleHandler">
            <tag name="shopware.cart.line_item.factory" />
        </service>
    </services>
</container>
```

Let's first have a look at an example handler:

```php
// <plugin root>/src/Service/ExampleHandler.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Checkout\Cart\LineItem\LineItem;
use Shopware\Core\Checkout\Cart\LineItemFactoryHandler\LineItemFactoryInterface;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class ExampleHandler implements LineItemFactoryInterface
{
    public const TYPE = 'example';

    public function supports(string $type): bool
    {
        return $type === self::TYPE;
    }

    public function create(array $data, SalesChannelContext $context): LineItem
    {
        return new LineItem($data['id'], self::TYPE, $data['referencedId'] ?? null, 1);
    }

    public function update(LineItem $lineItem, array $data, SalesChannelContext $context): void
    {
        if (isset($data['referencedId'])) {
            $lineItem->setReferencedId($data['referencedId']);
        }
    }
}
```

Implementing the `LineItemFactoryInterface` will force you to also implement three new methods:

* `supports`: A method that is applied a string `$type`. This method has to return a bool whether or not it supports this type.

  In this example, this handler supports the line item type `example`.

* `create`: This method is responsible for actually creating an instance of a `LineItem`. Apply everything necessary for your custom line item type

  here, such as fields, that always have to be set for your case. It is called when the method `create` of the `LineItemFactoryRegistry` is called,

  just like in the example earlier in this guide.

* `update`: This method is called the method `update` of the `LineItemFactoryRegistry` is called. Just as the name suggests, your line item will be updated.

  Here you can define which properties of your line item may actually be updated. E.g. if you really want property X to contain "Y", you can do so here.

Now you'll need to add a processor for your type. Otherwise your item won't be persisted in the cart. A simple processor for our ExampleHandler could look like this:

```php
// <plugin root>/Core/Checkout/Cart/ExampleProcessor.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout\Cart;

use Swag\BasicExample\Service\ExampleHandler;
use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Cart\CartBehavior;
use Shopware\Core\Checkout\Cart\CartProcessorInterface;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Core\Checkout\Cart\LineItem\CartDataCollection;

class ExampleProcessor implements CartProcessorInterface
{

    public function process(CartDataCollection $data, Cart $original, Cart $toCalculate, SalesChannelContext $context, CartBehavior $behavior): void
    {
        $lineItems = $original->getLineItems()->filterFlatByType(ExampleHandler::TYPE);

        foreach ($lineItems as $lineItem){
            $toCalculate->add($lineItem);
        }
    }
}
```

As you can see, this processor takes an "original cart" as an input and adds all instances of our example type to a second cart, which will actually be persisted.

Of course you can use processors to do much more than this. Have a look at [adding cart processors and collectors](./add-cart-processor-collector).

Now register this processor in your `services.xml` like this:

```html
// <plugin root>/Resources/config/services.xml
...
<services>
    ...
    <service id="Swag\BasicExample\Core\Checkout\Cart\ExampleProcessor">
        <tag name="shopware.cart.processor" priority="4800"/>
    </service>
</services>
```

And that's it. You should now be able to create line items of type `example`.

## Adding nested line item

When implementing nested line items, the plugins have to implement their own processing logic or alternatively extend Shopware's cart processors.

A plugin that reuses core line items can easily call the other processors to handle the nested line items themselves. Refer to [nested line items](../../../../../resources/references/adr/2021-03-24-nested-line-items.md) section of the guide for more information.

---

---
url: /docs/v6.6/guides/plugins/plugins/checkout/cart/add-cart-items.md
---

# Add Cart Items

## Overview

This guide will show you how to create line items like products, promotion and other types and add them to the cart. It will also cover creating a custom LineItemHandler.

## Prerequisites

As most guides, this guide is also built upon the [Plugin base guide](../../plugin-base-guide), but you don't necessarily need that. It will use an example Storefront controller, so if you don't know how to add a custom Storefront controller yet, have a look at our guide about [Adding a custom page](../../storefront/add-custom-page). Furthermore, registering classes or services to the DI container is also not explained here, but it's covered in our guide about [Dependency injection](../../plugin-fundamentals/dependency-injection), so having this open in another tab won't hurt.

## Adding a simple item

For this guide, we will use an example controller, that is already registered. The process of creating such a controller is not explained here, for that case head over to our guide about [Adding a custom page](../../storefront/add-custom-page).

However, having a controller is not a necessity here, it just comes with the advantage of fetching the current cart by adding `\Shopware\Core\Checkout\Cart\Cart` as a method argument, which will automatically be filled by our argument resolver.

If you're planning to use this guide for something else but a controller, you can fetch the current cart with the `\Shopware\Core\Checkout\Cart\SalesChannel\CartService::getCart` method.

So let's add an example product to the cart using code. For that case, you'll need to have access to both the services `\Shopware\Core\Checkout\Cart\LineItemFactoryRegistry` and `\Shopware\Core\Checkout\Cart\SalesChannel\CartService` supplied to your controller or service via [Dependency injection](../../plugin-fundamentals/dependency-injection).

Let's have a look at an example.

```php
// <plugin root>/src/Service/ExampleController.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Checkout\Cart\LineItem\LineItem;
use Shopware\Core\Checkout\Cart\LineItemFactoryRegistry;
use Shopware\Core\Checkout\Cart\SalesChannel\CartService;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Controller\StorefrontController;
use Shopware\Storefront\Framework\Routing\StorefrontResponse;
use Symfony\Component\Routing\Attribute\Route;
use Shopware\Core\Checkout\Cart\Cart;

#[Route(defaults: ['_routeScope' => ['storefront']])]
class ExampleController extends StorefrontController
{
    private LineItemFactoryRegistry $factory;

    private CartService $cartService;

    public function __construct(LineItemFactoryRegistry $factory, CartService $cartService)
    {
        $this->factory = $factory;
        $this->cartService = $cartService;
    }

    #[Route(path: '/cartAdd', name: 'frontend.example', methods: ['GET'])]
    public function add(Cart $cart, SalesChannelContext $context): StorefrontResponse
    {
        // Create product line item
        $lineItem = $this->factory->create([
            'type' => LineItem::PRODUCT_LINE_ITEM_TYPE, // Results in 'product'
            'referencedId' => 'myExampleId', // this is not a valid UUID, change this to your actual ID!
            'quantity' => 5,
            'payload' => ['key' => 'value']
        ], $context);

        $this->cartService->add($cart, $lineItem, $context);

        return $this->renderStorefront('@Storefront/storefront/base.html.twig');
    }
}
```

As mentioned earlier, you can just apply the `Cart` argument to your method and it will be automatically filled.

Afterwards you create a line item using the `LineItemFactoryRegistry` and its `create` method. It is mandatory to supply the `type` property, which can be one of the following by default:

* product
* promotion
* credit
* custom

The `LineItemFactoryRegistry` holds a collection of handlers to create a line item of a specific type. Each line item type needs an own handler, which is covered later in this guide. If the type is not supported, it will throw a `\Shopware\Core\Checkout\Cart\Exception\LineItemTypeNotSupportedException` exception.

Other than that, we apply the `referencedId`, which in this case points to the product ID that we want to add. If you were to add a line item of type `promotion`, the `referencedId` would have to point to the respective promotion ID. The `quantity` field just contains the quantity of line items which you want to add to the cart.

Now have a look at the `payload` field, which only contains dummy data in this example. The `payload` field can contain any additional data that you need to attach to a line item in order to properly handle your business logic. E.g. the information about the chosen options of a configurable product are saved in there. Feel free to use this one to apply important information to your line item, that you might have to process later on, e.g. in the template.

You can find a list of all available fields in the [createValidatorDefinition method of the LineItemFactoryRegistry](https://github.com/shopware/shopware/blob/v6.3.5.0/src/Core/Checkout/Cart/LineItemFactoryRegistry.php#L113-L142).

If you now call the route `/cartAdd`, it should add the product with the ID `myExampleId` to the cart, 5 times.

## Create new factory handler

Sometimes you really want to have a custom line item handler, e.g. for your own new entity, such as a bundle entity or alike. For that case, you can create your own line item handler, which will then be available in the `LineItemFactoryRegistry` as a valid `type` option.

You need to create a new class which implements the interface `\Shopware\Core\Checkout\Cart\LineItemFactoryHandler\LineItemFactoryInterface` and it needs to be registered in the DI container with the tag `shopware.cart.line_item.factory`.

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Service\ExampleHandler">
            <tag name="shopware.cart.line_item.factory" />
        </service>
    </services>
</container>
```

Let's first have a look at an example handler:

```php
// <plugin root>/src/Service/ExampleHandler.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Checkout\Cart\LineItem\LineItem;
use Shopware\Core\Checkout\Cart\LineItemFactoryHandler\LineItemFactoryInterface;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class ExampleHandler implements LineItemFactoryInterface
{
    public const TYPE = 'example';

    public function supports(string $type): bool
    {
        return $type === self::TYPE;
    }

    public function create(array $data, SalesChannelContext $context): LineItem
    {
        return new LineItem($data['id'], self::TYPE, $data['referencedId'] ?? null, 1);
    }

    public function update(LineItem $lineItem, array $data, SalesChannelContext $context): void
    {
        if (isset($data['referencedId'])) {
            $lineItem->setReferencedId($data['referencedId']);
        }
    }
}
```

Implementing the `LineItemFactoryInterface` will force you to also implement three new methods:

* `supports`: A method that is applied a string `$type`. This method has to return a bool whether or not it supports this type.

  In this example, this handler supports the line item type `example`.

* `create`: This method is responsible for actually creating an instance of a `LineItem`. Apply everything necessary for your custom line item type

  here, such as fields, that always have to be set for your case. It is called when the method `create` of the `LineItemFactoryRegistry` is called,

  just like in the example earlier in this guide.

* `update`: This method is called the method `update` of the `LineItemFactoryRegistry` is called. Just as the name suggests, your line item will be updated.

  Here you can define which properties of your line item may actually be updated. E.g. if you really want property X to contain "Y", you can do so here.

Now you'll need to add a processor for your type. Otherwise your item won't be persisted in the cart. A simple processor for our ExampleHandler could look like this:

```php
// <plugin root>/Core/Checkout/Cart/ExampleProcessor.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout\Cart;

use Swag\BasicExample\Service\ExampleHandler;
use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Cart\CartBehavior;
use Shopware\Core\Checkout\Cart\CartProcessorInterface;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Core\Checkout\Cart\LineItem\CartDataCollection;

class ExampleProcessor implements CartProcessorInterface
{

    public function process(CartDataCollection $data, Cart $original, Cart $toCalculate, SalesChannelContext $context, CartBehavior $behavior): void
    {
        $lineItems = $original->getLineItems()->filterFlatByType(ExampleHandler::TYPE);

        foreach ($lineItems as $lineItem){
            $toCalculate->add($lineItem);
        }
    }
}
```

As you can see, this processor takes an "original cart" as an input and adds all instances of our example type to a second cart, which will actually be persisted.

Of course you can use processors to do much more than this. Have a look at [adding cart processors and collectors](./add-cart-processor-collector).

Now register this processor in your `services.xml` like this:

```html
// <plugin root>/Resources/config/services.xml
...
<services>
    ...
    <service id="Swag\BasicExample\Core\Checkout\Cart\ExampleProcessor">
        <tag name="shopware.cart.processor" priority="4800"/>
    </service>
</services>
```

And that's it. You should now be able to create line items of type `example`.

## Adding nested line item

When implementing nested line items, the plugins have to implement their own processing logic or alternatively extend Shopware's cart processors.

A plugin that reuses core line items can easily call the other processors to handle the nested line items themselves. Refer to [nested line items](../../../../../resources/references/adr/2021-03-24-nested-line-items.md) section of the guide for more information.

---

---
url: /docs/guides/plugins/plugins/checkout/cart/add-cart-validator.md
---

# Add Cart Validator

## Overview

The cart in Shopware is continuously validated by so-called "validators" that check for invalid line items (label missing), shipping addresses, and other attributes.

This guide explains how to add your own custom cart validator.

## Prerequisites

Review the [plugin base guide](../../plugin-base-guide) to create a plugin. Familiarity with the [Dependency Injection container](../../services/dependency-injection.md), which you will use to register your custom validator, is also necessary.

## Adding a custom cart validator

We'll create several things throughout this guide, in that order:

* The validator itself
* A new exception being thrown by the validator if needed
* Snippets to print a proper error message

### The validator

The validator being created in this example is assuming you've got custom payload data in your line items to validate against. This is just an example and will always result in an error, since the data requested doesn't exist by default, until you add them.

A validator should be placed in the proper domain. That means, that an Address validator should be in a directory `<plugin root>/src/Core/Checkout/Cart/Address`. Since the validator in the following example will be called `CustomCartValidator`, its directory will be `<plugin root>/src/Core/Checkout/Cart/Custom`.

Your validator has to implement the interface `Shopware\Core\Checkout\Cart\CartValidatorInterface`. This forces you to also implement a `validate` method.

But let's have a look at the example validator first:

```php
// <plugin root>/src/Core/Checkout/Cart/Custom/CustomCartValidator.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout\Cart\Custom;

use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Cart\CartValidatorInterface;
use Shopware\Core\Checkout\Cart\Error\ErrorCollection;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Swag\BasicExample\Core\Checkout\Cart\Custom\Error\CustomCartBlockedError;

class CustomCartValidator implements CartValidatorInterface
{
    public function validate(Cart $cart, ErrorCollection $errorCollection, SalesChannelContext $salesChannelContext): void
    {
        foreach ($cart->getLineItems()->getFlat() as $lineItem) {
            if (!array_key_exists('customPayload', $lineItem->getPayload()) || $lineItem->getPayload()['customPayload'] !== 'example') {
                $errorCollection->add(new CustomCartBlockedError($lineItem->getId()));

                return;
            }
        }
    }
}
```

As already said, a cart validator has to implement the `CartValidatorInterface` and therefore implement a `validate` method. This method has access to some important parts of the checkout, such as the cart and the current sales channel context. Also you have access to the error collection, which may or may not contain errors from other earlier validators.

In this example we're dealing with the line items and are validating them, so we're iterating over each line item. This example assumes that your line items got a custom payload, called `customPayload`, and it expects a value in there.

If the condition doesn't match and the line item seems to be invalid, you'll have to add a new error to the error collection. You can't just use any exception here, but a class which has to extend from `Shopware\Core\Checkout\Cart\Error\Error`. Most likely you want to create your own error class here, which will be done in the next step.

Important to note is the `return` statement afterwards. If you wouldn't return here, it would add an error to the error collection for each invalid line item, resulting in several errors displayed on the checkout or the cart page. E.g. if you had four invalid items in your cart, four separate errors would be shown. This way, only one message is shown, so it depends on what you're validating and what you want to happen.

#### Registering the validator

One more thing to do is to register your new validator to the [dependency injection container](../../services/dependency-injection.md).

Your validator has to be registered using the tag `shopware.cart.validator`:

```php
// <plugin root>/src/Resources/config/services.php
<?php declare(strict_types=1);

use Swag\BasicExample\Core\Checkout\Cart\Custom\CustomCartValidator;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(CustomCartValidator::class)
        ->tag('shopware.cart.validator');
};
```

### Adding the custom cart error

The custom cart error class will be called `CustomCartBlockedError` and should be located in a `Error` directory in the same domain as the validator. Since the validator was located in the directory `<plugin root>/src/Core/Checkout/Cart/Custom`, the error class will be located in the directory `<plugin root>/src/Core/Checkout/Cart/Custom/Error`.

It has to extend from the abstract class `Shopware\Core\Checkout\Cart\Error\Error`, which asks you to implement a few methods:

* `getId`: Here you have to return a unique ID, since your error will be saved via this ID in the error collection. In this example,

  we'll just use the line item ID here.

* `getMessageKey`: The snippet key of the message to be displayed. In this example it will be `custom-line-item-blocked`, which is important

  for the next section of this guide, for adding the snippets.

* `getLevel`: The kind of error, available are `notice`, `warning` and `error`. Depending on that decision, the error will be printed in a blue,

  yellow or red box respectively. This example will use the error here.

* `blockOrder`: Return a boolean on whether this exception should block the possibility to actually finish the checkout.

  In this case it will be `true`, hence the error level defined earlier. It wouldn't make sense to block the checkout, but only display a notice.

* `blockResubmit`: Optional, return a boolean on whether this exception block the user from trying to finish the checkout again.

  If you want to use it, add the method `blockResubmit(): bool` to your custom error. If you don't, it is `true` by default.

* `getParameters`: You can add custom payload here. Technically any plugin or code could read the errors of the cart and act accordingly.

  If you need extra payload to your error class, this is the place to go.

So now let's have a look at the example error class:

```php
// <plugin root>/src/Core/Checkout/Cart/Custom/Error/CustomCartBlockedError.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout\Cart\Custom\Error;

use Shopware\Core\Checkout\Cart\Error\Error;

class CustomCartBlockedError extends Error
{
    private const KEY = 'custom-line-item-blocked';

    private string $lineItemId;

    public function __construct(string $lineItemId)
    {
        $this->lineItemId = $lineItemId;
        parent::__construct();
    }

    public function getId(): string
    {
        return $this->lineItemId;
    }

    public function getMessageKey(): string
    {
        return self::KEY;
    }

    public function getLevel(): int
    {
//        return self::LEVEL_NOTICE;
//        return self::LEVEL_WARNING;
        return self::LEVEL_ERROR;
    }

    public function blockOrder(): bool
    {
        return true;
    }

    public function getParameters(): array
    {
        return [ 'lineItemId' => $this->lineItemId ];
    }
}
```

The constructor was overridden so we can ask for the line item ID and save it in a property. Since we already used this class in the validator, we're basically done with that part here.

Only the snippets are missing.

### Adding the snippet

Review the guide on [adding storefront snippets](../../storefront/styling/add-translations.md).

You've defined the error key to be `custom-line-item-blocked` in your custom error class `CustomCartBlockedError`. Once your validator finds an invalid line item in your cart, Shopware is going to search for a respective snippet. In the cart, Shopware will be looking for the following snippet key: `checkout.custom-line-item-blocked`. Meanwhile it will be looking for a key `error.custom-line-item-blocked` in the checkout steps. This way you could technically define two different messages for the cart and the following checkout steps.

Now let's have a look at an example snippet file:

```javascript
// <plugin root>/src/Resources/snippet/en\_GB/example.en-GB.json
{
    "checkout": {
        "custom-line-item-blocked": "Example error message for the cart"
    },
    "error": {
        "custom-line-item-blocked": "Example error message for the checkout"
    }
}
```

This way Shopware will find the new snippets in your plugin and display the respective error message.

And that's it, you've now successfully added your own cart validator.

## Next steps

Review the guide on [adding cart items](add-cart-items) for information on custom line-item payloads.

---

---
url: /docs/v6.5/guides/plugins/plugins/checkout/cart/add-cart-validator.md
---

# Add Cart Validator

## Overview

The cart in Shopware is constantly being validated by so called "validators". This way we can check for an invalid cart, e.g. for invalid line items (label missing) or an invalid shipping address.

This guide will cover the subject on how to add your own custom cart validator.

## Prerequisites

For this guide, you will need a working plugin, which you learn to create [here](../../plugin-base-guide). Also, you will have to know the [Dependency Injection container](../../plugin-fundamentals/dependency-injection), since that's going to be used in order to register your custom validator.

## Adding a custom cart validator

We'll create several things throughout this guide, in that order:

* The validator itself
* A new exception being thrown by the validator if needed
* Snippets to print a proper error message

### The validator

The validator being created in this example is assuming you've got custom payload data in your line items to validate against. This is just an example and will always result in an error, since the data requested doesn't exist by default, until you add them.

A validator should be placed in the proper domain. That means, that an Address validator should be in a directory `<plugin root>/src/Core/Checkout/Cart/Address`. Since the validator in the following example will be called `CustomCartValidator`, its directory will be `<plugin root>/src/Core/Checkout/Cart/Custom`.

Your validator has to implement the interface `Shopware\Core\Checkout\Cart\CartValidatorInterface`. This forces you to also implement a `validate` method.

But let's have a look at the example validator first:

```php
// <plugin root>/src/Core/Checkout/Cart/Custom/CustomCartValidator.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout\Cart\Custom;

use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Cart\CartValidatorInterface;
use Shopware\Core\Checkout\Cart\Error\ErrorCollection;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Swag\BasicExample\Core\Checkout\Cart\Custom\Error\CustomCartBlockedError;

class CustomCartValidator implements CartValidatorInterface
{
    public function validate(Cart $cart, ErrorCollection $errorCollection, SalesChannelContext $salesChannelContext): void
    {
        foreach ($cart->getLineItems()->getFlat() as $lineItem) {
            if (!array_key_exists('customPayload', $lineItem->getPayload()) || $lineItem->getPayload()['customPayload'] !== 'example') {
                $errorCollection->add(new CustomCartBlockedError($lineItem->getId()));

                return;
            }
        }
    }
}
```

As already said, a cart validator has to implement the `CartValidatorInterface` and therefore implement a `validate` method. This method has access to some important parts of the checkout, such as the cart and the current sales channel context. Also you have access to the error collection, which may or may not contain errors from other earlier validators.

In this example we're dealing with the line items and are validating them, so we're iterating over each line item. This example assumes that your line items got a custom payload, called `customPayload`, and it expects a value in there.

If the condition doesn't match and the line item seems to be invalid, you'll have to add a new error to the error collection. You can't just use any exception here, but a class which has to extend from `Shopware\Core\Checkout\Cart\Error\Error`. Most likely you want to create your own error class here, which will be done in the next step.

Important to note is the `return` statement afterwards. If you wouldn't return here, it would add an error to the error collection for each invalid line item, resulting in several errors displayed on the checkout or the cart page. E.g. if you had four invalid items in your cart, four separate errors would be shown. This way, only one message is shown, so it depends on what you're validating and what you want to happen.

#### Registering the validator

One more thing to do is to register your new validator to the [dependency injection container](../../plugin-fundamentals/dependency-injection).

Your validator has to be registered using the tag `shopware.cart.validator`:

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Core\Checkout\Cart\Custom\CustomCartValidator">
            <tag name="shopware.cart.validator"/>
        </service>
    </services>
</container>
```

### Adding the custom cart error

The custom cart error class will be called `CustomCartBlockedError` and should be located in a `Error` directory in the same domain as the validator. Since the validator was located in the directory `<plugin root>/src/Core/Checkout/Cart/Custom`, the error class will be located in the directory `<plugin root>/src/Core/Checkout/Cart/Custom/Error`.

It has to extend from the abstract class `Shopware\Core\Checkout\Cart\Error\Error`, which asks you to implement a few methods:

* `getId`: Here you have to return a unique ID, since your error will be saved via this ID in the error collection. In this example,

  we'll just use the line item ID here.

* `getMessageKey`: The snippet key of the message to be displayed. In this example it will be `custom-line-item-blocked`, which is important

  for the next section of this guide, for adding the snippets.

* `getLevel`: The kind of error, available are `notice`, `warning` and `error`. Depending on that decision, the error will be printed in a blue,

  yellow or red box respectively. This example will use the error here.

* `blockOrder`: Return a boolean on whether this exception should block the possibility to actually finish the checkout.

  In this case it will be `true`, hence the error level defined earlier. It wouldn't make sense to block the checkout, but only display a notice.

* `blockResubmit`: Optional, return a boolean on whether this exception block the user from trying to finish the checkout again.

  If you want to use it, add the method `blockResubmit(): bool` to your custom error. If you don't, it is `true` by default.

* `getParameters`: You can add custom payload here. Technically any plugin or code could read the errors of the cart and act accordingly.

  If you need extra payload to your error class, this is the place to go.

So now let's have a look at the example error class:

```php
// <plugin root>/src/Core/Checkout/Cart/Custom/Error/CustomCartBlockedError.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout\Cart\Custom\Error;

use Shopware\Core\Checkout\Cart\Error\Error;

class CustomCartBlockedError extends Error
{
    private const KEY = 'custom-line-item-blocked';

    private string $lineItemId;

    public function __construct(string $lineItemId)
    {
        $this->lineItemId = $lineItemId;
        parent::__construct();
    }

    public function getId(): string
    {
        return $this->lineItemId;
    }

    public function getMessageKey(): string
    {
        return self::KEY;
    }

    public function getLevel(): int
    {
//        return self::LEVEL_NOTICE;
//        return self::LEVEL_WARNING;
        return self::LEVEL_ERROR;
    }

    public function blockOrder(): bool
    {
        return true;
    }

    public function getParameters(): array
    {
        return [ 'lineItemId' => $this->lineItemId ];
    }
}
```

The constructor was overridden so we can ask for the line item ID and save it in a property. Since we already used this class in the validator, we're basically done with that part here.

Only the snippets are missing.

### Adding the snippet

First of all you should know our guide about [adding storefront snippets](../../storefront/add-translations), since that won't be explained in detail here.

You've defined the error key to be `custom-line-item-blocked` in your custom error class `CustomCartBlockedError`. Once your validator finds an invalid line item in your cart, Shopware is going to search for a respective snippet. In the cart, Shopware will be looking for the following snippet key: `checkout.custom-line-item-blocked`. Meanwhile it will be looking for a key `error.custom-line-item-blocked` in the checkout steps. This way you could technically define two different messages for the cart and the following checkout steps.

Now let's have a look at an example snippet file:

```js
// <plugin root>/src/Resources/snippet/en\_GB/example.en-GB.json
{
    "checkout": {
        "custom-line-item-blocked": "Example error message for the cart"
    },
    "error": {
        "custom-line-item-blocked": "Example error message for the checkout"
    }
}
```

This way Shopware will find the new snippets in your plugin and display the respective error message.

And that's it, you've now successfully added your own cart validator.

## Next steps

In the examples mentioned above, we're asking for custom line item payloads. This subject is covered in our guide about [adding cart items](add-cart-items), so you might want to have a look at that.

---

---
url: /docs/v6.6/guides/plugins/plugins/checkout/cart/add-cart-validator.md
---

# Add Cart Validator

## Overview

The cart in Shopware is constantly being validated by so called "validators". This way we can check for an invalid cart, e.g. for invalid line items (label missing) or an invalid shipping address.

This guide will cover the subject on how to add your own custom cart validator.

## Prerequisites

For this guide, you will need a working plugin, which you learn to create [here](../../plugin-base-guide). Also, you will have to know the [Dependency Injection container](../../plugin-fundamentals/dependency-injection), since that's going to be used in order to register your custom validator.

## Adding a custom cart validator

We'll create several things throughout this guide, in that order:

* The validator itself
* A new exception being thrown by the validator if needed
* Snippets to print a proper error message

### The validator

The validator being created in this example is assuming you've got custom payload data in your line items to validate against. This is just an example and will always result in an error, since the data requested doesn't exist by default, until you add them.

A validator should be placed in the proper domain. That means, that an Address validator should be in a directory `<plugin root>/src/Core/Checkout/Cart/Address`. Since the validator in the following example will be called `CustomCartValidator`, its directory will be `<plugin root>/src/Core/Checkout/Cart/Custom`.

Your validator has to implement the interface `Shopware\Core\Checkout\Cart\CartValidatorInterface`. This forces you to also implement a `validate` method.

But let's have a look at the example validator first:

```php
// <plugin root>/src/Core/Checkout/Cart/Custom/CustomCartValidator.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout\Cart\Custom;

use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Cart\CartValidatorInterface;
use Shopware\Core\Checkout\Cart\Error\ErrorCollection;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Swag\BasicExample\Core\Checkout\Cart\Custom\Error\CustomCartBlockedError;

class CustomCartValidator implements CartValidatorInterface
{
    public function validate(Cart $cart, ErrorCollection $errorCollection, SalesChannelContext $salesChannelContext): void
    {
        foreach ($cart->getLineItems()->getFlat() as $lineItem) {
            if (!array_key_exists('customPayload', $lineItem->getPayload()) || $lineItem->getPayload()['customPayload'] !== 'example') {
                $errorCollection->add(new CustomCartBlockedError($lineItem->getId()));

                return;
            }
        }
    }
}
```

As already said, a cart validator has to implement the `CartValidatorInterface` and therefore implement a `validate` method. This method has access to some important parts of the checkout, such as the cart and the current sales channel context. Also you have access to the error collection, which may or may not contain errors from other earlier validators.

In this example we're dealing with the line items and are validating them, so we're iterating over each line item. This example assumes that your line items got a custom payload, called `customPayload`, and it expects a value in there.

If the condition doesn't match and the line item seems to be invalid, you'll have to add a new error to the error collection. You can't just use any exception here, but a class which has to extend from `Shopware\Core\Checkout\Cart\Error\Error`. Most likely you want to create your own error class here, which will be done in the next step.

Important to note is the `return` statement afterwards. If you wouldn't return here, it would add an error to the error collection for each invalid line item, resulting in several errors displayed on the checkout or the cart page. E.g. if you had four invalid items in your cart, four separate errors would be shown. This way, only one message is shown, so it depends on what you're validating and what you want to happen.

#### Registering the validator

One more thing to do is to register your new validator to the [dependency injection container](../../plugin-fundamentals/dependency-injection).

Your validator has to be registered using the tag `shopware.cart.validator`:

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Core\Checkout\Cart\Custom\CustomCartValidator">
            <tag name="shopware.cart.validator"/>
        </service>
    </services>
</container>
```

### Adding the custom cart error

The custom cart error class will be called `CustomCartBlockedError` and should be located in a `Error` directory in the same domain as the validator. Since the validator was located in the directory `<plugin root>/src/Core/Checkout/Cart/Custom`, the error class will be located in the directory `<plugin root>/src/Core/Checkout/Cart/Custom/Error`.

It has to extend from the abstract class `Shopware\Core\Checkout\Cart\Error\Error`, which asks you to implement a few methods:

* `getId`: Here you have to return a unique ID, since your error will be saved via this ID in the error collection. In this example,

  we'll just use the line item ID here.

* `getMessageKey`: The snippet key of the message to be displayed. In this example it will be `custom-line-item-blocked`, which is important

  for the next section of this guide, for adding the snippets.

* `getLevel`: The kind of error, available are `notice`, `warning` and `error`. Depending on that decision, the error will be printed in a blue,

  yellow or red box respectively. This example will use the error here.

* `blockOrder`: Return a boolean on whether this exception should block the possibility to actually finish the checkout.

  In this case it will be `true`, hence the error level defined earlier. It wouldn't make sense to block the checkout, but only display a notice.

* `blockResubmit`: Optional, return a boolean on whether this exception block the user from trying to finish the checkout again.

  If you want to use it, add the method `blockResubmit(): bool` to your custom error. If you don't, it is `true` by default.

* `getParameters`: You can add custom payload here. Technically any plugin or code could read the errors of the cart and act accordingly.

  If you need extra payload to your error class, this is the place to go.

So now let's have a look at the example error class:

```php
// <plugin root>/src/Core/Checkout/Cart/Custom/Error/CustomCartBlockedError.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout\Cart\Custom\Error;

use Shopware\Core\Checkout\Cart\Error\Error;

class CustomCartBlockedError extends Error
{
    private const KEY = 'custom-line-item-blocked';

    private string $lineItemId;

    public function __construct(string $lineItemId)
    {
        $this->lineItemId = $lineItemId;
        parent::__construct();
    }

    public function getId(): string
    {
        return $this->lineItemId;
    }

    public function getMessageKey(): string
    {
        return self::KEY;
    }

    public function getLevel(): int
    {
//        return self::LEVEL_NOTICE;
//        return self::LEVEL_WARNING;
        return self::LEVEL_ERROR;
    }

    public function blockOrder(): bool
    {
        return true;
    }

    public function getParameters(): array
    {
        return [ 'lineItemId' => $this->lineItemId ];
    }
}
```

The constructor was overridden so we can ask for the line item ID and save it in a property. Since we already used this class in the validator, we're basically done with that part here.

Only the snippets are missing.

### Adding the snippet

First of all you should know our guide about [adding storefront snippets](../../storefront/add-translations), since that won't be explained in detail here.

You've defined the error key to be `custom-line-item-blocked` in your custom error class `CustomCartBlockedError`. Once your validator finds an invalid line item in your cart, Shopware is going to search for a respective snippet. In the cart, Shopware will be looking for the following snippet key: `checkout.custom-line-item-blocked`. Meanwhile it will be looking for a key `error.custom-line-item-blocked` in the checkout steps. This way you could technically define two different messages for the cart and the following checkout steps.

Now let's have a look at an example snippet file:

```javascript
// <plugin root>/src/Resources/snippet/en\_GB/example.en-GB.json
{
    "checkout": {
        "custom-line-item-blocked": "Example error message for the cart"
    },
    "error": {
        "custom-line-item-blocked": "Example error message for the checkout"
    }
}
```

This way Shopware will find the new snippets in your plugin and display the respective error message.

And that's it, you've now successfully added your own cart validator.

## Next steps

In the examples mentioned above, we're asking for custom line item payloads. This subject is covered in our guide about [adding cart items](add-cart-items), so you might want to have a look at that.

---

---
url: /docs/v6.5/guides/plugins/plugins/content/cms/add-cms-block.md
---

# Add CMS Block

## Overview

This guide will teach you how to create your very own CMS block with your plugin.

## Prerequisites

This plugin is built upon our plugin from the [Plugin base guide](../../plugin-base-guide), but the examples mentioned here are applicable to every valid Shopware 6 plugin. Also, you should know how to handle the "Shopping Experiences" module in the Administration first. Furthermore, you definitely need to know how to create a custom component in the Administration, which is covered here [Creating a component](../../administration/add-custom-component).

## Custom block in the Administration

Let's get started with adding your first custom block. By default, Shopware 6 comes with several blocks, such as a block called `image_text`. It renders an image element on the left side and a simple text element on the right side. In this guide, you're going to create a new block to swap those two elements, so the text is on the left side and the image on the right side.

All blocks can be found in the directory [/src/Administration/Resources/app/administration/src/module/sw-cms/blocks](https://github.com/shopware/shopware/tree/v6.3.4.1/src/Administration/Resources/app/administration/src/module/sw-cms/blocks). In there, they are divided into the categories `commerce`, `form`, `image`, `sidebar`, `text-image`, `text` and `video`.

`commerce` : Blocks using a special template can be found here, e.g. a product slider block.

`form` : A single block displaying a form, mainly the `contact` or the `newsletter` form.

`image` : Only image elements are used by these blocks.

`sidebar` : Blocks for the sidebar, such as the listing filters or the category navigation.

`text-image` : Blocks, that are making use of both, text and images, belong here.

`text` : Blocks only using text elements are located here.

`video` : Our blocks for youtube and vimeo videos reside here.

### Injecting into the Administration

The main entry point to customize the Administration via plugin is the `main.js` file. It has to be placed into a `<plugin root>/src/Resources/app/administration/src` directory in order to be automatically found by Shopware 6.

Create this `main.js` file for now, it will be used later.

### Registering a new block

Your plugin's structure should always match the core's structure. When thinking about creating a new block, you should recreate the directory structure of core blocks in your plugin. The block, which you're going to create, consists of an `image` and a `text` element, so it belongs to the category `text-image`. Thus, create the directory `<plugin root>/src/Resources/app/administration/src/module/sw-cms/blocks/text-image`.

In there, you have to create a new directory for each block you want to create, the directory's name representing the block's name. For this example, the name `my-image-text-reversed` is going to be used, so create this directory in there.

Now create a new file `index.js` inside the `my-image-text-reversed` directory, since it will be automatically loaded when importing this block in your `main.js`. Speaking of that, right after having created the `index.js` file, you can actually import your new block directory in the `main.js` file already:

```javascript
// <plugin root>/src/Resources/app/administration/src/main.js
import './module/sw-cms/blocks/text-image/my-image-text-reversed';
```

Back to your `index.js`, which is still empty. In order to register a new block, you have to call the `registerCmsBlock` method of the [cmsService](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Administration/Resources/app/administration/src/module/sw-cms/service/cms.service.js). Since it's available in the Dependency Injection Container, you can fetch it from there.

First of all, access our `Application` wrapper, which will grant you access to the DI container. This `Application` wrapper has access to the DI container, so go ahead and fetch the `cmsService` from it and call the mentioned `registerCmsBlock` method.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/blocks/text-image/my-image-text-reversed/index.js
Shopware.Service('cmsService').registerCmsBlock();
```

#### The configuration object

The method `registerCmsBlock` takes a configuration object, containing the following necessary data:

`name` : The technical name of your block. Will be used for the template and component loading later on.

`label` : A name to be shown for your block in the User Interface.

`category` : The category this block belongs to.

`component` : The Vue component to be used when rendering your actual block in the Administration sidebar.

`previewComponent` : The Vue component to be used in the "list of available blocks". Just shows a tiny preview of what your block would look like if it was used.

`defaultConfig` : A default configuration to be applied to this block. Must be an object containing those default values.

`slots` : Key-value pair to configure which element to be shown in which slot. Will be explained in the next few steps when creating a template for this block.

Go ahead and create this configuration object yourself. Here's what it should look like after having set all of those options:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/blocks/text-image/my-image-text-reversed/index.js
Shopware.Service('cmsService').registerCmsBlock({
    name: 'my-image-text-reversed',
    category: 'text-image',
    label: 'My Image Text Block!',
    component: 'sw-cms-block-my-image-text-reversed',
    previewComponent: 'sw-cms-preview-my-image-text-reversed',
    defaultConfig: {
        marginBottom: '20px',
        marginTop: '20px',
        marginLeft: '20px',
        marginRight: '20px',
        sizingMode: 'boxed'
    },
    slots: {
        left: 'text',
        right: 'image'
    }
});
```

The `component` and `previewComponent` do not exist yet, but they are created later in this guide. The `defaultConfig` just gets some minor margins and the sizing mode 'boxed', which will result in a CSS class [is--boxed](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Administration/Resources/app/administration/src/module/sw-cms/component/sw-cms-block/sw-cms-block.scss) being applied to that block later. The slots are defined by an object, where the key represents the slot's name and the value being the technical name of the element to be used in this slot. This will be easier to understand when having a look at the respective template in a few minutes. Also you might want to have a look at the [Vue documentation regarding slots](https://vuejs.org/v2/guide/components-slots.html).

### Rendering the block

You've set the `name` of the component to be used when rendering your block to be 'sw-cms-block-my-image-text-reversed'. This component does not exist yet, so let's create this one real quick. As already mentioned, creating a component is not explained by this guide in detail, so you might want to head over to our guide about [Creating a component](../../administration/add-custom-component) first.

First of all, create a new directory `component` in your block's directory. In there, create a new `index.js` file and register your custom component `sw-cms-block-my-image-text-reversed`.

**Keep in mind: The component name consists of `sw-cms-block-` and the `name` property mentioned in your `index.js`, while registering your cms block component via `registerCmsBlock()`!**

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/blocks/text-image/my-image-text-reversed/component/index.js
import template from './sw-cms-block-my-image-text-reversed.html.twig';
import './sw-cms-block-my-image-text-reversed.scss';

Shopware.Component.register('sw-cms-block-my-image-text-reversed', {
    template
});
```

Just like most components, it has a custom template and also some styles. Focus on the template first, create a new file `sw-cms-block-my-image-text-reversed.html.twig`.

This template now has to define the basic structure of your custom block. In this simple case, you only need a parent container and two sub-elements, whatever those are. That's also were the slots come into play: You've used two slots in your block's configuration, `left` and `right`. Make sure to create those slots in the template as well now.

```twig
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/blocks/text-image/my-image-text-reversed/component/sw-cms-block-my-image-text-reversed.html.twig
{% block sw_cms_block_my_image_text_reversed %}
    <div class="sw-cms-block-my-image-text-reversed">
        <slot name="left">{% block sw_cms_block_my_image_text_reversed_slot_left %}{% endblock %}</slot>
        <slot name="right">{% block sw_cms_block_my_image_text_reversed_slot_right %}{% endblock %}</slot>
    </div>
{% endblock %}
```

You've got a parent `div` containing the two required [slots](https://vuejs.org/v2/guide/components-slots.html). If you were to rename the first slot `left` to something else, you'd have to adjust this in your block's configuration as well.

Those slots would be rendered from top to bottom now, instead of from left to right. That's why your block comes with a custom `.scss` file, create it now by adding the file `sw-cms-block-my-image-text-reversed.scss` to your `component` directory.

In there, use a grid to display your elements next to each other. You've set a CSS class for your block, which is the same as its name.

```css
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/blocks/text-image/my-image-text-reversed/component/sw-cms-block-my-image-text-reversed.scss
.sw-cms-block-my-image-text-reversed {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    grid-gap: 40px;
}
```

That's it for this component! Make sure to import your `component` directory in your `index.js` file, so your new component actually gets loaded.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/blocks/text-image/my-image-text-reversed/index.js
import './component'; // <- Right here!

Shopware.Service('cmsService').registerCmsBlock({
    ...
});
```

Your block can now be rendered in the designer. Let's continue with the preview component.

### Block preview

You've also set a property `previewComponent` containing the value `sw-cms-preview-my-image-text-reversed`. Time to create this component as well. For this purpose, stick to the core structure again and create a new directory `preview`. In there, again, create an `index.js` file, register your component by its name and load a template and a `.scss` file.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/blocks/text-image/my-image-text-reversed/preview/index.js
import template from './sw-cms-preview-my-image-text-reversed.html.twig';
import './sw-cms-preview-my-image-text-reversed.scss';

Shopware.Component.register('sw-cms-preview-my-image-text-reversed', {
    template
});
```

The preview element doesn't have to deal with mobile viewports or anything alike, it's just a simplified preview of your block. Thus, create a template containing a text and an image and use the styles to place them next to each other. Create a `sw-cms-preview-my-image-text-reversed.html.twig` file in your `preview` directory with the following content.

```twig
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/blocks/text-image/my-image-text-reversed/preview/sw-cms-preview-my-image-text-reversed.html.twig
{% block sw_cms_block_my_image_text_reversed_preview %}
    <div class="sw-cms-preview-my-image-text-reversed">
        <div>
            <h2>Lorem ipsum dolor</h2>
            <p>Lorem ipsum dolor sit amet, consetetur sadipscing elitr.</p>
        </div>
        <img :src="'/administration/static/img/cms/preview_mountain_small.jpg' | asset">
    </div>
{% endblock %}
```

Just a div containing some text and an example image next to that. For the styles, you can simply use the grid property of CSS again. Since you don't have to care about mobile viewports, this is even easier this time.

Now create the styles file `sw-cms-preview-my-image-text-reversed.scss` with the following styles:

```css
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/blocks/text-image/my-image-text-reversed/preview/sw-cms-preview-my-image-text-reversed.scss
.sw-cms-preview-my-image-text-reversed {
    display: grid;
    grid-template-columns: 1fr 1fr;
    grid-column-gap: 20px;
    padding: 15px;
}
```

A two-column layout, some padding and spacing here and there, done.

Now, import this component in your block's `index.js` as well. This is, what your final block's `index.js` file should look like now:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/blocks/text-image/my-image-text-reversed/index.js
import './component';
import './preview';

Shopware.Service('cmsService').registerCmsBlock({
    name: 'my-image-text-reversed',
    category: 'text-image',
    label: 'My Image Text Block!',
    component: 'sw-cms-block-my-image-text-reversed',
    previewComponent: 'sw-cms-preview-my-image-text-reversed',
    defaultConfig: {
        marginBottom: '20px',
        marginTop: '20px',
        marginLeft: '20px',
        marginRight: '20px',
        sizingMode: 'boxed'
    },
    slots: {
        left: 'text',
        right: 'image'
    }
});
```

In order to test your changes now, you should rebuild your Administration. This can be done with the following command:

```bash
./bin/build-administration.sh
```

```bash
composer run build:js:admin
```

You should now be able to use your new block in the "Shopping Experiences" module.

## Storefront representation

While your new block is fully functional in the Administration already, you've never defined a template for it for the Storefront.

A block's Storefront representation is always expected in the directory [platform/src/Storefront/Resources/views/storefront/block](https://github.com/shopware/shopware/tree/v6.3.4.1/src/Storefront/Resources/views/storefront/block). In there, a twig template named after your block is expected.

So go ahead and re-create that structure in your plugin: `<plugin root>/src/Resources/views/storefront/block/`

Create a new twig template named after your block. The filename convention for this is :

* Starts with the prefix `cms-block-`
* Followed by the technical name of the block `my-image-text-reversed`
* Ends with the extension `.html.twig`

Example : `cms-block-my-image-text-reversed.html.twig`.

Since the [original 'image\_text' file](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Storefront/Resources/views/storefront/block/cms-block-image-text.html.twig) is already perfectly fine, you can go ahead and extend from it in your storefront template.

```twig
// <plugin root>/src/Resources/views/storefront/block/cms-block-my-image-text-reversed.html.twig
{% sw_extends '@Storefront/storefront/block/cms-block-image-text.html.twig' %}
```

And that's it for the Storefront as well in this example! Make sure to have a look at the other original templates to get and understand how the templating for blocks works.

## Next steps

Now you've got your very own CMS block running, what about a custom CMS element? Head over to our guide, which will explain exactly that: [Creating a custom CMS element](add-cms-element)

---

---
url: /docs/v6.6/guides/plugins/plugins/content/cms/add-cms-block.md
---

# Add CMS Block

## Overview

This guide will teach you how to create your very own CMS block with your plugin.

## Prerequisites

This plugin is built upon our plugin from the [Plugin base guide](../../plugin-base-guide), but the examples mentioned here are applicable to every valid Shopware 6 plugin. Also, you should know how to handle the "Shopping Experiences" module in the Administration first. Furthermore, you definitely need to know how to create a custom component in the Administration, which is covered here [Creating a component](../../administration/add-custom-component).

## Custom block in the Administration

Let's get started with adding your first custom block. By default, Shopware 6 comes with several blocks, such as a block called `image_text`. It renders an image element on the left side and a simple text element on the right side. In this guide, you're going to create a new block to swap those two elements, so the text is on the left side and the image on the right side.

All blocks can be found in the directory [/src/Administration/Resources/app/administration/src/module/sw-cms/blocks](https://github.com/shopware/shopware/tree/v6.3.4.1/src/Administration/Resources/app/administration/src/module/sw-cms/blocks). In there, they are divided into the categories `commerce`, `form`, `image`, `sidebar`, `text-image`, `text` and `video`.

`commerce` : Blocks using a special template can be found here, e.g. a product slider block.

`form` : A single block displaying a form, mainly the `contact` or the `newsletter` form.

`image` : Only image elements are used by these blocks.

`sidebar` : Blocks for the sidebar, such as the listing filters or the category navigation.

`text-image` : Blocks, that are making use of both, text and images, belong here.

`text` : Blocks only using text elements are located here.

`video` : Our blocks for youtube and vimeo videos reside here.

### Injecting into the Administration

The main entry point to customize the Administration via plugin is the `main.js` file. It has to be placed into a `<plugin root>/src/Resources/app/administration/src` directory in order to be automatically found by Shopware 6.

Create this `main.js` file for now, it will be used later.

### Registering a new block

Your plugin's structure should always match the core's structure. When thinking about creating a new block, you should recreate the directory structure of core blocks in your plugin. The block, which you're going to create, consists of an `image` and a `text` element, so it belongs to the category `text-image`. Thus, create the directory `<plugin root>/src/Resources/app/administration/src/module/sw-cms/blocks/text-image`.

In there, you have to create a new directory for each block you want to create, the directory's name representing the block's name. For this example, the name `my-image-text-reversed` is going to be used, so create this directory in there.

Now create a new file `index.js` inside the `my-image-text-reversed` directory, since it will be automatically loaded when importing this block in your `main.js`. Speaking of that, right after having created the `index.js` file, you can actually import your new block directory in the `main.js` file already:

```javascript
// <plugin root>/src/Resources/app/administration/src/main.js
import './module/sw-cms/blocks/text-image/my-image-text-reversed';
```

Back to your `index.js`, which is still empty. In order to register a new block, you have to call the `registerCmsBlock` method of the [cmsService](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Administration/Resources/app/administration/src/module/sw-cms/service/cms.service.js). Since it's available in the Dependency Injection Container, you can fetch it from there.

First of all, access our `Application` wrapper, which will grant you access to the DI container. This `Application` wrapper has access to the DI container, so go ahead and fetch the `cmsService` from it and call the mentioned `registerCmsBlock` method.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/blocks/text-image/my-image-text-reversed/index.js
Shopware.Service('cmsService').registerCmsBlock();
```

#### The configuration object

The method `registerCmsBlock` takes a configuration object, containing the following necessary data:

`name` : The technical name of your block. Will be used for the template and component loading later on.

`label` : A name to be shown for your block in the User Interface.

`category` : The category this block belongs to.

`component` : The Vue component to be used when rendering your actual block in the Administration sidebar.

`previewComponent` : The Vue component to be used in the "list of available blocks". Just shows a tiny preview of what your block would look like if it was used.

`defaultConfig` : A default configuration to be applied to this block. Must be an object containing those default values.

`slots` : Key-value pair to configure which element to be shown in which slot. Will be explained in the next few steps when creating a template for this block.

Go ahead and create this configuration object yourself. Here's what it should look like after having set all of those options:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/blocks/text-image/my-image-text-reversed/index.js
Shopware.Service('cmsService').registerCmsBlock({
    name: 'my-image-text-reversed',
    category: 'text-image',
    label: 'My Image Text Block!',
    component: 'sw-cms-block-my-image-text-reversed',
    previewComponent: 'sw-cms-preview-my-image-text-reversed',
    defaultConfig: {
        marginBottom: '20px',
        marginTop: '20px',
        marginLeft: '20px',
        marginRight: '20px',
        sizingMode: 'boxed'
    },
    slots: {
        left: 'text',
        right: 'image'
    }
});
```

The `component` and `previewComponent` do not exist yet, but they are created later in this guide. The `defaultConfig` just gets some minor margins and the sizing mode 'boxed', which will result in a CSS class [is--boxed](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Administration/Resources/app/administration/src/module/sw-cms/component/sw-cms-block/sw-cms-block.scss) being applied to that block later. The slots are defined by an object, where the key represents the slot's name and the value being the technical name of the element to be used in this slot. This will be easier to understand when having a look at the respective template in a few minutes. Also you might want to have a look at the [Vue documentation regarding slots](https://vuejs.org/v2/guide/components-slots.html).

### Rendering the block

You've set the `name` of the component to be used when rendering your block to be 'sw-cms-block-my-image-text-reversed'. This component does not exist yet, so let's create this one real quick. As already mentioned, creating a component is not explained by this guide in detail, so you might want to head over to our guide about [Creating a component](../../administration/add-custom-component) first.

First of all, create a new directory `component` in your block's directory. In there, create a new `index.js` file and register your custom component `sw-cms-block-my-image-text-reversed`.

**Keep in mind: The component name consists of `sw-cms-block-` and the `name` property mentioned in your `index.js`, while registering your cms block component via `registerCmsBlock()`!**

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/blocks/text-image/my-image-text-reversed/component/index.js
import template from './sw-cms-block-my-image-text-reversed.html.twig';
import './sw-cms-block-my-image-text-reversed.scss';

Shopware.Component.register('sw-cms-block-my-image-text-reversed', {
    template
});
```

Just like most components, it has a custom template and also some styles. Focus on the template first, create a new file `sw-cms-block-my-image-text-reversed.html.twig`.

This template now has to define the basic structure of your custom block. In this simple case, you only need a parent container and two sub-elements, whatever those are. That's also were the slots come into play: You've used two slots in your block's configuration, `left` and `right`. Make sure to create those slots in the template as well now.

```twig
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/blocks/text-image/my-image-text-reversed/component/sw-cms-block-my-image-text-reversed.html.twig
{% block sw_cms_block_my_image_text_reversed %}
    <div class="sw-cms-block-my-image-text-reversed">
        <slot name="left">{% block sw_cms_block_my_image_text_reversed_slot_left %}{% endblock %}</slot>
        <slot name="right">{% block sw_cms_block_my_image_text_reversed_slot_right %}{% endblock %}</slot>
    </div>
{% endblock %}
```

You've got a parent `div` containing the two required [slots](https://vuejs.org/v2/guide/components-slots.html). If you were to rename the first slot `left` to something else, you'd have to adjust this in your block's configuration as well.

Those slots would be rendered from top to bottom now, instead of from left to right. That's why your block comes with a custom `.scss` file, create it now by adding the file `sw-cms-block-my-image-text-reversed.scss` to your `component` directory.

In there, use a grid to display your elements next to each other. You've set a CSS class for your block, which is the same as its name.

```css
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/blocks/text-image/my-image-text-reversed/component/sw-cms-block-my-image-text-reversed.scss
.sw-cms-block-my-image-text-reversed {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(300px, 1fr));
    grid-gap: 40px;
}
```

That's it for this component! Make sure to import your `component` directory in your `index.js` file, so your new component actually gets loaded.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/blocks/text-image/my-image-text-reversed/index.js
import './component'; // <- Right here!

Shopware.Service('cmsService').registerCmsBlock({
    ...
});
```

Your block can now be rendered in the designer. Let's continue with the preview component.

### Block preview

You've also set a property `previewComponent` containing the value `sw-cms-preview-my-image-text-reversed`. Time to create this component as well. For this purpose, stick to the core structure again and create a new directory `preview`. In there, again, create an `index.js` file, register your component by its name and load a template and a `.scss` file.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/blocks/text-image/my-image-text-reversed/preview/index.js
import template from './sw-cms-preview-my-image-text-reversed.html.twig';
import './sw-cms-preview-my-image-text-reversed.scss';

Shopware.Component.register('sw-cms-preview-my-image-text-reversed', {
    template
});
```

The preview element doesn't have to deal with mobile viewports or anything alike, it's just a simplified preview of your block. Thus, create a template containing a text and an image and use the styles to place them next to each other. Create a `sw-cms-preview-my-image-text-reversed.html.twig` file in your `preview` directory with the following content.

```twig
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/blocks/text-image/my-image-text-reversed/preview/sw-cms-preview-my-image-text-reversed.html.twig
{% block sw_cms_block_my_image_text_reversed_preview %}
    <div class="sw-cms-preview-my-image-text-reversed">
        <div>
            <h2>Lorem ipsum dolor</h2>
            <p>Lorem ipsum dolor sit amet, consetetur sadipscing elitr.</p>
        </div>
        <img :src="assetFilter('/administration/static/img/cms/preview_mountain_small.jpg')">
    </div>
{% endblock %}
```

Also, you need to create a computed component to access the asset filter in your template.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/blocks/text-image/my-image-text-reversed/preview/index.js
computed: {
    assetFilter() {
        return Shopware.Filter.getByName('asset');
    },
}
```

Just a div containing some text and an example image next to that. For the styles, you can simply use the grid property of CSS again. Since you don't have to care about mobile viewports, this is even easier this time.

Now create the styles file `sw-cms-preview-my-image-text-reversed.scss` with the following styles:

```css
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/blocks/text-image/my-image-text-reversed/preview/sw-cms-preview-my-image-text-reversed.scss
.sw-cms-preview-my-image-text-reversed {
    display: grid;
    grid-template-columns: 1fr 1fr;
    grid-column-gap: 20px;
    padding: 15px;
}
```

A two-column layout, some padding and spacing here and there, done.

Now, import this component in your block's `index.js` as well. This is, what your final block's `index.js` file should look like now:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/blocks/text-image/my-image-text-reversed/index.js
import './component';
import './preview';

Shopware.Service('cmsService').registerCmsBlock({
    name: 'my-image-text-reversed',
    category: 'text-image',
    label: 'My Image Text Block!',
    component: 'sw-cms-block-my-image-text-reversed',
    previewComponent: 'sw-cms-preview-my-image-text-reversed',
    defaultConfig: {
        marginBottom: '20px',
        marginTop: '20px',
        marginLeft: '20px',
        marginRight: '20px',
        sizingMode: 'boxed'
    },
    slots: {
        left: 'text',
        right: 'image'
    }
});
```

In order to test your changes now, you should rebuild your Administration. This can be done with the following command:

```bash
./bin/build-administration.sh
```

```bash
composer run build:js:admin
```

You should now be able to use your new block in the "Shopping Experiences" module.

## Storefront representation

While your new block is fully functional in the Administration already, you've never defined a template for it for the Storefront.

A block's Storefront representation is always expected in the directory [platform/src/Storefront/Resources/views/storefront/block](https://github.com/shopware/shopware/tree/v6.3.4.1/src/Storefront/Resources/views/storefront/block). In there, a twig template named after your block is expected.

So go ahead and re-create that structure in your plugin: `<plugin root>/src/Resources/views/storefront/block/`

Create a new twig template named after your block. The filename convention for this is :

* Starts with the prefix `cms-block-`
* Followed by the technical name of the block `my-image-text-reversed`
* Ends with the extension `.html.twig`

Example : `cms-block-my-image-text-reversed.html.twig`.

Since the [original 'image\_text' file](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Storefront/Resources/views/storefront/block/cms-block-image-text.html.twig) is already perfectly fine, you can go ahead and extend from it in your storefront template.

```twig
// <plugin root>/src/Resources/views/storefront/block/cms-block-my-image-text-reversed.html.twig
{% sw_extends '@Storefront/storefront/block/cms-block-image-text.html.twig' %}
```

And that's it for the Storefront as well in this example! Make sure to have a look at the other original templates to get and understand how the templating for blocks works.

## Next steps

Now you've got your very own CMS block running, what about a custom CMS element? Head over to our guide, which will explain exactly that: [Creating a custom CMS element](add-cms-element)

---

---
url: /docs/guides/plugins/plugins/content/cms/add-cms-block.md
---

# Add CMS Blocks

## Overview

A CMS block in Shopware is a fundamental structural component of the Shopping Experience (CMS) system. Understanding the hierarchy helps clarify what blocks are.

### CMS Hierarchy

* Page - The top-level container (e.g., category page, shop page, product page)
* Section - Horizontal segments within a page (can be single-column or two-column with sidebar)
* **Block - Units that usually span an entire row with custom layout and styling**
* **Slots - A named container inside a block. Each slot represents a designated area that can hold exactly one CMS element**
* Elements - The actual content primitives (text, image, video, product listing, etc.) placed inside slots

A block represents a reusable layout unit that defines how elements are arranged in slots. For example, Shopware's built-in `image-text` block displays an image on the left and text on the right. Blocks are clustered into categories like Text, Images, Commerce, and Video for organizational purposes in the administration interface.

**Key concept**: Blocks define the structure (layout and slots), while elements provide the actual content. This separation allows the same block to display different types of content in its slots.

> **Learn more**: For a deeper understanding of the CMS architecture, see the [Shopping Experience fundamental guide](../../../../../concepts/commerce/content/shopping-experiences-cms.md).

## Where to Find Blocks

Blocks are located in the Shopping Experience module in the Shopware Administration:

* Navigate to Content → Shopping Experience
* Create a new layout or edit an existing one
* In the layout designer, you'll see a sidebar with available blocks organized by category:
  * Text - Text-only blocks
  * Images - Image-only blocks
  * Text & Images - Combined text and image blocks
  * Commerce - Product sliders, listings, etc.
  * Video - YouTube and Vimeo video blocks
  * Form - Contact and newsletter forms
  * Sidebar - Category navigation and listing filters

Drag and drop blocks from the sidebar into your layout sections.

You can find related block code here:

* Administration: `src/Administration/Resources/app/administration/src/module/sw-cms/blocks/`
* Storefront: `src/Storefront/Resources/views/storefront/block/`
* Core: `\Shopware\Core\Content\Cms\SalesChannel\SalesChannelCmsPageLoader::load`

## How to Create a Block in the Administration

### Directory Structure

We recommend this structure for CMS blocks:

```TEXT
<plugin root>/src/Resources/app/administration/src/
├── main.js
└── module/
    └── sw-cms/
        └── blocks/
            └── text-image/              (category)
                └── image-text-reversed/ (block name)
                    ├── index.js
                    ├── component/
                    │   ├── index.js
                    │   ├── cms-block-image-text-reversed.html.twig
                    │   └── cms-block-image-text-reversed.scss
                    └── preview/
                        ├── index.js
                        ├── cms-block-preview-image-text-reversed.html.twig
                        └── cms-block-preview-image-text-reversed.scss
```

### Step 1: Import Your Block in main.js

```JS
// <plugin root>/src/Resources/app/administration/src/main.js
import './module/sw-cms/blocks/text-image/image-text-reversed';
```

### Step 2: Register the Block

```JS
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/blocks/text-image/image-text-reversed/index.js
import './component';
import './preview';

Shopware.Service('cmsService').registerCmsBlock({
    name: 'image-text-reversed',
    category: 'text-image',
    label: 'cms.blocks.imageTextReversed.label',
    component: 'cms-block-image-text-reversed',
    previewComponent: 'cms-block-preview-image-text-reversed',
    defaultConfig: {
        marginBottom: '20px',
        marginTop: '20px',
        marginLeft: '20px',
        marginRight: '20px',
        sizingMode: 'boxed',
    },
    slots: {
        left: 'text',
        right: 'image',
    },
});
```

| Property         | Description                                                                                   |
|------------------|----------------------------------------------------------------------------------------------|
| `name`           | Technical name of your block                                                                 |
| `category`       | Which category it appears under (`text`, `image`, `text-image`, `commerce`, `form`, `video`, `sidebar`) |
| `label`          | Display name in the UI                                                                       |
| `component`      | Vue component for rendering the block in the designer                                        |
| `previewComponent` | Vue component for the block thumbnail preview                                              |
| `defaultConfig`  | Default styling values                                                                       |
| `slots`          | Defines which element types go in which slots (key = slot name, value = element type)        |

### Step 3: Create the Block Component

It's important to include all slots you defined in the block configuration (Step 2). These are used for configuring elements in the administration interface.

```JS
// image-text-reversed/component/index.js
Shopware.Component.register('cms-block-image-text-reversed', {
    template: `<div style="display: flex; gap: 16px;">
        <slot name="left" />
        <slot name="right" />
    </div>`,
});
```

### Step 4: Create the Preview Component

The preview is shown as a thumbnail when selecting a block from the editor sidebar. You could also display a static image of your final Storefront block here.

```JS
// image-text-reversed/preview/index.js
Shopware.Component.register('cms-block-preview-image-text-reversed', {
    template: `<div style="display: flex; gap: 16px;">
        <h2>Lorem ipsum dolor sit amet</h2>
        <img :src="assetFilter('/administration/administration/static/img/cms/preview_mountain_small.jpg')" />
    </div>`,
    computed: {
        assetFilter() {
            return Shopware.Filter.getByName('asset');
        },
    },
});
```

After this, the block preview should appear in the Shopping Experience block sidebar under the "Text & Images" category and can be added to a layout.

## How to Create a Block in the Storefront

The Storefront template defines how your element appears on the actual storefront. It is expected to be located in the directory `src/Resources/views/storefront/block`. In there, a twig template file has to follow this naming convention:

* **Prefix**: `cms-block-`
* **Technical name**: `image-text-reversed` (The `name` property in Step 2)
* **Extension**: `.html.twig`

The block components are loaded in `src/Storefront/Resources/views/storefront/section/cms-section-block-container.html.twig`. This loader expects the following format for block components: `cms-block-image-text-reversed.html.twig`.

### Basic Template

You can create your own blocks or extend and reuse existing ones. Don't forget to clear the Storefront cache after adding new templates.

```TWIG
{# <plugin root>/src/Resources/views/storefront/block/cms-block-image-text-reversed.html.twig #}
<div class="col-md-6">
    {% set element = block.slots.getSlot('left') %}

    {% sw_include '@Storefront/storefront/element/cms-element-' ~ element.type ~ '.html.twig' with {
        'element': element
     } %}
</div>

<div class="col-md-6">
    {% set element = block.slots.getSlot('right') %}

    {% sw_include '@Storefront/storefront/element/cms-element-' ~ element.type ~ '.html.twig' with {
        'element': element
     } %}
</div>
```

The `block` is automatically passed to the template and contains meta data and configuration values. See the `CmsBlockDefinition.php` for a full overview.

### How to Render Slots

Slots contain elements that need to be rendered. Here are the key methods:

#### 1. Get a Slot by Name

```TWIG
{% set leftSlot = block.slots.getSlot('left') %}
```

#### 2. Render an Element

Use `sw_include` to dynamically include the correct element template:

```TWIG
{% sw_include "@Storefront/storefront/element/cms-element-" ~ leftSlot.type ~ ".html.twig" with {
   'element': leftSlot
} %}
```

This dynamically builds the template path based on the element type. For example:

* If `leftSlot.type` is text, it renders cms-element-text.html.twig
* If `leftSlot.type` is image, it renders cms-element-image.html.twig

#### 3. Loop Through All Slots

```TWIG
{% for slotName, slot in block.slots %}
    {% sw_include "@Storefront/storefront/element/cms-element-" ~ slot.type ~ ".html.twig" with {
        'element': slot
    } %}
{% endfor %}
```

## Next steps

Now you've got your very own CMS block running, what about a custom CMS element? Head over to our guide, which will explain exactly that: [Creating a custom CMS element](add-cms-element.md).

---

---
url: /docs/guides/plugins/apps/administration/add-cms-element-via-admin-sdk.md
---

# Add CMS Element

## Overview

This guide explains how to create a new CMS element using the Meteor Admin SDK. The example plugin is named
`SwagBasicAppCmsElementExample`, following the naming conventions used in other guides.

## Prerequisites

* Familiarity with creating [Plugins](../../plugins/plugin-base-guide.md) or [Apps](../app-base-guide.md)
* Familiarity with [creating custom admin components](../../plugins/administration/module-component-management/add-custom-component.md#creating-a-custom-component)
* Understanding of the [Meteor Admin SDK](meteor-admin-sdk.md)

::: info
This example uses TypeScript, which is recommended but not required to develop Shopware.
:::

## Creating your custom element

Similar to [creating a new custom element via plugin](../../plugins/content/cms/add-cms-element.md), this guide describes how to create a new custom element via an app.
Creating a new element requires the Meteor Admin SDK.

::: info
Apps can also add CMS blocks declaratively via `cms.xml` without the Meteor Admin SDK.
That approach is simpler but limited to reusing existing Shopware elements inside the block's slots.
See [Add custom CMS blocks](../content/cms/add-custom-cms-blocks) for details.
:::

The example demonstrates a scenario where a shop manager can configure a video ID to display a Dailymotion video.

### Target structure

Any file structure works for apps, as everything is loaded via iFrame. Shopware recommends using Vue 3 single-file components (SFCs).

When the app is complete, the file structure will look like this:

```bash
// SwagBasicAppCmsElementExample/src/Resources/app/administration/src
├── base
│   └── mainCommands.ts
├── main.ts
├── viewRenderer.ts
└── views
    └── swag-dailymotion
        ├── swag-dailymotion-config.vue
        ├── swag-dailymotion-element.vue
        └── swag-dailymotion-preview.vue
```

## Initial loading of components

The entry point is the `main.ts` file:

```javascript
import { location } from '@shopware-ag/meteor-admin-sdk';

if (location.is(location.MAIN_HIDDEN)) {
    // Execute the base commands
    import('./base/mainCommands');
} else {
    // Render different views
    import('./viewRenderer');
}
```

Use `if(location.is(location.MAIN_HIDDEN))` to **load the main commands** defined in `mainCommands.ts`.
This branch loads logic only — no templates are rendered into the Administration here.

The `else` case loads the view templates via `viewRenderer.ts`.

### Loading all required templates

Next, create the `viewRenderer.ts` file, which loads the three required Vue SFCs for a CMS element:

* `swag-dailymotion-config.vue`, which will handle the content of the CMS element configuration
* `swag-dailymotion-element.vue`, which represents the actual target element in the CMS
* `swag-dailymotion-preview.vue`, which is responsible for the preview when selecting the CMS element in its selection
  screen

Each file is named after its component and prefixed with `swag-dailymotion` (vendor prefix) to avoid naming conflicts.

The following example shows how component loading via `viewRenderer.ts` is implemented:

```javascript
import { createApp, defineAsyncComponent, h } from 'vue';
import { location } from '@shopware-ag/meteor-admin-sdk';

// watch for height changes
location.startAutoResizer();

const locations = {
    'swag-dailymotion-element': defineAsyncComponent(
        () => import('./views/swag-dailymotion/swag-dailymotion-element.vue'),
    ),
    'swag-dailymotion-config': defineAsyncComponent(
        () => import('./views/swag-dailymotion/swag-dailymotion-config.vue'),
    ),
    'swag-dailymotion-preview': defineAsyncComponent(
        () => import('./views/swag-dailymotion/swag-dailymotion-preview.vue'),
    ),
};

const app = createApp({
    render: () => h(locations[location.get()]),
});

app.mount('#app');
```

The `locations` map connects each Shopware-provided location ID to the corresponding Vue component. `location.get()`
returns the current location ID so the correct component is rendered inside the iFrame.

Location IDs are a core concept of the Meteor Admin SDK — Shopware provides dedicated `locationIds` as injection points
for your templates. For CMS elements, these IDs are **auto-generated** from the element name plus the suffixes
`-element`, `-config`, and `-preview`. They become available once the element is registered (see the next section).

> **Learn more**: See the [Meteor Admin SDK locations reference](/resources/admin-extension-sdk/concepts/locations) for a full overview of the concept.

## Registering the block and element

The Shopware CMS distinguishes between two concepts:

* A **block** is the selectable container that appears in the block picker (organised by categories such as *Text*, *Image*, *Video*, etc.).
  Users add blocks to a section, and each block contains one or more slots.
* An **element** is the content type that lives inside a slot (e.g., a video player, an image, a text).
  Elements can also be swapped inside an existing slot via the element-replacement modal.

The registration method you call determines where your addition is reachable:

| What you call                 | Where it appears                                                                                                                            |
|-------------------------------|---------------------------------------------------------------------------------------------------------------------------------------------|
| `registerCmsElement` only     | Element-replacement modal only (the  icon on an existing slot) |
| `registerCmsBlock` only       | Block picker under the chosen category — but the slot renders nothing until an element is also registered                                   |
| Both                          | Block picker **and** element-replacement modal                                                                                              |

To make your CMS addition fully discoverable and functional, call both.

Go to `mainCommands.ts` and add both registrations:

```javascript
import { cms } from '@shopware-ag/meteor-admin-sdk';

const CMS_ELEMENT_NAME = 'swag-dailymotion';
export const CONSTANTS = {
    CMS_ELEMENT_NAME,
    PUBLISHING_KEY: `${CMS_ELEMENT_NAME}__config-element`,
};

// Makes the block appear in the block picker under the "Video" category
void cms.registerCmsBlock({
    name: CONSTANTS.CMS_ELEMENT_NAME,
    label: 'Dailymotion video',
    category: 'video',
    slots: [{ element: CONSTANTS.CMS_ELEMENT_NAME }],
});

// Registers the element that fills the block's slot
void cms.registerCmsElement({
    name: CONSTANTS.CMS_ELEMENT_NAME,
    label: 'Dailymotion video',
    defaultConfig: {
        dailyUrl: {
            source: 'static',
            value: '',
        },
    },
});
```

The `category` field of `registerCmsBlock` controls which group the block appears in:
`'video'`, `'text'`, `'image'`, `'text-image'`, `'commerce'`, `'sidebar'`, `'form'`, or a custom string (which creates a new category group).
The `slots` array lists the element types each slot of the block accepts.

As a best practice, use a **constant** for the CMS element name and the publishing key.
The publishing key must be the element name followed by the `__config-element` suffix.

## Templates and communication with the Administration

The remaining files are the Vue single-file components inside the `views` folder. Create a folder with the full
component name containing three files as shown below:

```bash
// SwagBasicAppCmsElementExample/src/Resources/app/administration/src
views
└── swag-dailymotion
    ├── swag-dailymotion-config.vue
    ├── swag-dailymotion-element.vue
    └── swag-dailymotion-preview.vue
```

### Element ID

When Shopware renders any of the three CMS iFrames, it automatically appends the ID of the current CMS element instance as an `elementId` query parameter to the iFrame URL:

```http request
https://your-app-server/...?elementId=<uuid>
```

Use this ID together with the publishing key to address the correct element's data in Shopware:

```javascript
const params = new URLSearchParams(window.location.search);
const elementId = params.get('elementId');
const dataId = `${CONSTANTS.PUBLISHING_KEY}__${elementId}`;
```

### The config file

The following section describes each file, starting with `swag-dailymotion-config.vue`:

```html
<template>
  <div>
    <h2>Config!</h2>
    Video-Code: <input v-model="dailyUrl" type="text"><br>
  </div>
</template>

<script setup lang="ts">
import { onBeforeMount, ref, computed } from 'vue';
import { data } from '@shopware-ag/meteor-admin-sdk';
import { CONSTANTS } from '../../base/mainCommands';

const dailyUrlValue = ref('');
const dailyUrlSource = ref('static');

const selectors = ['config.dailyUrl.value', 'config.dailyUrl.source'];

const dataId = computed(() => {
    const params = new URLSearchParams(window.location.search);
    const elementId = params.get('elementId');

    return elementId
        ? `${CONSTANTS.PUBLISHING_KEY}__${elementId}`
        : CONSTANTS.PUBLISHING_KEY;
});

const dailyUrl = computed({
    get(): string {
        return dailyUrlValue.value || '';
    },

    set(value: string): void {
        dailyUrlValue.value = value;

        data.update({
            id: dataId.value,
            data: {
                config: {
                    dailyUrl: {
                        value: dailyUrlValue.value,
                        source: dailyUrlSource.value,
                    },
                },
            },
        });
    },
});

onBeforeMount(async () => {
    const value = await data.get({
        id: dataId.value,
        selectors,
    }) as { 'config.dailyUrl.value': string; 'config.dailyUrl.source': string };

    if (value) {
        dailyUrlValue.value = value['config.dailyUrl.value'];
        dailyUrlSource.value = value['config.dailyUrl.source'];
    }
});
</script>
```

**Key points:**

* `data` is imported from the Meteor Admin SDK and handles all data exchange between the app and Shopware
* `dataId` is derived from the `elementId` query parameter appended by Shopware to the iFrame URL, combined with `CONSTANTS.PUBLISHING_KEY`
* `data.get()` accepts an optional `selectors` array so only the relevant fields are fetched; the result is a flat object keyed by selector path (e.g. `value['config.dailyUrl.value']`)
* `data.update()` sends only the changed config structure back to Shopware — not the entire element
* The current config is fetched via `data.get()` in `onBeforeMount` and linked to the computed property `dailyUrl`; the setter calls `data.update({ id, data })` to persist changes

![The image shows the configuration modal for a dailymotion video CMS element. The modal contains one text input for the Dailymotion video ID, a caption for the input and a title.](../../../../assets/add-cms-element-via-admin-sdk-config.png "Dailymotion config modal")

### The element file

`swag-dailymotion-element.vue` contains the main rendering logic for the CMS element in the Administration:

```html
<template>
  <div class="sw-cms-el-dailymotion">
    <div class="sw-cms-el-dailymotion-iframe-wrapper">
      <iframe
        frameborder="0"
        type="text/html"
        width="100%"
        height="100%"
        :src="dailyUrl"
      />
    </div>
  </div>
</template>

<script setup lang="ts">
import { ref, computed, onBeforeMount } from 'vue';
import { data } from '@shopware-ag/meteor-admin-sdk';
import { CONSTANTS } from '../../base/mainCommands';

const dailyUrlValue = ref('');
const dailyUrlSource = ref('static');

const selectors = ['config.dailyUrl.value', 'config.dailyUrl.source'];

const dailyUrl = computed(() => {
    const code = dailyUrlValue.value || 'x8hc5d6';
    return `https://www.dailymotion.com/embed/video/${code}`;
});

const dataId = computed(() => {
    const params = new URLSearchParams(window.location.search);
    const elementId = params.get('elementId');

    return elementId
        ? `${CONSTANTS.PUBLISHING_KEY}__${elementId}`
        : CONSTANTS.PUBLISHING_KEY;
});

onBeforeMount(async () => {
    const value = await data.get({
        id: dataId.value,
        selectors,
    }) as { 'config.dailyUrl.value': string; 'config.dailyUrl.source': string };

    if (value) {
        dailyUrlValue.value = value['config.dailyUrl.value'];
        dailyUrlSource.value = value['config.dailyUrl.source'];
    }

    data.subscribe(
        dataId.value,
        (response) => {
            const responseData = response.data as {
                'config.dailyUrl.value': string;
                'config.dailyUrl.source': string;
            };
            dailyUrlValue.value = responseData['config.dailyUrl.value'];
            dailyUrlSource.value = responseData['config.dailyUrl.source'];
        },
        { selectors },
    );
});
</script>

<style scoped>
.sw-cms-el-dailymotion-iframe-wrapper {
    height: 500px;
}
</style>
```

**Key points:**

* `data.get()` fetches the initial element config using the element-specific `dataId`
* `data.subscribe()` keeps the element in sync whenever the config changes — it receives the same flat selector-keyed object as `data.get()` and is called regardless of where the change originates

![The image shows the Shopware administration's CMS layout editor. The current layout only has one block with a Dailymotion CMS element. The block shows the paused preview of the configured video.](../../../../assets/add-cms-element-via-admin-sdk-element.png "Dailymotion CMS element")

### The preview file

`swag-dailymotion-preview.vue` is the thumbnail shown in the block picker when a user browses the *Video* category.
In most cases it contains minimal logic — a static image, a skeleton, or a logo is sufficient:

```html
<template>
  <h2>Preview!</h2>
</template>
```

![The image shows the "Replace element" modal to replace the current block with another element. Depicted is the Dailymotion element which has the text "Preview!" as the element preview as configured in this example.](../../../../assets/add-cms-element-via-admin-sdk-preview.png "Dailymotion element preview")

## Storefront implementation

After completing the admin implementation, you also need a Storefront representation of your blocks. This is similar to typical plugin development, except for the path. All Storefront templates must follow this pattern:

`<app-name>/Resources/views/storefront/element/<elementname>.html.twig`

For more details, see the guide on [CMS element development for plugins](../../plugins/content/cms/add-cms-element#storefront-implementation).
Below is an example of how your storefront template
(`SwagBasicAppCmsElementExample/Resources/views/storefront/element/cms-element-swag-dailymotion.html.twig`) could look:

```twig
{% block element_swag_dailymotion %}
<div class="cms-element-swag-dailymotion" style="height: 100%; width: 100%">
    {% block element_dailymotion_image_inner %}
    <div class="cms-el-swag-dailymotion">
        <div style="position:relative; padding-bottom:56.25%; height:0; overflow:hidden;">
            <iframe style="width:100%; height:100%; position:absolute; left:0px; top:0px; overflow:hidden"
                    src="https://www.dailymotion.com/embed/video/{{ element.config.dailyUrl.value }}"
                    frameborder="0"
                    type="text/html"
                    width="100%"
                    height="100%">
            </iframe>
        </div>
    </div>
    {% endblock %}
</div>
{% endblock %}
```

---

---
url: /docs/v6.5/guides/plugins/apps/administration/add-cms-element-via-admin-sdk.md
---

# Add CMS Element

## Overview

This article will teach you how to create a new CMS element via the Meteor Admin SDK. The plugin in this example will be named `SwagBasicAppCmsElementExample`, similar to the other guides.

## Prerequisites

* Knowledge on the creation of [Plugins](/docs/guides/plugins/plugins/plugin-base-guide) or [Apps](/docs/guides/plugins/apps/app-base-guide)
* Knowledge on the [creation of custom admin components](/docs/guides/plugins/plugins/administration/add-custom-component#creating-a-custom-component)
* Understanding the [Meteor Admin SDK](https://shopware.github.io/meteor-admin-sdk/docs/guide/getting-started/installation)

::: info
This example uses TypeScript, which is recommended, but not required for developing Shopware.
:::

## Creating your custom element

Similar to [Creating a new custom element via plugin](/docs/guides/plugins/plugins/content/cms/add-cms-element#creating-your-custom-element), this article describes creating a new custom element via app.
Creating a new element requires Meteor Admin SDK.

Consider the same scenario to allow a shop manager configure a link to display the Dailymotion video. That is exactly what you are going to build.

### Target structure

You can decide what approach to use when creating apps since everything here is loaded via iFrame. However, Shopware's best practice is a full Vue.js approach.

When our extension is finished, you will get the following file structure:

```bash
// <plugin root>/src/Resources/app/administration/src
├── base
│   └── mainCommands.ts
├── main.ts
├── viewRenderer.ts
└── views
    └── swag-dailymotion
        ├── swag-dailymotion-config.ts
        ├── swag-dailymotion-element.ts
        └── swag-dailymotion-preview.ts
```

## Initial loading of components

Everything starts in the `main.ts` file:

```js
import 'regenerator-runtime/runtime';
import { location } from '@shopware-ag/meteor-admin-sdk';

// Only execute extensionSDK commands when
// it is inside a iFrame (only needed for plugins)
if (location.isIframe()) {
    if (location.is(location.MAIN_HIDDEN)) {
        // Execute the base commands
        import('./base/mainCommands');
    } else {
        // Render different views
        import('./viewRenderer');
    }
}
```

This is the main file, which is executed first and functions as the entry point.

Start with `if(location.isIframe())` to make sure only content used inside iFrames is loaded. While the SDK is used in apps and plugins, this check ensures the code is executed in the right place.

Next you need `if(location.is(location.MAIN_HIDDEN))` to **load the main commands**, which are defined in the `mainCommands.ts` file. This will only be used to load logic, but not templates into the Administration.

Lastly, the `else` case will be responsible for specific loading of views via `viewRenderer.ts`. This is where the view templates will be loaded.

### Loading all required templates

Now, create the `viewRenderer.ts` file, which includes the three mandatory files needed for a CMS element as below:

* `swag-dailymotion-config.ts`, which will handle the content of the CMS element configuration
* `swag-dailymotion-element.ts`, which represents the actual target element in the CMS
* `swag-dailymotion-preview.ts`, which is responsible for the preview, when selecting the CMS element in its selection screen

Observe that every file is named according to the component and prefixed with `swag-dailymotion`, (vendor prefix) to ensure no other developer accidentally chooses the same name.

Let us see how the component loading via `viewRenderer.ts` looks like:

```js
import Vue from 'vue';
import { location } from '@shopware-ag/meteor-admin-sdk';

// watch for height changes
location.startAutoResizer();

// start app views
const app = new Vue({
    el: '#app',
    data() {
        return { location };
    },
    components: {
        'SwagDailymotionElement':
            () => import('./views/swag-dailymotion/swag-dailymotion-element'),
        'SwagDailymotionConfig':
            () => import('./views/swag-dailymotion/swag-dailymotion-config'),
        'SwagDailymotionPreview':
            () => import('./views/swag-dailymotion/swag-dailymotion-preview'),
    },
    template: `
        <SwagDailymotionElement
            v-if="location.is('swag-dailymotion-element')"
        ></SwagDailymotionElement>
        <SwagDailymotionConfig
            v-else-if="location.is('swag-dailymotion-config')"
        ></SwagDailymotionConfig>
        <SwagDailymotionPreview
            v-else-if="location.is('swag-dailymotion-preview')"
        ></SwagDailymotionPreview>
    `,
});
```

Really straightforward, isn't it? As you probably know from Vue.js's Options API, you just need to load, register and use the Vue.js component to make them work.

What's especially interesting here is the use of the `location` object. This is a main concept of the Meteor Admin SDK, where Shopware provides dedicated `locationIds` to offer you places to inject your templates into. For further information on that, it is recommend to take a look at the documentation of the [Meteor Admin SDK](https://shopware.github.io/meteor-admin-sdk/docs/guide/concepts/locations) to learn more about its concepts.

In your case, we will get your own **auto-generated** `locationIds`, depending on the name of your CMS element and suffixes, such as `-element`, `-config`, and `-preview`.

Those will be available after **registering the component**, which we will do in the following chapter.

## Registering a new element

For this topic we head to `mainCommands.ts`, since the registration of CMS elements is something to be done in a global scope.

```js
import { cms } from '@shopware-ag/meteor-admin-sdk';

const CMS_ELEMENT_NAME = 'swag-dailymotion';
const CONSTANTS = {
    CMS_ELEMENT_NAME,
    PUBLISHING_KEY: `${CMS_ELEMENT_NAME}__config-element`,
};

void cms.registerCmsElement({
    name: CONSTANTS.CMS_ELEMENT_NAME,
    label: 'Dailymotion video',
    defaultConfig: {
        dailyUrl: {
            source: 'static',
            value: '',
        },
    },
});

export default CONSTANTS;
```

At first, you import the Meteor Admin SDK's cms object, used for `cms.registerCmsElement` to register a new element.

That is all about what is required to register your CMS element. As a best practice, it is recommended to create a **constant** for the CMS element name and the publishing key. This makes it easier to maintain and keep track of changes. The publishing key can be predefined since the name must be a combination of CMS element name and the `__config-element` suffix as shown above.

## Templates and communication with the Administration

The last files are the components inside our `views` folder. Just like you know it from typical CMS element loading, we will create a folder with the full component name, containing 3 files as shown below:

```bash
// <plugin root>/src/Resources/app/administration/src
views
└── swag-dailymotion
    ├── swag-dailymotion-config.ts
    ├── swag-dailymotion-element.ts
    └── swag-dailymotion-preview.ts
```

You can vary the structure of `swag-dailymotion`'s contents and create folders for each of the three. However, let us keep it simple with single file components.

### The config file

Let's go through each of the files to talk about it's contents, starting with `swag-dailymotion-config.ts`:

```js
import Vue from 'vue'
import { data } from "@shopware-ag/meteor-admin-sdk";
import CONSTANTS from "../../base/mainCommands";

export default Vue.extend({
    template: `
        <div>
          <h2>
            Config!
          </h2>
          Video-Code: <input v-model="dailyUrl" type="text"/><br/>
        </div>
    `,

    data(): Object {
        return {
            element: null
        }
    },

    computed: {
        dailyUrl: {
            get(): string {
                return this.element?.config?.dailyUrl?.value || '';
            },

            set(value: string): void {
                this.element.config.dailyUrl.value = value;

                data.update({
                    id: CONSTANTS.PUBLISHING_KEY,
                    data: this.element,
                });
            }
        }
    },

    created() {
        this.createdComponent();
    },

    methods: {
        async createdComponent() {
            this.element = await data.get({ id: CONSTANTS.PUBLISHING_KEY });
        }
    }
});
```

This file is the config component used to define every type of configuration for the CMS element. Most of the code will be common for experienced Shopware 6 developers, so here are some important highlights:

* Import `data` from the Meteor Admin SDK, which is required for data handling between this app and Shopware
* The `element` variable contains the typical CMS element object and is also used to manage the element configuration you want to edit
* The `publishingKey` is used to tell the Meteor Admin SDK in Shopware what piece of information you want to fetch. In this case, you need the `element` data

So, now you need a simple input field to get a `dailyUrl` for the Dailymotion video to be displayed. For that, first fetch the element via `data.get()` as seen in `createdComponent` and then link it to the computed property `dailyUrl` with getters and setters to mutate it. Using `data.update({ id, data })` you provide the publishing key `id` as a target and `data` for the data you want to save in Shopware.

With these small additions to typical CMS element behavior, you have already done with the config modal.

![Dailymotion config modal](../../../../assets/add-cms-element-via-admin-sdk-config.png)

### The element file

Now let's have a look at the result of `swag-dailymotion-element.ts`:

```js
import Vue from 'vue'
import { data } from "@shopware-ag/meteor-admin-sdk";
import CONSTANTS from "../../base/mainCommands";

export default Vue.extend({
    template: `
        <div>
            <h2>
              Element!
            </h2>
            <div class="sw-cms-el-dailymotion">
                <div class="sw-cms-el-dailymotion-iframe-wrapper">
                    <iframe
                        frameborder="0"
                        type="text/html"
                        width="100%"
                        height="100%"
                        :src="dailyUrl">
                    </iframe>
                </div>
            </div>
        </div>
    `,

    data(): { element: object|null } {
        return {
            element: null
        }
    },

    computed: {
        dailyUrl(): string {
            return `https://www.dailymotion.com/embed/video/${this.element?.config?.dailyUrl?.value || ''}`;
        }
    },

    created() {
        this.createdComponent();
    },

    methods: {
        async createdComponent() {
            this.element = await data.get({ id: CONSTANTS.PUBLISHING_KEY });
            data.subscribe(CONSTANTS.PUBLISHING_KEY, this.elementSubscriber);
        },

        elementSubscriber(response: { data: unknown, id: string }): void {
            this.element = response.data;
        }
    }
});
```

Here, you have the main rendering logic for the Administration's CMS element. This file shows what your element will look like when it's done. So besides a template and the computed `dailyUrl`, used to correctly load the Dailymotion video player, the only interesting part is the `createdComponent` method.

It initially fetches the `element` data, as you've already seen it in the config file. After that, using `data.subscribe(id, method)` it subscribes to the publishing key, which will update the element data automatically if something changes. It doesn't matter if the changes originate from our config modal outside Shopware or from somewhere else inside Shopware.

![Dailymotion CMS element](../../../../assets/add-cms-element-via-admin-sdk-element.png)

### The preview file

Lastly, have a look at `swag-dailymotion-preview.ts`. In most cases, not much logic is to be found here, since this is the preview loaded when choosing a CMS element for your block. It makes sense to show an example preview, a miniature skeleton of the result, or just the Dailymotion logo. Therefore, the following code will suffice for your example extension:

```js
import Vue from 'vue'

export default Vue.extend({
    template: `
        <h2>
          Preview!
        </h2>
    `,
});
```

![Dailymotion element preview](../../../../assets/add-cms-element-via-admin-sdk-preview.png)

## Storefront implementation

After everything for the admin is done, there is still the need for a storefront representation of your blocks. This works similarly to typical plugin development, with an exception to the path. All Storefront templates must match the following path pattern: `<app-name>/Resources/views/storefront/element/<elementname>.html.twig`

Since everything is already described in guide [CMS element development for plugins](/docs/guides/plugins/plugins/content/cms/add-cms-element#storefront-implementation), the following example just shows how your Storefront template (`swag-daiĺymotion/Resources/views/storefront/element/cms-element-swag-dailymotion.html.twig`) could look like:

```twig
{% block element_swag_dailymotion %}
<div class="cms-element-swag-dailymotion" style="height: 100%; width: 100%">
    {% block element_dailymotion_image_inner %}
    <div class="cms-el-swag-dailymotion">
        <div style="position:relative; padding-bottom:56.25%; height:0; overflow:hidden;">
            <iframe style="width:100%; height:100%; position:absolute; left:0px; top:0px; overflow:hidden"
                    src="https://www.dailymotion.com/embed/video//{{ element.config.dailyUrl.value }}"
                    frameborder="0"
                    type="text/html"
                    width="100%"
                    height="100%">
            </iframe>
        </div>
    </div>
    {% endblock %}
</div>
{% endblock %}
```

---

---
url: /docs/v6.5/guides/plugins/plugins/content/cms/add-cms-element.md
---

# Add CMS Element

## Overview

This article will teach you how to create a new CMS element via plugin. The plugin in this example will be named `SwagBasicExample`, similar to the other guides.

## Prerequisites

You won't learn how to create a plugin in this guide, head over to our Plugin base guide to create your first plugin.

This guide will also not explain how a custom component can be created in general, so head over to the official guide about creating a custom component to learn this first.

## Creating your custom element

Imagine you want to create a new element to display a Dailymotion video. The shop manager can configure the link of the video to be shown. That's exactly what you're going to build in this guide.

Creating a new element requires you to extend the Administration.

### Injecting into the Administration

The main entry point to customize the Administration via plugin is the `main.js` file. It has to be placed into a `<plugin root>/src/Resources/app/administration/src` directory in order to be automatically found by the Shopware platform.

## Registering a new element

Your plugin's structure should always match the core's structure. When thinking about creating a new element, it's a recommendation to recreate the file tree like in the core for your plugin. Thus, recreate this structure in your plugin: `<plugin root>/src/Resources/app/administration/src/module/sw-cms/elements`

In there, you create a directory for each new element you want to create. In this example a directory `dailymotion` is created.

Now create a new file `index.js` inside the `dailymotion` directory, since it will be loaded when importing this element in your `main.js`. Speaking of that, right after having created the `index.js` file, you can actually import your new element's directory in the `main.js` file already:

```javascript
// <plugin root>/src/Resources/app/administration/src/main.js
import './module/sw-cms/elements/dailymotion';
```

Now open up your empty `dailymotion/index.js` file. In order to register a new element to the system, you have to call the method `registerCmsElement` of the [cmsService](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Administration/Resources/app/administration/src/module/sw-cms/service/cms.service.js). Since it's available in the Dependency Injection Container, you can fetch it from there.

First of all, access our `Application` wrapper, which will grant you access to the DI container. So go ahead and fetch the `cmsService` from it and call the mentioned `registerCmsElement` method.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/index.js
Shopware.Service('cmsService').registerCmsElement();
```

The method `registerCmsElement` takes a configuration object, containing the following necessary data:

| Key | Description |
| :--- | :--- |
| name | The technical name of your element. Will be used for the template loading later on. |
| label | A name to be shown for your element in the User Interface. Preferably as a snippet key. |
| component | The Vue component to be used when rendering your actual element in the Administration. |
| configComponent | The Vue component defining the "configuration detail" page of your element. |
| previewComponent | The Vue component to be used in the "list of available elements". Just shows a tiny preview of what your element would look like if it was used. |
| defaultConfig | A default configuration to be applied to this element. Must be an object containing properties matching the used variable names, containing the default values. |
| hidden (optional) | Hides the element in the replace element modal. |
| removable (optional) | Removes the replace element icon. |

Go ahead and create this configuration object yourself. Here's what it should look like after having set all of those options:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/index.js
Shopware.Service('cmsService').registerCmsElement({
    name: 'dailymotion',
    label: 'sw-cms.elements.customDailymotionElement.label',
    component: 'sw-cms-el-dailymotion',
    configComponent: 'sw-cms-el-config-dailymotion',
    previewComponent: 'sw-cms-el-preview-dailymotion',
    defaultConfig: {
        dailyUrl: {
            source: 'static',
            value: ''
        }
    }
});
```

The property name does not require further explanation. However, you need to create a snippet file in your plugin directory for the label property.

To do this, create a folder with the name snippet in your `sw-cms` folder. After that, create the files for the languages, e.g. `de-DE.json` and `en-GB.json`. The content of your snippet file should look something like this:

```json
{
  "sw-cms": {
    "elements": {
      "customDailymotionElement": {
        "label": "Dailymotion video"
      }
    }
  }
}
```

To learn more about adding own snippets, please refer to [Add snippets to Administration](../../administration/adding-snippets) for more information.

For all three fields `component`, `configComponent` and `previewComponent`, components that do not *yet* exist were applied. Those will be created in the next few steps as well. The `defaultConfig` defines the default values for the element's configuration. There will be a text field to enter a Dailymotion video ID called `dailyUrl`.

Now you have to create the three missing components, let's start with the preview component.

## Building the preview

Create a new directory preview in your element's directory dailymotion. In there, create a new file `index.js`, just like for all components. Then register your component, using the `Shopware.Component` wrapper:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/preview/index.js
import template from './sw-cms-el-preview-dailymotion.html.twig';
import './sw-cms-el-preview-dailymotion.scss';

Shopware.Component.register('sw-cms-el-preview-dailymotion', {
    template
});
```

Just like most components, it has a custom template and some styles. Focus on the template first, create a new file `sw-cms-el-preview-dailymotion.html.twig`.

So, for instance, if you want to show the default 'mountain' preview image as an example, then copy it from `<Shopware root>/public/bundles/administration/static/img/cms/preview_mountain_small.jpg` to your static folder. You can also replace it with something of your own. Additionally, you can place icons `multicolor-action-play`. Head over to [icon library](https://component-library.shopware.com/icons/) to access them.

That means: You'll need a container to contain both the image and the icon. In there, you create an `img` tag and use the [sw-icon component](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Administration/Resources/app/administration/src/app/component/base/sw-icon/index.js) to display the icon.

```twig
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/preview/sw-cms-el-preview-dailymotion.html.twig
{% block sw_cms_element_dailymotion_preview %}
    <div class="sw-cms-el-preview-dailymotion">
        <img class="sw-cms-el-preview-dailymotion-img"
             :src="'customcmselement/static/img/background_dailymotion_preview.jpg' | asset">

        <sw-icon class="sw-cms-el-preview-dailymotion-icon"
                 name="multicolor-action-play"></sw-icon>
    </div>
{% endblock %}
```

The icon would now be displayed beneath the image, so let's add some styles for this by creating the file `sw-cms-el-preview-dailymotion.scss`.

The container needs to have a `position: relative;` style. This is necessary, so the child can be positioned absolutely and will do so relative to the container's position. Thus, the icon receives a `position: absolute; style`, plus some top and left values to center it.

```css
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/preview/sw-cms-el-preview-dailymotion.scss
.sw-cms-el-preview-dailymotion {
    position: relative;

    .sw-cms-el-preview-dailymotion-img {
        display: block;
        max-width: 100%;
    }

    .sw-cms-el-preview-dailymotion-icon {
        $icon-height: 50px;
        $icon-width: $icon-height;
        position: absolute;
        height: $icon-height;
        width: $icon-width;

        left: calc(50% - #{$icon-width/2});
        top: calc(50% - #{$icon-height/2});
    }
}
```

The centered positioning will be done by translating the elements by 50% via `top` and `left` properties. Since that would be 50% from the upper left corner of the icon, this wouldn't really center the icon yet. Subtract the half of the icon's width and height and then you're fine.

One last thing: Import your preview component in your element's `index.js` file, so it's loaded.

## Rendering the component

The next would be the main component `sw-cms-el-dailymotion`, the one to be rendered when the shop manager actually decided to use your element by clicking on the preview. Now, you want to show the actually configured video here now. Start with the basic again, create a new directory `component`, in there a new file `index.js` and then register your component `sw-cms-el-dailymotion`.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/component/index.js
import template from './sw-cms-el-dailymotion.html.twig';
import './sw-cms-el-dailymotion.scss';

Shopware.Component.register('sw-cms-el-dailymotion', {
    template
});
```

In addition, create the template file `sw-cms-el-dailymotion.html.twig` and the `.scss` file `sw-cms-el-dailymotion.scss`.

The template doesn't have to include a lot. Having a look at how Dailymotion video embedding works, you just have to add an `iframe` with a src attribute pointing to the video.

```twig
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/component/sw-cms-el-dailymotion.html.twig
{% block sw_cms_element_dailymotion %}
    <div class="sw-cms-el-dailymotion">
        <div class="sw-cms-el-dailymotion-iframe-wrapper">
            <iframe frameborder="0"
                    type="text/html"
                    width="100%"
                    height="100%"
                    :src="dailyUrl">
            </iframe>
        </div>
    </div>
{% endblock %}
```

You can't just use a static `src` here, since the shop manager wants to configure the video he wants to show. Thus, we're fetching that link via VueJS now.

Let's add the code to provide the src for the iframe. For this case you're going to use a [computed property](https://vuejs.org/v2/guide/computed.html).

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/component/index.js
import template from './sw-cms-el-dailymotion.html.twig';
import './sw-cms-el-dailymotion.scss';

Shopware.Component.register('sw-cms-el-dailymotion', {
    template,

    computed: {
        dailyUrl() {
            return `https://www.dailymotion.com/embed/video/${this.element.config.dailyUrl.value}`;
        }
    },    
});
```

The link being used has to follow this pattern: `https://www.dailymotion.com/embed/video/<videoId>`, so the only variable you need from the shop manager is the video ID. That's what you're doing here - you're building the link like mentioned above and you add the value of `dailyUrl` from the config. This value will be provided by the config component, that you're going to create in the next step.

In order for this to work though, you have to call the method `initElementConfig` from the `cms-element` mixin. This will take care of dealing with the `configComponent` and therefore providing the configured values.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/component/index.js
import template from './sw-cms-el-dailymotion.html.twig';
import './sw-cms-el-dailymotion.scss';

Shopware.Component.register('sw-cms-el-dailymotion', {
    template,

    mixins: [
        'cms-element'
    ],

    computed: {
        dailyUrl() {
            return `https://www.dailymotion.com/embed/video/${this.element.config.dailyUrl.value}`;
        }
    },

    created() {
        this.createdComponent();
    },

    methods: {
        createdComponent() {
            this.initElementConfig('dailymotion');
        }
    }
});
```

Now, the method `initElementConfig` is immediately executed once this component is created.

Time to add the last remaining part of this component: The styles to be applied. Since Dailymotion takes care of responsive layouts itself, you just have to scale the iFrame to 100% width and 100% height. Yet, there's a recommended `min-height` of 315px, so add that one as well.

```css
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/component/sw-cms-el-dailymotion.scss
.sw-cms-el-dailymotion {
    height: 100%;
    width: 100%;
    min-height: 315px;

    .sw-cms-el-dailymotion-iframe-wrapper {
        position: relative;
        padding-bottom: 56.25%;
        height: 0;
        overflow: hidden;

        iframe {
            width: 100%;
            height: 100%;
            position: absolute;
            left: 0;
            top: 0;
            overflow: hidden
        }
    }
}
```

That's it for this component! Import it in your element's `index.js` file.

## The configuration

Let's head over to the last remaining component. Create a directory `config`, an `index.js` file in there and register your config component `sw-cms-el-config-dailymotion`.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/config/index.js
import template from './sw-cms-el-config-dailymotion.html.twig';

Shopware.Component.register('sw-cms-el-config-dailymotion', {
    template,

    mixins: [
        'cms-element'
    ],

    computed: {
        dailyUrl: {
            get() {
                return this.element.config.dailyUrl.value;
            },

            set(value) {
                this.element.config.dailyUrl.value = value;
            }
        }
    },

    created() {
        this.createdComponent();
    },

    methods: {
        createdComponent() {
            this.initElementConfig('dailymotion');
        },

        onElementUpdate(value) {
            this.element.config.dailyUrl.value = value;

            this.$emit('element-update', this.element);
        }
    }
});
```

Just like always, it comes with a template, no styles necessary here though. Create the template file now. Also, the `initElementConfig` method has to be called in here as well, just the same way you've done it in your main component. A little spoiler: This file will remain like this already, you can close it now.

Open the template `sw-cms-el-config-dailymotion.html.twig` instead. To be displayed in the config, we just need a text element, so the shop manager can apply a Dailymotion video ID.

```twig
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/config/sw-cms-el-config-dailymotion.html.twig
{% block sw_cms_element_dailymotion_config %}
    <sw-text-field
          v-model="dailyUrl"
          class="swag-dailymotion-field"
          label="Dailymotion video link"
          placeholder="Enter dailymotion link..."
          @input="onElementUpdate"
          @change="onElementUpdate">
    </sw-text-field>
{% endblock %}
```

The `v-model` takes care of binding the field's values to the values from the config. Don't forget to include your config in your `index.js`:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/index.js
import './component';
import './config';
import './preview';

Shopware.Service('cmsService').registerCmsElement({
    // ...
});
```

That's it! You could now go ahead and fully test your new element! Install this plugin via `bin/console plugin:install --activate SwagBasicExample`, rebuild the Administration using the following command and then start using your new element in the Administration.

```bash
./bin/build-administration.sh
```

```bash
composer run build:js:admin
```

Of course, the Storefront implementation is still missing, so your element wouldn't be rendered in the Storefront yet.

## Storefront implementation

Just like the CMS blocks, each element's storefront representation is always expected in the directory `platform/src/Storefront/Resources/views/storefront/element`. In there, a twig template named after your custom element is expected, in this case a file named `cms-element-dailymotion.html.twig`.

So go ahead and re-create that structure in your plugin: `<plugin root>/src/Resources/views/storefront/element/`

In there create a new twig template named after your element, so `cms-element-dailymotion.html.twig` that is.

The template for this is super easy though, just like it's been in your main component for the Administration. Just add an iFrame again. Simply apply the same styles like in the Administration, 100% to both height and width that is.

```twig
// platform/src/Storefront/Resources/views/storefront/element/cms-element-dailymotion.html.twig
{% block element_dailymotion %}
    <div class="cms-element-dailymotion" style="height: 100%; width: 100%">

        {% block element_dailymotion_image_inner %}
            <div class="cms-el-dailymotion">
                <div style="position:relative; padding-bottom:56.25%; height:0; overflow:hidden;">
                    <iframe style="width:100%; height:100%; position:absolute; left:0px; top:0px; overflow:hidden"
                            src="https://www.dailymotion.com/embed/video//{{ element.config.dailyUrl.value }}"
                            frameborder="0"
                            type="text/html"
                            width="100%"
                            height="100%">
                    </iframe>
                </div>
            </div>
        {% endblock %}
    </div>
{% endblock %}
```

The URL is parsed here using the twig variable element, which is automatically available in your element's template.

Once more: That's it! Your element is now fully working! The shop manager can choose your new element in the 'Shopping Experiences' module, he can configure it and even see it being rendered live in the Administration. After saving and applying this layout to e.g. a category, this element will also be rendered into the Storefront.

## Next steps

There are many possibilities to extend Shopware's CMS. If you haven't done so already, consider using your element in a cms block. To learn how to do this, take a look at the guide on [Add custom cms block](add-cms-block).

---

---
url: /docs/v6.6/guides/plugins/apps/administration/add-cms-element-via-admin-sdk.md
---

# Add CMS Element

## Overview

This article will teach you how to create a new CMS element via the Meteor Admin SDK. The plugin in this example will be named `SwagBasicAppCmsElementExample`, similar to the other guides.

## Prerequisites

* Knowledge on the creation of [Plugins](/docs/guides/plugins/plugins/plugin-base-guide) or [Apps](/docs/guides/plugins/apps/app-base-guide)
* Knowledge on the [creation of custom admin components](/docs/guides/plugins/plugins/administration/add-custom-component#creating-a-custom-component)
* Understanding the [Meteor Admin SDK](/resources/admin-extension-sdk/getting-started/installation)

::: info
This example uses TypeScript, which is recommended, but not required for developing Shopware.
:::

## Creating your custom element

Similar to [Creating a new custom element via plugin](/docs/guides/plugins/plugins/content/cms/add-cms-element#creating-your-custom-element), this article describes creating a new custom element via app.
Creating a new element requires Meteor Admin SDK.

Consider the same scenario to allow a shop manager configure a link to display the Dailymotion video. That is exactly what you are going to build.

### Target structure

You can decide what approach to use when creating apps since everything here is loaded via iFrame. However, Shopware's best practice is a full Vue.js approach.

When our extension is finished, you will get the following file structure:

```bash
// <plugin root>/src/Resources/app/administration/src
├── base
│   └── mainCommands.ts
├── main.ts
├── viewRenderer.ts
└── views
    └── swag-dailymotion
        ├── swag-dailymotion-config.ts
        ├── swag-dailymotion-element.ts
        └── swag-dailymotion-preview.ts
```

## Initial loading of components

Everything starts in the `main.ts` file:

```javascript
// Prior to 6.7
import 'regenerator-runtime/runtime';
import { location } from '@shopware-ag/meteor-admin-sdk';

// Only execute extensionSDK commands when
// it is inside an iFrame
if (location.isIframe()) {
    if (location.is(location.MAIN_HIDDEN)) {
        // Execute the base commands
        import('./base/mainCommands');
    } else {
        // Render different views
        import('./viewRenderer');
    }
}
```

```javascript
// 6.7 and above (inside meteor-app folder)
import 'regenerator-runtime/runtime';
import { location } from '@shopware-ag/meteor-admin-sdk';

if (location.is(location.MAIN_HIDDEN)) {
    // Execute the base commands
    import('./base/mainCommands');
} else {
    // Render different views
    import('./viewRenderer');
}
```

This is the main file, which is executed first and functions as the entry point.

Use `if(location.is(location.MAIN_HIDDEN))` to **load the main commands**, which are defined in the `mainCommands.ts` file. This will only be used to load logic, but not templates into the Administration.

Lastly, the `else` case will be responsible for specific loading of views via `viewRenderer.ts`. This is where the view templates will be loaded.

### Loading all required templates

Now, create the `viewRenderer.ts` file, which includes the three mandatory files needed for a CMS element as below:

* `swag-dailymotion-config.ts`, which will handle the content of the CMS element configuration
* `swag-dailymotion-element.ts`, which represents the actual target element in the CMS
* `swag-dailymotion-preview.ts`, which is responsible for the preview, when selecting the CMS element in its selection screen

Observe that every file is named according to the component and prefixed with `swag-dailymotion`, (vendor prefix) to ensure no other developer accidentally chooses the same name.

Let us see how the component loading via `viewRenderer.ts` looks like:

```javascript
import Vue from 'vue';
import { location } from '@shopware-ag/meteor-admin-sdk';

// watch for height changes
location.startAutoResizer();

// start app views
const app = new Vue({
    el: '#app',
    data() {
        return { location };
    },
    components: {
        'SwagDailymotionElement':
            () => import('./views/swag-dailymotion/swag-dailymotion-element'),
        'SwagDailymotionConfig':
            () => import('./views/swag-dailymotion/swag-dailymotion-config'),
        'SwagDailymotionPreview':
            () => import('./views/swag-dailymotion/swag-dailymotion-preview'),
    },
    template: `
        <SwagDailymotionElement
            v-if="location.is('swag-dailymotion-element')"
        ></SwagDailymotionElement>
        <SwagDailymotionConfig
            v-else-if="location.is('swag-dailymotion-config')"
        ></SwagDailymotionConfig>
        <SwagDailymotionPreview
            v-else-if="location.is('swag-dailymotion-preview')"
        ></SwagDailymotionPreview>
    `,
});
```

Really straightforward, isn't it? As you probably know from Vue.js's Options API, you just need to load, register and use the Vue.js component to make them work.

What's especially interesting here is the use of the `location` object. This is a main concept of the Meteor Admin SDK, where Shopware provides dedicated `locationIds` to offer you places to inject your templates into. For further information on that, it is recommend to take a look at the documentation of the [Meteor Admin SDK](/resources/admin-extension-sdk/concepts/locations) to learn more about its concepts.

In your case, we will get your own **auto-generated** `locationIds`, depending on the name of your CMS element and suffixes, such as `-element`, `-config`, and `-preview`.

Those will be available after **registering the component**, which we will do in the following chapter.

## Registering a new element

For this topic we head to `mainCommands.ts`, since the registration of CMS elements is something to be done in a global scope.

```javascript
import { cms } from '@shopware-ag/meteor-admin-sdk';

const CMS_ELEMENT_NAME = 'swag-dailymotion';
const CONSTANTS = {
    CMS_ELEMENT_NAME,
    PUBLISHING_KEY: `${CMS_ELEMENT_NAME}__config-element`,
};

void cms.registerCmsElement({
    name: CONSTANTS.CMS_ELEMENT_NAME,
    label: 'Dailymotion video',
    defaultConfig: {
        dailyUrl: {
            source: 'static',
            value: '',
        },
    },
});

export default CONSTANTS;
```

At first, you import the Meteor Admin SDK's cms object, used for `cms.registerCmsElement` to register a new element.

That is all about what is required to register your CMS element. As a best practice, it is recommended to create a **constant** for the CMS element name and the publishing key. This makes it easier to maintain and keep track of changes. The publishing key can be predefined since the name must be a combination of CMS element name and the `__config-element` suffix as shown above.

## Templates and communication with the Administration

The last files are the components inside our `views` folder. Just like you know it from typical CMS element loading, we will create a folder with the full component name, containing 3 files as shown below:

```bash
// <plugin root>/src/Resources/app/administration/src
views
└── swag-dailymotion
    ├── swag-dailymotion-config.ts
    ├── swag-dailymotion-element.ts
    └── swag-dailymotion-preview.ts
```

You can vary the structure of `swag-dailymotion`'s contents and create folders for each of the three. However, let us keep it simple with single file components.

### The config file

Let's go through each of the files to talk about it's contents, starting with `swag-dailymotion-config.ts`:

```javascript
import Vue from 'vue'
import { data } from "@shopware-ag/meteor-admin-sdk";
import CONSTANTS from "../../base/mainCommands";

export default Vue.extend({
    template: `
        <div>
          <h2>
            Config!
          </h2>
          Video-Code: <input v-model="dailyUrl" type="text"/><br/>
        </div>
    `,

    data(): Object {
        return {
            element: null
        }
    },

    computed: {
        dailyUrl: {
            get(): string {
                return this.element?.config?.dailyUrl?.value || '';
            },

            set(value: string): void {
                this.element.config.dailyUrl.value = value;

                data.update({
                    id: CONSTANTS.PUBLISHING_KEY,
                    data: this.element,
                });
            }
        }
    },

    created() {
        this.createdComponent();
    },

    methods: {
        async createdComponent() {
            this.element = await data.get({ id: CONSTANTS.PUBLISHING_KEY });
        }
    }
});
```

This file is the config component used to define every type of configuration for the CMS element. Most of the code will be common for experienced Shopware 6 developers, so here are some important highlights:

* Import `data` from the Meteor Admin SDK, which is required for data handling between this app and Shopware
* The `element` variable contains the typical CMS element object and is also used to manage the element configuration you want to edit
* The `publishingKey` is used to tell the Meteor Admin SDK in Shopware what piece of information you want to fetch. In this case, you need the `element` data

So, now you need a simple input field to get a `dailyUrl` for the Dailymotion video to be displayed. For that, first fetch the element via `data.get()` as seen in `createdComponent` and then link it to the computed property `dailyUrl` with getters and setters to mutate it. Using `data.update({ id, data })` you provide the publishing key `id` as a target and `data` for the data you want to save in Shopware.

With these small additions to typical CMS element behavior, you have already done with the config modal.

![Dailymotion config modal](../../../../assets/add-cms-element-via-admin-sdk-config.png)

### The element file

Now let's have a look at the result of `swag-dailymotion-element.ts`:

```javascript
import Vue from 'vue'
import { data } from "@shopware-ag/meteor-admin-sdk";
import CONSTANTS from "../../base/mainCommands";

export default Vue.extend({
    template: `
        <div>
            <h2>
              Element!
            </h2>
            <div class="sw-cms-el-dailymotion">
                <div class="sw-cms-el-dailymotion-iframe-wrapper">
                    <iframe
                        frameborder="0"
                        type="text/html"
                        width="100%"
                        height="100%"
                        :src="dailyUrl">
                    </iframe>
                </div>
            </div>
        </div>
    `,

    data(): { element: object|null } {
        return {
            element: null
        }
    },

    computed: {
        dailyUrl(): string {
            return `https://www.dailymotion.com/embed/video/${this.element?.config?.dailyUrl?.value || ''}`;
        }
    },

    created() {
        this.createdComponent();
    },

    methods: {
        async createdComponent() {
            this.element = await data.get({ id: CONSTANTS.PUBLISHING_KEY });
            data.subscribe(CONSTANTS.PUBLISHING_KEY, this.elementSubscriber);
        },

        elementSubscriber(response: { data: unknown, id: string }): void {
            this.element = response.data;
        }
    }
});
```

Here, you have the main rendering logic for the Administration's CMS element. This file shows what your element will look like when it's done. So besides a template and the computed `dailyUrl`, used to correctly load the Dailymotion video player, the only interesting part is the `createdComponent` method.

It initially fetches the `element` data, as you've already seen it in the config file. After that, using `data.subscribe(id, method)` it subscribes to the publishing key, which will update the element data automatically if something changes. It doesn't matter if the changes originate from our config modal outside Shopware or from somewhere else inside Shopware.

![Dailymotion CMS element](../../../../assets/add-cms-element-via-admin-sdk-element.png)

### The preview file

Lastly, have a look at `swag-dailymotion-preview.ts`. In most cases, not much logic is to be found here, since this is the preview loaded when choosing a CMS element for your block. It makes sense to show an example preview, a miniature skeleton of the result, or just the Dailymotion logo. Therefore, the following code will suffice for your example extension:

```javascript
import Vue from 'vue'

export default Vue.extend({
    template: `
        <h2>
          Preview!
        </h2>
    `,
});
```

![Dailymotion element preview](../../../../assets/add-cms-element-via-admin-sdk-preview.png)

## Storefront implementation

After everything for the admin is done, there is still the need for a storefront representation of your blocks. This works similarly to typical plugin development, with an exception to the path. All Storefront templates must match the following path pattern: `<app-name>/Resources/views/storefront/element/<elementname>.html.twig`

Since everything is already described in guide [CMS element development for plugins](/docs/guides/plugins/plugins/content/cms/add-cms-element#storefront-implementation), the following example just shows how your Storefront template (`swag-daiĺymotion/Resources/views/storefront/element/cms-element-swag-dailymotion.html.twig`) could look like:

```twig
{% block element_swag_dailymotion %}
<div class="cms-element-swag-dailymotion" style="height: 100%; width: 100%">
    {% block element_dailymotion_image_inner %}
    <div class="cms-el-swag-dailymotion">
        <div style="position:relative; padding-bottom:56.25%; height:0; overflow:hidden;">
            <iframe style="width:100%; height:100%; position:absolute; left:0px; top:0px; overflow:hidden"
                    src="https://www.dailymotion.com/embed/video//{{ element.config.dailyUrl.value }}"
                    frameborder="0"
                    type="text/html"
                    width="100%"
                    height="100%">
            </iframe>
        </div>
    </div>
    {% endblock %}
</div>
{% endblock %}
```

---

---
url: /docs/v6.6/guides/plugins/plugins/content/cms/add-cms-element.md
---

# Add CMS Element

## Overview

This article will teach you how to create a new CMS element via plugin.
The plugin in this example will be named `SwagBasicExample`, similar to the other guides.

## Prerequisites

You won't learn how to create a plugin in this guide, head over to our Plugin base guide to create your first plugin.

This guide will also not explain how a custom component can be created in general, so head over to the official guide about creating a custom component to learn this first.

## Creating your custom element

Imagine you want to create a new element to display a Dailymotion video.
The shop managers can configure the link of the video to be shown. That's exactly what you're going to build in this guide.

Creating a new element requires you to extend the Administration.

### Injecting into the Administration

The main entry point to customize the Administration via plugin is the `main.js` file.
It has to be placed into a `<plugin root>/src/Resources/app/administration/src` directory in order to be automatically found by the Shopware platform.

## Registering a new element

Your plugin's structure should always match the core's structure.
When thinking about creating a new element, it's a recommendation to recreate the file tree like in the core for your plugin.
Thus, recreate this structure in your plugin: `<plugin root>/src/Resources/app/administration/src/module/sw-cms/elements`

In there, you create a directory for each new element you want to create. In this example a directory `dailymotion` is created.

Now create a new file `index.js` inside the `dailymotion` directory, since it will be loaded when importing this element in your `main.js`.
Speaking of that, right after having created the `index.js` file, you can actually import your new element's directory in the `main.js` file already:

```javascript
// <plugin root>/src/Resources/app/administration/src/main.js
import './module/sw-cms/elements/dailymotion';
```

Now open up your empty `dailymotion/index.js` file.
In order to register a new element to the system, you have to call the method `registerCmsElement` of the [cmsService](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Administration/Resources/app/administration/src/module/sw-cms/service/cms.service.js).
Since it's available in the Dependency Injection Container, you can fetch it from there.

First of all, access our `Application` wrapper, which will grant you access to the DI container.
So go ahead and fetch the `cmsService` from it and call the mentioned `registerCmsElement` method.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/index.js
Shopware.Service('cmsService').registerCmsElement();
```

The method `registerCmsElement` takes a configuration object, containing the following necessary data:

| Key                  | Description                                                                                                                                                     |
|:---------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------|
| name                 | The technical name of your element. Will be used for the template loading later on.                                                                             |
| label                | A name to be shown for your element in the User Interface. Preferably as a snippet key.                                                                         |
| component            | The Vue component to be used when rendering your actual element in the Administration.                                                                          |
| configComponent      | The Vue component defining the "configuration detail" page of your element.                                                                                     |
| previewComponent     | The Vue component to be used in the "list of available elements". Just shows a tiny preview of what your element would look like if it was used.                |
| defaultConfig        | A default configuration to be applied to this element. Must be an object containing properties matching the used variable names, containing the default values. |
| hidden (optional)    | Hides the element in the replace element modal.                                                                                                                 |
| removable (optional) | Removes the replace element icon.                                                                                                                               |

Go ahead and create this configuration object yourself.
Here's what it should look like after having set all of those options:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/index.js
Shopware.Service('cmsService').registerCmsElement({
    name: 'dailymotion',
    label: 'sw-cms.elements.customDailymotionElement.label',
    component: 'sw-cms-el-dailymotion',
    configComponent: 'sw-cms-el-config-dailymotion',
    previewComponent: 'sw-cms-el-preview-dailymotion',
    defaultConfig: {
        dailyUrl: {
            source: 'static',
            value: ''
        }
    }
});
```

The property name does not require further explanation.
However, you need to create a snippet file in your plugin directory for the label property.

To do this, create a folder with the name snippet in your `sw-cms` folder.
After that, create the files for the languages, e.g. `de-DE.json` and `en-GB.json`.
The content of your snippet file should look something like this:

```json
{
  "sw-cms": {
    "elements": {
      "customDailymotionElement": {
        "label": "Dailymotion video"
      }
    }
  }
}
```

To learn more about adding own snippets, please refer to [Add snippets to Administration](../../administration/adding-snippets) for more information.

For all three fields `component`, `configComponent` and `previewComponent`, components that do not *yet* exist were applied.
Those will be created in the next few steps as well. The `defaultConfig` defines the default values for the element's configuration.
There will be a text field to enter a Dailymotion video ID called `dailyUrl`.

Now you have to create the three missing components, let's start with the preview component.

## Building the preview

Create a new directory preview in your element's directory dailymotion. In there, create a new file `index.js`, just like for all components.
Then register your component, using the `Shopware.Component` wrapper:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/preview/index.js
import template from './sw-cms-el-preview-dailymotion.html.twig';
import './sw-cms-el-preview-dailymotion.scss';

Shopware.Component.register('sw-cms-el-preview-dailymotion', {
    template
});
```

Just like most components, it has a custom template and some styles.
Focus on the template first, create a new file `sw-cms-el-preview-dailymotion.html.twig`.

So, for instance, if you want to show the default 'mountain' preview image as an example, then copy it from `<Shopware root>/public/bundles/administration/static/img/cms/preview_mountain_small.jpg` to your static folder.
You can also replace it with something of your own. Additionally, you can place icons `multicolor-action-play`.
Head over to [icon library](https://component-library.shopware.com/icons/) to access them.

That means: You'll need a container to contain both the image and the icon.
In there, you create an `img` tag and use the [sw-icon component](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Administration/Resources/app/administration/src/app/component/base/sw-icon/index.js) to display the icon.

```twig
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/preview/sw-cms-el-preview-dailymotion.html.twig
{% block sw_cms_element_dailymotion_preview %}
    <div class="sw-cms-el-preview-dailymotion">
        <img class="sw-cms-el-preview-dailymotion-img"
             :src="'customcmselement/static/img/background_dailymotion_preview.jpg' | asset">

        <sw-icon class="sw-cms-el-preview-dailymotion-icon"
                 name="multicolor-action-play"></sw-icon>
    </div>
{% endblock %}
```

The icon would now be displayed beneath the image, so let's add some styles for this by creating the file `sw-cms-el-preview-dailymotion.scss`.

The container needs to have a `position: relative;` style.
This is necessary, so the child can be positioned absolutely and will do so relative to the container's position.
Thus, the icon receives a `position: absolute;` style, plus some top and left values to center it.

```css
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/preview/sw-cms-el-preview-dailymotion.scss
.sw-cms-el-preview-dailymotion {
    position: relative;

    .sw-cms-el-preview-dailymotion-img {
        display: block;
        max-width: 100%;
    }

    .sw-cms-el-preview-dailymotion-icon {
        $icon-height: 50px;
        $icon-width: $icon-height;
        position: absolute;
        height: $icon-height;
        width: $icon-width;

        left: calc(50% - #{$icon-width/2});
        top: calc(50% - #{$icon-height/2});
    }
}
```

The centered positioning will be done by translating the elements by 50% via `top` and `left` properties.
Since that would be 50% from the upper left corner of the icon, this wouldn't really center the icon yet.
Subtract the half of the icon's width and height and then you're fine.

One last thing: Import your preview component in your element's `index.js` file, so it's loaded.

## Rendering the component

The next would be the main component `sw-cms-el-dailymotion`, the one to be rendered when the shop managers actually decided to use your element by clicking on the preview.
Now, you want to show the actually configured video here now.
Start with the basic again, create a new directory `component`, in there a new file `index.js` and then register your component `sw-cms-el-dailymotion`.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/component/index.js
import template from './sw-cms-el-dailymotion.html.twig';
import './sw-cms-el-dailymotion.scss';

Shopware.Component.register('sw-cms-el-dailymotion', {
    template
});
```

In addition, create the template file `sw-cms-el-dailymotion.html.twig` and the `.scss` file `sw-cms-el-dailymotion.scss`.

The template doesn't have to include a lot.
Having a look at how Dailymotion video embedding works, you just have to add an `iframe` with a src attribute pointing to the video.

```twig
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/component/sw-cms-el-dailymotion.html.twig
{% block sw_cms_element_dailymotion %}
    <div class="sw-cms-el-dailymotion">
        <div class="sw-cms-el-dailymotion-iframe-wrapper">
            <iframe frameborder="0"
                    type="text/html"
                    width="100%"
                    height="100%"
                    :src="dailyUrl">
            </iframe>
        </div>
    </div>
{% endblock %}
```

You can't just use a static `src` here, since the shop managers want to configure the video they want to show.
Thus, we're fetching that link via Vue.js now.

Let's add the code to provide the src for the iframe. For this case you're going to use a [computed property](https://vuejs.org/v2/guide/computed.html).

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/component/index.js
import template from './sw-cms-el-dailymotion.html.twig';
import './sw-cms-el-dailymotion.scss';

Shopware.Component.register('sw-cms-el-dailymotion', {
    template,

    computed: {
        dailyUrl() {
            return `https://www.dailymotion.com/embed/video/${this.element.config.dailyUrl.value}`;
        }
    },    
});
```

The link being used has to follow this pattern: `https://www.dailymotion.com/embed/video/<videoId>`, so the only variable you need from the shop managers is the video ID.
That's what you're doing here - you're building the link like mentioned above, and you add the value of `dailyUrl` from the config.
This value will be provided by the config component, that you're going to create in the next step.

In order for this to work though, you have to call the method `initElementConfig` from the `cms-element` mixin.
This will take care of dealing with the `configComponent` and therefore providing the configured values.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/component/index.js
import template from './sw-cms-el-dailymotion.html.twig';
import './sw-cms-el-dailymotion.scss';

Shopware.Component.register('sw-cms-el-dailymotion', {
    template,

    mixins: [
        'cms-element'
    ],

    computed: {
        dailyUrl() {
            return `https://www.dailymotion.com/embed/video/${this.element.config.dailyUrl.value}`;
        }
    },

    created() {
        this.createdComponent();
    },

    methods: {
        createdComponent() {
            this.initElementConfig('dailymotion');
        }
    }
});
```

Now, the method `initElementConfig` is immediately executed once this component is created.

Time to add the last remaining part of this component: The styles to be applied.
Since Dailymotion takes care of responsive layouts itself, you just have to scale the iFrame to 100% width and 100% height.
Yet, there's a recommended `min-height` of 315px, so add that one as well.

```css
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/component/sw-cms-el-dailymotion.scss
.sw-cms-el-dailymotion {
    height: 100%;
    width: 100%;
    min-height: 315px;

    .sw-cms-el-dailymotion-iframe-wrapper {
        position: relative;
        padding-bottom: 56.25%;
        height: 0;
        overflow: hidden;

        iframe {
            width: 100%;
            height: 100%;
            position: absolute;
            left: 0;
            top: 0;
            overflow: hidden
        }
    }
}
```

That's it for this component! Import it in your element's `index.js` file.

## The configuration

Let's head over to the last remaining component. Create a directory `config`, an `index.js` file in there and register your config component `sw-cms-el-config-dailymotion`.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/config/index.js
import template from './sw-cms-el-config-dailymotion.html.twig';

Shopware.Component.register('sw-cms-el-config-dailymotion', {
    template,

    mixins: [
        'cms-element'
    ],

    computed: {
        dailyUrl: {
            get() {
                return this.element.config.dailyUrl.value;
            },

            set(value) {
                this.element.config.dailyUrl.value = value;
            }
        }
    },

    created() {
        this.createdComponent();
    },

    methods: {
        createdComponent() {
            this.initElementConfig('dailymotion');
        },

        onElementUpdate(value) {
            this.element.config.dailyUrl.value = value;

            this.$emit('element-update', this.element);
        }
    }
});
```

Just like always, it comes with a template, no styles necessary here though.
Create the template file now. Also, the `initElementConfig` method has to be called in here as well, just the same way you've done it in your main component.
A little spoiler: This file will remain like this already, you can close it now.

Open the template `sw-cms-el-config-dailymotion.html.twig` instead.
To be displayed in the config, we just need a text element, so the shop managers can apply a Dailymotion video ID.

```twig
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/config/sw-cms-el-config-dailymotion.html.twig
{% block sw_cms_element_dailymotion_config %}
    <sw-text-field
          v-model="dailyUrl"
          class="swag-dailymotion-field"
          label="Dailymotion video link"
          placeholder="Enter dailymotion link..."
          @update:value="onElementUpdate">
    </sw-text-field>
{% endblock %}
```

The `v-model` takes care of binding the field's values to the values from the config.
Don't forget to include your config in your `index.js`:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/index.js
import './component';
import './config';
import './preview';

Shopware.Service('cmsService').registerCmsElement({
    // ...
});
```

That's it! You could now go ahead and fully test your new element!
Install this plugin via `bin/console plugin:install --activate SwagBasicExample`, rebuild the Administration using the following command and then start using your new element in the Administration.

```bash
./bin/build-administration.sh
```

```bash
composer run build:js:admin
```

Of course, the Storefront implementation is still missing, so your element wouldn't be rendered in the Storefront yet.

## Storefront implementation

Just like the CMS blocks, each element's storefront representation is always expected in the directory `platform/src/Storefront/Resources/views/storefront/element`.
In there, a twig template named after your custom element is expected, in this case a file named `cms-element-dailymotion.html.twig`.

So go ahead and re-create that structure in your plugin: `<plugin root>/src/Resources/views/storefront/element/`

In there create a new twig template named after your element, so `cms-element-dailymotion.html.twig` that is.

The template for this is super easy though, just like it's been in your main component for the Administration.
Just add an iFrame again. Simply apply the same styles as in the Administration, 100% to both height and width that is.

```twig
// platform/src/Storefront/Resources/views/storefront/element/cms-element-dailymotion.html.twig
{% block element_dailymotion %}
    <div class="cms-element-dailymotion" style="height: 100%; width: 100%">

        {% block element_dailymotion_image_inner %}
            <div class="cms-el-dailymotion">
                <div style="position:relative; padding-bottom:56.25%; height:0; overflow:hidden;">
                    <iframe style="width:100%; height:100%; position:absolute; left:0px; top:0px; overflow:hidden"
                            src="https://www.dailymotion.com/embed/video//{{ element.config.dailyUrl.value }}"
                            frameborder="0"
                            type="text/html"
                            width="100%"
                            height="100%">
                    </iframe>
                </div>
            </div>
        {% endblock %}
    </div>
{% endblock %}
```

The URL is parsed here using the twig variable element, which is automatically available in your element's template.

Once more: That's it! Your element is now fully working!
The shop managers can choose your new element in the 'Shopping Experiences' module, they can configure it and even see it being rendered live in the Administration.
After saving and applying this layout to e.g. a category, this element will also be rendered into the Storefront.

## Next steps

There are many possibilities to extend Shopware's CMS.
If you haven't done so already, consider using your element in a cms block.
To learn how to do this, take a look at the guide on [Add custom cms block](add-cms-block).

---

---
url: /docs/guides/plugins/plugins/content/cms/add-cms-element.md
---

# Add CMS Elements

## Overview

A CMS element in Shopware is the smallest content unit in the Shopping Experience (CMS) system. Understanding the hierarchy helps clarify what elements are.

### CMS Hierarchy

* Page - The top-level container (e.g., category page, shop page, product page)
* Section - Horizontal segments within a page (can be single-column or two-column with sidebar)
* Block - Units that usually span an entire row with custom layout and styling
* Slots - A named container inside a block. Each slot represents a designated area that can hold exactly one CMS element
* **Elements - The actual content primitives (text, image, video, product listing, etc.) placed inside slots**

Elements are the "primitives" in the CMS hierarchy. They have no knowledge of their context and contain minimal markup. Elements are always rendered inside slots of their parent blocks.

**Key concept**: Elements provide the actual content, while blocks define the structure and layout. This separation allows different element types to be placed in the same block slot.

> **Learn more**: For a deeper understanding of the CMS architecture, see the [Shopping Experience fundamental guide](../../../../../concepts/commerce/content/shopping-experiences-cms.md).

## Where to find elements

Elements are added to blocks within the Shopping Experience module:

* Navigate to Content → Shopping Experience
* Create a new layout or edit an existing one
* Add a block to your layout (blocks contain slots)
  * Blocks usually contain one or more predefined elements
* Click on the arrow icon on a slot within a block to see available elements
* Select an element to place it in the slot

You can find related element code here:

* Administration: `src/Administration/Resources/app/administration/src/module/sw-cms/elements/`
* Storefront: `src/Storefront/Resources/views/storefront/element/`
* Core: `\Shopware\Core\Content\Cms\SalesChannel\SalesChannelCmsPageLoader::load`

## How to create an element in the Administration

We recommend this structure for CMS elements:

```TEXT
<plugin root>/src/Resources/app/administration/src/
├── main.js
└── module/
    └── sw-cms/
        └── elements/
            └── dailymotion/              (element name)
                ├── index.js
                ├── component/
                │   ├── index.js
                │   ├── cms-el-dailymotion.html.twig
                │   └── cms-el-dailymotion.scss
                ├── config/
                │   ├── index.js
                │   └── cms-el-config-dailymotion.html.twig
                └── preview/
                    ├── index.js
                    ├── cms-el-preview-dailymotion.html.twig
                    └── cms-el-preview-dailymotion.scss
```

### Step 1: Import your element in main.js

```JS
// <plugin root>/src/Resources/app/administration/src/main.js
import './module/sw-cms/elements/dailymotion';
```

### Step 2: Register the element

```JS
// <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/index.js
import './component';
import './config';
import './preview';

Shopware.Service('cmsService').registerCmsElement({
    name: 'dailymotion',
    label: 'cms.elements.dailymotion.label',
    component: 'cms-el-dailymotion',
    configComponent: 'cms-el-config-dailymotion',
    previewComponent: 'cms-el-preview-dailymotion',
    defaultConfig: {
        url: {
            source: 'static',
            value: '',
        },
    },
});
```

| Property         | Description                                                                                |
|------------------|--------------------------------------------------------------------------------------------|
| name             | Technical name of your element                                                             |
| label            | Display name in the UI (preferably as a snippet key)                                       |
| component        | Vue component for rendering the element in the Administration                              |
| configComponent  | Vue component for the configuration panel                                                  |
| previewComponent | Vue component for the element thumbnail in the element selector                            |
| defaultConfig    | Default configuration values (key = config property, value = object with source and value) |
| hidden           | (Optional) Hides the element in the "replace element" modal                                |
| removable        | (Optional) Prevents the element from being removed from a slot via UI                      |

### Step 3: Create the preview component

The preview is shown as a thumbnail when selecting or swapping elements in block slots. You could also display a static image of your final Storefront element here.

```JS
// dailymotion/preview/index.js
Shopware.Component.register('cms-el-preview-dailymotion', {
    template: `
        <div class="cms-el-preview-dailymotion">
            <h3>Dailymotion Embed</h3>
        </div>
    `,
});
```

### Step 4: Create the main component

The main component is displayed in the editor layout. It should provide a good representation of the final Storefront element.

```JS
// dailymotion/component/index.js
Shopware.Component.register('cms-el-dailymotion', {
    template: `
        <iframe
            v-if="element.config.url.value"
            class="cms-el-dailymotion"
            :src="embedUrl"
            width="100%"
            height="480"
        />
        <h3 v-else>Dailymotion</h3>
    `,
    mixins: [
        'cms-element'
    ],
    computed: {
        embedUrl() {
            return `https://www.dailymotion.com/embed/video/${this.element.config.url.value}`;
        },
    },
    created() {
        this.initElementConfig('dailymotion');
    },
});
```

**Key points**:

* The `cms-element` mixin provides common props and data-mapping for config objects
* Use fallback content to avoid invisible elements in the editor (for example when missing an `iframe` or `img` `src`)

### Step 5: Create the configuration component

This component will be displayed in a modal and should provide form fields for all options defined in Step 2 (`defaultConfig`).

```JS
// dailymotion/config/index.js
Shopware.Component.register('cms-el-config-dailymotion', {
    template: `<div class="cms-el-config-dailymotion">
        <mt-text-field
            v-model="element.config.url.value"
            label="Dailymotion video ID"
            placeholder="Enter Dailymotion video ID..."
        />
    </div>`,
    mixins: [
        'cms-element'
    ],
    created() {
        this.initElementConfig('dailymotion');
    },
});
```

**Key points**:

* The `cms-element` mixin provides common props and data-mapping for config objects
* Use [Shopware Meteor components](https://shopware.design/meteor-components/) for a consistent UI

### Step 6: Inheritance support for elements

Inheritance in the CMS provides fine-grained control over how content is customized between the base layout and content pages (category, product, landing page, ..) they are assigned to.
Similar to how product variants work, content managers can choose to either inherit the content from the base layout or override it with custom content for each page.

By default, configuration will be inherited unless explicitly overridden though the UI may not be as clear.

For an improved user experience when working with inherited fields, we provide a [wrapper component](https://github.com/shopware/shopware/blob/trunk/src/Administration/Resources/app/administration/src/module/sw-cms/component/sw-cms-inherit-wrapper/index.ts) that handles removing and restoring inherited values and displaying proper UI states. To use this is in your own elements, you can add the `sw-cms-inherit-wrapper` component to individual fields in your element.

```VUE
<!-- src/module/sw-cms/elements/text/config/sw-cms-el-config-text.html.twig -->
<sw-cms-inherit-wrapper
    field="verticalAlign"
    :element="element"
    :label="$t('sw-cms.elements.general.config.label.verticalAlign')"
>
    <template #default="{ isInherited }">
        <mt-select
            v-model:model-value="element.config.verticalAlign.value"
            :placeholder="$t('sw-cms.elements.general.config.label.verticalAlign')"
            :disabled="isInherited"
        />
    </template>
</sw-cms-inherit-wrapper>
```

You can find more references in the standard CMS elements located in `src/Administration/Resources/app/administration/src/module/sw-cms/elements/`.

## How to Create an element in the Storefront

The Storefront template defines how your element appears on the actual storefront. It is expected to be located in the directory `src/Resources/views/storefront/element`. In there, a twig template file has to follow this naming convention:

* **Prefix**: `cms-element-`
* **Technical name**: `dailymotion` (the `name` property defined in Step 2)
* **Extension**: `.html.twig`

**Shopware is expecting the prefix as part of the full filename.**

Full example: `cms-element-dailymotion.html.twig`

### Basic template

You can create your own elements or extend and reuse existing ones. Don't forget to clear the Storefront cache after adding new templates.

```TWIG
{# <plugin root>/src/Resources/views/storefront/element/cms-element-dailymotion.html.twig #}

<div class="cms-element-dailymotion">
    <iframe
        src="https://www.dailymotion.com/embed/video/{{ element.config.url.value }}"
        frameborder="0"
        type="text/html"
        width="100%"
        height="480"
    />
</div>
```

The `element` is automatically passed to the template and contains meta data and configuration values. See the `CmsSlotDefinition.php` for a full overview.

## Next steps

There are many possibilities to extend Shopware's CMS.
If you haven't done so already, consider using your element in a cms block.
To learn how to do this, take a look at the guide on [Add custom CMS block](add-cms-block.md).

---

---
url: /docs/guides/plugins/plugins/storefront/advanced/add-cookie-to-manager.md
---

# Add Cookie to Manager

## Overview

Since the GDPR was introduced, every website has to be shipped with some sort of a cookie consent manager. This is also the case for Shopware 6 of course, which comes with a cookie consent manager by default. In this guide you will learn how you can add your own cookies to the cookie consent manager of Shopware 6.

::: info
For a comprehensive understanding of Shopware's cookie consent system, see the [Cookie Consent Management Concept](../../../../../concepts/commerce/content/cookie-consent-management.md).
:::

## Prerequisites

Review the [Plugin base guide](../../plugin-base-guide.md) and create a running plugin. Also, you will need to know how to [create your own service](../../services/add-custom-service.md) and [subscribe to an event](../../framework/event/listening-to-events.md), so you might want to take a look at those guides as well.

## Extend the cookie consent manager

Adding custom cookies requires you to listen to the `CookieGroupCollectEvent` and add your custom cookies to the collection.

::: tip
It is recommended to use an event listener if you're listening to a single event. If you need to react to multiple events, an event subscriber is the better choice.
:::

### Registering your event listener

Start with creating the `services.php` and registering your event listener.

```php
// <plugin root>/src/Resources/config/services.php
<?php declare(strict_types=1);

use PluginName\Listener\CookieListener;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(CookieListener::class)
        ->tag('kernel.event_listener', ['event' => 'Shopware\Core\Content\Cookie\Event\CookieGroupCollectEvent']);
};
```

In the next step we'll create the actual listener class.

### Creating the listener

We need to create a class called `CookieListener` with an `__invoke` method. This method will be executed once the `CookieGroupCollectEvent` is dispatched.

The event object that is passed to our listener method contains the cookie groups collection, which we can use to add our custom cookies.

::: warning
Since Shopware 6.7.3.0, cookies use structured objects (`CookieEntry` and `CookieGroup`) instead of arrays for better type safety and consistency. The array format is deprecated.
:::

Let's have a look at an example:

```php
// <plugin root>/src/Listener/CookieListener.php
<?php declare(strict_types=1);

namespace PluginName\Listener;

use Shopware\Core\Content\Cookie\Event\CookieGroupCollectEvent;
use Shopware\Core\Content\Cookie\Service\CookieProvider;
use Shopware\Core\Content\Cookie\Struct\CookieEntry;
use Shopware\Core\Content\Cookie\Struct\CookieEntryCollection;

class CookieListener
{
    public function __invoke(CookieGroupCollectEvent $event): void
    {
        $comfortFeaturesCookieGroup = $event->cookieGroupCollection->get(CookieProvider::SNIPPET_NAME_COOKIE_GROUP_COMFORT_FEATURES);
        if (!$comfortFeaturesCookieGroup) {
            return;
        }

        $entries = $comfortFeaturesCookieGroup->getEntries();
        if ($entries === null) {
            $entries = new CookieEntryCollection();
            $comfortFeaturesCookieGroup->setEntries($entries);
        }

        $cookieEntry = new CookieEntry('my-cookie-key');
        $cookieEntry->name = 'cookie.myCookieName';
        $cookieEntry->value = '1';
        $cookieEntry->expiration = 30;

        $entries->add($cookieEntry);
    }
}
```

This will add your cookie to the existing "Comfort Features" group in the cookie consent manager.

And that's basically it already. After loading your Storefront, you should now see your new cookie in the cookie consent manager.

## Parameter Reference

For a complete list of available parameters and their types, refer to the source code:

* [`CookieEntry`](https://github.com/shopware/shopware/blob/trunk/src/Core/Content/Cookie/Struct/CookieEntry.php) - Individual cookie definition
* [`CookieGroup`](https://github.com/shopware/shopware/blob/trunk/src/Core/Content/Cookie/Struct/CookieGroup.php) - Cookie group definition

::: info
Cookie groups should not have the `cookie`, `value`, `expiration`, or `isRequired` parameters. These only apply to individual `CookieEntry` objects within the group's `entries`.
:::

## Migrating from CookieProviderInterface (Shopware 6.7.2 and earlier)

If you are upgrading from an older version, you might have used the `CookieProviderInterface` to add custom cookies. This interface is now deprecated and should be replaced with the `CookieGroupCollectEvent`.

For backward compatibility, you can still use the `CookieProviderInterface` to provide cookies in the old array syntax. However, it is highly recommended to use the new event-based system to provide the new object structure.

## Cookie Configuration Changes and Re-Consent

Since Shopware 6.7.3.0, cookie configurations include a hash that tracks changes. When you modify cookie configurations through your plugin (add/remove/change cookies), the hash changes automatically, triggering a re-consent flow for users.

This helps maintain transparency by re-prompting users when cookie handling changes, supporting GDPR compliance requirements. The hash is automatically calculated from all cookie configurations provided by the `CookieProvider`.

::: info
**Hash Storage Format**: The configuration hash is stored in the browser's `cookie-config-hash` cookie as an object where the language ID is the key and the cookie hash is the value, for example: `{"019ada128cfb711aa7a0d00f476d5961":"998cdcc090e92b3ecdd057241d0fd01f"}`. This enables per-language consent tracking. Since cookies are stored per domain by the browser, installations using different domains for different languages don't encounter tracking conflicts. The language ID is specifically used when multiple languages are served from the same domain.
:::

::: info
While this feature helps with GDPR compliance, shop owners are responsible for ensuring their overall cookie usage, privacy policies, and data handling practices comply with GDPR and other applicable regulations.
:::

### How it works

1. Your plugin adds/modifies cookies via the `CookieGroupCollectEvent`
2. Shopware calculates a hash of the entire cookie configuration
3. The hash is stored in the user's browser as an object where the language ID is the key and the hash is the value (e.g., `{"019ada128cfb711aa7a0d00f476d5961":"998cdcc090e92b3ecdd057241d0fd01f"}`)
4. On the next visit, if the hash differs for the current language, the consent banner appears again
5. Users are informed about changes and can make new choices

This automatic re-consent mechanism helps shop owners maintain transparency about cookie changes.

::: info
The configuration hash is exposed via the Store API endpoint `/store-api/cookie/groups`. For API documentation, see [Fetch all cookie groups](https://shopware.stoplight.io/docs/store-api/f9c70be044a15-fetch-all-cookie-groups).
:::

## Video Platform Cookies

YouTube and Vimeo cookies are now handled separately in Shopware's cookie management. If you're adding video functionality to your plugin, ensure you register the appropriate cookie for your video platform or reuse existing ones.

## Next steps

Those changes will mainly just show your new cookies in the cookie consent manager, but without much function. Head over to our guide about [Reacting to cookie consent changes](reacting-to-cookie-consent-changes) to see how you can implement your custom logic once your cookie got accepted or declined.

---

---
url: /docs/v6.5/guides/plugins/plugins/storefront/add-cookie-to-manager.md
---

# Add Cookie to Manager

## Overview

Since the GDPR was introduced, every website has to be shipped with some sort of a cookie consent manager. This is also the case for Shopware 6 of course, which comes with a cookie consent manager by default. In this guide you will learn how you can add your own cookies to the cookie consent manager of Shopware 6.

## Prerequisites

This guide is built upon the [Plugin base guide](../plugin-base-guide), so have a look at that first if you're lacking a running plugin. Also you will have to know how to [create your own service](../plugin-fundamentals/add-custom-service) and [decorations](../plugin-fundamentals/adjusting-service#decorating-the-service), so you might want to have a look at those guides as well.

## Extend the cookie consent manager

Adding custom cookies basically requires you to decorate a service, the `CookieProvider` to be precise. Neither decorations, nor adding a service via a `services.xml` is explained here, so make sure to have a look at the previously mentioned guides first, if you're lacking this knowledge.

### Registering your decoration

Start with creating the `services.xml` entry and with decorating the `CookieProviderInterface`. The `CookieProvider` service was already built before we decided to use abstract classes for decorations, so don't be confused here.

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
       <service id="PluginName\Framework\Cookie\CustomCookieProvider"
                decorates="Shopware\Storefront\Framework\Cookie\CookieProviderInterface">
             <argument type="service" 
                       id="PluginName\Framework\Cookie\CustomCookieProvider.inner" />
         </service>
    </services>
</container>
```

In the next step we'll create the actual decorated class.

### Creating the decorated service

We need to create a class called `CustomCookieProvider`, which implements the `CookieProviderInterface`. Our constructor parameter is the original `CookieProviderInterface` instance, which we need to call to get all other cookies as well.

The interface mentioned above requires you to implement a method called `getCookieGroups`, which has to return an array of cookie groups and their respective cookies. You need to call the original method now, receive the default cookie groups and then merge your custom group, if there's any, and your custom cookies into it.

Let's have a look at an example:

```php
// <plugin root>/src/Framework/Cookie/CustomCookieProvider.php
<?php declare(strict_types=1);

namespace PluginName\Framework\Cookie;

use Shopware\Storefront\Framework\Cookie\CookieProviderInterface;

class CustomCookieProvider implements CookieProviderInterface {

    private CookieProviderInterface $originalService;

    public function __construct(CookieProviderInterface $service)
    {
        $this->originalService = $service;
    }

    private const singleCookie = [
        'snippet_name' => 'cookie.name',
        'snippet_description' => 'cookie.description ',
        'cookie' => 'cookie-key',
        'value' => 'cookie value',
        'expiration' => '30'
    ];

    // cookies can also be provided as a group
    private const cookieGroup = [
        'snippet_name' => 'cookie.group_name',
        'snippet_description' => 'cookie.group_description ',
        'entries' => [
            [
                'snippet_name' => 'cookie.first_child_name',
                'cookie' => 'cookie-key-1',
                'value'=> 'cookie value',
                'expiration' => '30'
            ],
            [
                'snippet_name' => 'cookie.second_child_name',
                'cookie' => 'cookie-key-2',
                'value'=> 'cookie value',
                'expiration' => '60'
            ]
        ],
    ];

    public function getCookieGroups(): array
    {
        return array_merge(
            $this->originalService->getCookieGroups(),
            [
                self::cookieGroup,
                self::singleCookie
            ]
        );
    }
}
```

As already mentioned, we're overwriting the method `getCookieGroups` and in there we're calling the original method first. We then proceed to merge our own custom group into it, as well as a custom cookie.

This will eventually lead to a new group being created, containing two new cookies, as well as a new cookie without a group.

And that's basically it already. After loading your Storefront, you should now see your new cookies and the cookie-group.

### Cookie array keys

Here's a list of attributes, that you can apply to a cookie array:

| Attribute | Data type | Required | Description |
| :--- | :--- | :--- | :--- |
| snippet\_name | String | Yes | Key of a snippet containing the display name of a cookie or cookie group. |
| snippet\_description | String | No | Key of a snippet containing a short description of a cookie or cookie group. |
| cookie | String | Yes | The internal cookie name used to save the cookie. |
| value | String | No | If unset, the cookie will not be updated (set active or inactive) by Shopware, but passed to the update event only. |
| expiration | String | No | Cookie lifetime in days. **If unset, the cookie expires with the session**. |
| entries | Array | No | An array of cookie objects. Used to create grouped cookies. Nested groups are not supported. If using this, **the group itself should not have the attributes** ***cookie*****,** ***value*** **and** ***expiration*****.**. |

## Next steps

Those changes will mainly just show your new cookies in the cookie consent manager, but without much function. Head over to our guide about [Reacting to cookie consent changes](reacting-to-cookie-consent-changes) to see how you can implement your custom logic once your cookie got accepted or declined.

---

---
url: /docs/v6.6/guides/plugins/plugins/storefront/add-cookie-to-manager.md
---

# Add Cookie to Manager

## Overview

Since the GDPR was introduced, every website has to be shipped with some sort of a cookie consent manager. This is also the case for Shopware 6 of course, which comes with a cookie consent manager by default. In this guide you will learn how you can add your own cookies to the cookie consent manager of Shopware 6.

## Prerequisites

This guide is built upon the [Plugin base guide](../plugin-base-guide), so have a look at that first if you're lacking a running plugin. Also you will have to know how to [create your own service](../plugin-fundamentals/add-custom-service) and [decorations](../plugin-fundamentals/adjusting-service#decorating-the-service), so you might want to have a look at those guides as well.

## Extend the cookie consent manager

Adding custom cookies basically requires you to decorate a service, the `CookieProvider` to be precise. Neither decorations, nor adding a service via a `services.xml` is explained here, so make sure to have a look at the previously mentioned guides first, if you're lacking this knowledge.

### Registering your decoration

Start with creating the `services.xml` entry and with decorating the `CookieProviderInterface`. The `CookieProvider` service was already built before we decided to use abstract classes for decorations, so don't be confused here.

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
       <service id="PluginName\Framework\Cookie\CustomCookieProvider"
                decorates="Shopware\Storefront\Framework\Cookie\CookieProviderInterface">
             <argument type="service" 
                       id="PluginName\Framework\Cookie\CustomCookieProvider.inner" />
         </service>
    </services>
</container>
```

In the next step we'll create the actual decorated class.

### Creating the decorated service

We need to create a class called `CustomCookieProvider`, which implements the `CookieProviderInterface`. Our constructor parameter is the original `CookieProviderInterface` instance, which we need to call to get all other cookies as well.

The interface mentioned above requires you to implement a method called `getCookieGroups`, which has to return an array of cookie groups and their respective cookies. You need to call the original method now, receive the default cookie groups and then merge your custom group, if there's any, and your custom cookies into it.

Let's have a look at an example:

```php
// <plugin root>/src/Framework/Cookie/CustomCookieProvider.php
<?php declare(strict_types=1);

namespace PluginName\Framework\Cookie;

use Shopware\Storefront\Framework\Cookie\CookieProviderInterface;

class CustomCookieProvider implements CookieProviderInterface {

    private CookieProviderInterface $originalService;

    public function __construct(CookieProviderInterface $service)
    {
        $this->originalService = $service;
    }

    private const singleCookie = [
        'snippet_name' => 'cookie.name',
        'snippet_description' => 'cookie.description ',
        'cookie' => 'cookie-key',
        'value' => 'cookie value',
        'expiration' => '30'
    ];

    // cookies can also be provided as a group
    private const cookieGroup = [
        'snippet_name' => 'cookie.group_name',
        'snippet_description' => 'cookie.group_description ',
        'entries' => [
            [
                'snippet_name' => 'cookie.first_child_name',
                'cookie' => 'cookie-key-1',
                'value'=> 'cookie value',
                'expiration' => '30'
            ],
            [
                'snippet_name' => 'cookie.second_child_name',
                'cookie' => 'cookie-key-2',
                'value'=> 'cookie value',
                'expiration' => '60'
            ]
        ],
    ];

    public function getCookieGroups(): array
    {
        return array_merge(
            $this->originalService->getCookieGroups(),
            [
                self::cookieGroup,
                self::singleCookie
            ]
        );
    }
}
```

As already mentioned, we're overwriting the method `getCookieGroups` and in there we're calling the original method first. We then proceed to merge our own custom group into it, as well as a custom cookie.

This will eventually lead to a new group being created, containing two new cookies, as well as a new cookie without a group.

And that's basically it already. After loading your Storefront, you should now see your new cookies and the cookie-group.

### Cookie array keys

Here's a list of attributes, that you can apply to a cookie array:

| Attribute | Data type | Required | Description |
| :--- | :--- | :--- | :--- |
| snippet\_name | String | Yes | Key of a snippet containing the display name of a cookie or cookie group. |
| snippet\_description | String | No | Key of a snippet containing a short description of a cookie or cookie group. |
| cookie | String | Yes | The internal cookie name used to save the cookie. |
| value | String | No | If unset, the cookie will not be updated (set active or inactive) by Shopware, but passed to the update event only. |
| expiration | String | No | Cookie lifetime in days. **If unset, the cookie expires with the session**. |
| entries | Array | No | An array of cookie objects. Used to create grouped cookies. Nested groups are not supported. If using this, **the group itself should not have the attributes** ***cookie*****,** ***value*** **and** ***expiration*****.**. |

## Next steps

Those changes will mainly just show your new cookies in the cookie consent manager, but without much function. Head over to our guide about [Reacting to cookie consent changes](reacting-to-cookie-consent-changes) to see how you can implement your custom logic once your cookie got accepted or declined.

---

---
url: /docs/v6.5/guides/plugins/apps/storefront/cookies-with-apps.md
---

# Add cookies to the consent manager

## Prerequisites

You should be familiar with the concept of apps.

## Create a single cookie

To add new cookies to the cookie consent manager, you can add a `cookies` section to your `manifest.xml`. Inside this section, you can add new `cookie` elements, as shown in the following example. Note that you don't need a `setup` section in your `manifest.xml` since extending the Storefront doesn't need a registration nor an own server to run.

```xml
// manifest.xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        <name>ExampleAppWithCookies</name>
        <version>1.0.0</version>
        <!-- other meta data goes here -->
    </meta>
    <cookies>
        <cookie>
            <cookie>my-cookie</cookie>
            <snippet-name>example-app-with-cookies.my-cookie.name</snippet-name>
            <snippet-description>example-app-with-cookies.my-cookie.description</snippet-description>
            <value>a static value for the cookie</value>
            <expiration>1</expiration>
        </cookie>
    </cookies>
</manifest>
```

Cookie elements can be configured by adding the following child elements:

* `cookie` (required): The technical name of the cookie. The value is used to store the cookie in the customer's cookie jar.
* `snippet-name` (required): A string that represents the label of the cookie in the cookie consent manager. To provide translations this should be the key of a Storefront snippet.
* `value` (optional): A fixed value that is set as the cookie's value when the customer accepts your cookie. **If unset, the cookie will not be updated (set active or inactive) by Shopware, but passed to the update event.**
* `expiration` (optional): Cookie lifetime in days. **If unset, the cookie expires with the session.**
* `snippet-description` (optional): A string that represents the description of the cookie in the cookie consent manager. To provide translations, this should be the key of a Storefront snippet.

For a complete reference of the structure of the manifest file, take a look at the [Manifest reference](../../../../resources/references/app-reference/manifest-reference).

## Create a cookie group

When adding multiple cookies through your app it may become handy to group them. This makes it possible for the customer to accept all of your cookies at once and additionally enhances the readability of the cookie consent manager.

To add a cookie group, you can add a `groups` section within your `cookies` section in your `manifest.xml`. In the following example, we use the cookie that we created in the previous section but display it in a cookie group:

```xml
// manifest.xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        <name>ExampleAppWithCookies</name>
        <version>1.0.0</version>
        <!-- other meta data goes here -->
    </meta>
    <cookies>
        <group>
            <snippet-name>example-app-with-cookies.cookie-group.name</snippet-name>
            <snippet-description>example-app-with-cookies.cookie-group.description</snippet-description>
            <entries>
                <cookie>
                    <cookie>my-cookie</cookie>
                    <snippet-name>example-app-with-cookies.my-cookie.name</snippet-name>
                    <snippet-description>example-app-with-cookies.my-cookie.description</snippet-description>
                    <value>a static value for the cookie</value>
                    <expiration>1</expiration>
                </cookie>
            </entries>
        </group>
    </cookies>
</manifest>
```

A `group` element consists of three child elements to configure the cookie group. Here is a description of all of them:

* `snippet-name` (required): A string that represents the label of the cookie group in the cookie consent manager. To provide translations this should be the key of a Storefront snippet.
* `entries` (required): Contains the grouped cookies. It is a collection of `cookie` elements described in the previous section.
* `snippet-description` (optional): A string that represents the description of the cookie group in the cookie consent manager. To provide translations this should be the key of a Storefront snippet.

For a complete reference of the structure of the manifest file, take a look at the [Manifest reference](../../../../resources/references/app-reference/manifest-reference).

## Snippet handling

As already mentioned in the previous sections, both the `cookie` and the `group` elements can contain `snippet-name` and `snippet-description` child elements. Although their values can be strings that will be displayed in the Storefront, the preferred way to set up cookie names and descriptions is to provide Storefront snippets. It gives you and the shop owner the possibility to add translations for your cookie's name and description.

If you are not familiar with setting up Storefront snippets, please refer to our snippet guide.

## Reacting to cookie consent changes

As described in the previous section, `cookie` elements without a `value` element will not be set automatically. Instead, you have to react to cookie consent changes within your JavaScript. Find out how to [respond to cookie consent changes](../../../plugins/plugins/storefront/reacting-to-cookie-consent-changes).

---

---
url: /docs/v6.6/guides/plugins/apps/storefront/cookies-with-apps.md
---

# Add cookies to the consent manager

## Prerequisites

You should be familiar with the concept of apps.

## Create a single cookie

To add new cookies to the cookie consent manager, you can add a `cookies` section to your `manifest.xml`. Inside this section, you can add new `cookie` elements, as shown in the following example. Note that you don't need a `setup` section in your `manifest.xml` since extending the Storefront doesn't need a registration nor an own server to run.

::: code-group

```xml [manifest.xml]
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        <name>ExampleAppWithCookies</name>
        <version>1.0.0</version>
        <!-- other meta data goes here -->
    </meta>
    <cookies>
        <cookie>
            <cookie>my-cookie</cookie>
            <snippet-name>example-app-with-cookies.my-cookie.name</snippet-name>
            <snippet-description>example-app-with-cookies.my-cookie.description</snippet-description>
            <value>a static value for the cookie</value>
            <expiration>1</expiration>
        </cookie>
    </cookies>
</manifest>
```

:::

Cookie elements can be configured by adding the following child elements:

* `cookie` (required): The technical name of the cookie. The value is used to store the cookie in the customer's cookie jar.
* `snippet-name` (required): A string that represents the label of the cookie in the cookie consent manager. To provide translations this should be the key of a Storefront snippet.
* `value` (optional): A fixed value that is set as the cookie's value when the customer accepts your cookie. **If unset, the cookie will not be updated (set active or inactive) by Shopware, but passed to the update event.**
* `expiration` (optional): Cookie lifetime in days. **If unset, the cookie expires with the session.**
* `snippet-description` (optional): A string that represents the description of the cookie in the cookie consent manager. To provide translations, this should be the key of a Storefront snippet.

For a complete reference of the structure of the manifest file, take a look at the [Manifest reference](../../../../resources/references/app-reference/manifest-reference).

## Create a cookie group

When adding multiple cookies through your app it may become handy to group them. This makes it possible for the customer to accept all of your cookies at once and additionally enhances the readability of the cookie consent manager.

To add a cookie group, you can add a `groups` section within your `cookies` section in your `manifest.xml`. In the following example, we use the cookie that we created in the previous section but display it in a cookie group:

::: code-group

```xml [manifest.xml]
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        <name>ExampleAppWithCookies</name>
        <version>1.0.0</version>
        <!-- other meta data goes here -->
    </meta>
    <cookies>
        <group>
            <snippet-name>example-app-with-cookies.cookie-group.name</snippet-name>
            <snippet-description>example-app-with-cookies.cookie-group.description</snippet-description>
            <entries>
                <cookie>
                    <cookie>my-cookie</cookie>
                    <snippet-name>example-app-with-cookies.my-cookie.name</snippet-name>
                    <snippet-description>example-app-with-cookies.my-cookie.description</snippet-description>
                    <value>a static value for the cookie</value>
                    <expiration>1</expiration>
                </cookie>
            </entries>
        </group>
    </cookies>
</manifest>
```

:::

A `group` element consists of three child elements to configure the cookie group. Here is a description of all of them:

* `snippet-name` (required): A string that represents the label of the cookie group in the cookie consent manager. To provide translations this should be the key of a Storefront snippet.
* `entries` (required): Contains the grouped cookies. It is a collection of `cookie` elements described in the previous section.
* `snippet-description` (optional): A string that represents the description of the cookie group in the cookie consent manager. To provide translations this should be the key of a Storefront snippet.

For a complete reference of the structure of the manifest file, take a look at the [Manifest reference](../../../../resources/references/app-reference/manifest-reference).

## Snippet handling

As already mentioned in the previous sections, both the `cookie` and the `group` elements can contain `snippet-name` and `snippet-description` child elements. Although their values can be strings that will be displayed in the Storefront, the preferred way to set up cookie names and descriptions is to provide Storefront snippets. It gives you and the shop owner the possibility to add translations for your cookie's name and description.

If you are not familiar with setting up Storefront snippets, please refer to our snippet guide.

## Reacting to cookie consent changes

As described in the previous section, `cookie` elements without a `value` element will not be set automatically. Instead, you have to react to cookie consent changes within your JavaScript. Find out how to [respond to cookie consent changes](../../../plugins/plugins/storefront/reacting-to-cookie-consent-changes).

---

---
url: /docs/guides/plugins/apps/storefront/cookies-with-apps.md
---

# Add Cookies to the Consent Manager

## Overview

Before proceeding, review the [App Base Guide](../app-base-guide.md).

The [Cookie Consent Management Concept](../../../../concepts/commerce/content/cookie-consent-management.md) provides a comprehensive guide to Shopware's cookie consent system.

## Create a single cookie

To add new cookies to the cookie consent manager, you can add a `cookies` section to your `manifest.xml`. Inside this section, you can add new `cookie` elements, as shown in the following example. Note that you don't need a `setup` section in your `manifest.xml` since extending the Storefront doesn't need a registration nor an own server to run.

```XML
<?XML version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/refs/tags/v6.7.4.0/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        <name>ExampleAppWithCookies</name>
        <version>1.0.0</version>
        <!-- other meta data goes here -->
    </meta>
    <cookies>
        <cookie>
            <cookie>my-cookie</cookie>
            <snippet-name>example-app-with-cookies.my-cookie.name</snippet-name>
            <snippet-description>example-app-with-cookies.my-cookie.description</snippet-description>
            <value>a static value for the cookie</value>
            <expiration>1</expiration>
        </cookie>
    </cookies>
</manifest>
```

Cookie elements can be configured by adding the following child elements:

* `cookie` (required): The technical name of the cookie. The value is used to store the cookie in the customer's cookie jar.
* `snippet-name` (required): A string that represents the label of the cookie in the cookie consent manager. To provide translations this should be the key of a Storefront snippet.
* `value` (optional): A fixed value that is set as the cookie's value when the customer accepts your cookie. **If unset, the cookie will not be updated (set active or inactive) by Shopware, but passed to the update event.**
* `expiration` (optional): Cookie lifetime in days. **If unset, the cookie expires with the session.**
* `snippet-description` (optional): A string that represents the description of the cookie in the cookie consent manager. To provide translations, this should be the key of a Storefront snippet.

For a complete reference of the structure of the manifest file, take a look at the [Manifest reference](../../../../resources/references/app-reference/manifest-reference.md).

## Create a cookie group

When adding multiple cookies through your app, it may become handy to group them. This makes it possible for the customer to accept all of your cookies at once and additionally enhances the readability of the cookie consent manager.

To add a cookie group, you can add a `groups` section within your `cookies` section in your `manifest.xml`. In the following example, we use the cookie that we created in the previous section but display it in a cookie group:

```XML
<?XML version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/refs/tags/v6.7.4.0/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        <name>ExampleAppWithCookies</name>
        <version>1.0.0</version>
        <!-- other meta data goes here -->
    </meta>
    <cookies>
        <group>
            <snippet-name>example-app-with-cookies.cookie-group.name</snippet-name>
            <snippet-description>example-app-with-cookies.cookie-group.description</snippet-description>
            <entries>
                <cookie>
                    <cookie>my-cookie</cookie>
                    <snippet-name>example-app-with-cookies.my-cookie.name</snippet-name>
                    <snippet-description>example-app-with-cookies.my-cookie.description</snippet-description>
                    <value>a static value for the cookie</value>
                    <expiration>1</expiration>
                </cookie>
            </entries>
        </group>
    </cookies>
</manifest>
```

A `group` element consists of three child elements to configure the cookie group. Here is a description of all of them:

* `snippet-name` (required): A string that represents the label of the cookie group in the cookie consent manager. To provide translations this should be the key of a Storefront snippet.
* `entries` (required): Contains the grouped cookies. It is a collection of `cookie` elements described in the previous section.
* `snippet-description` (optional): A string that represents the description of the cookie group in the cookie consent manager. To provide translations this should be the key of a Storefront snippet.

The [Manifest reference](../../../../resources/references/app-reference/manifest-reference.md) provides comprehensive information about manifest file structure.

## Assigning Cookies to Standard Cookie Groups

You can assign your app's cookies to Shopware's standard cookie groups by using one of the built-in snippet names in your `manifest.xml`: `cookie.groupRequired`, `cookie.groupComfortFeatures`, `cookie.groupStatistical`, and `cookie.groupMarketing`.

The following example shows how to assign cookies to the **Marketing group**:

```XML
<?XML version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/refs/tags/v6.7.4.0/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        <name>MyApp</name>
        <label>My App</label>
        <version>1.0.0</version>
        <author>Your Name</author>
    </meta>

    <cookies>
        <!-- Marketing/Tracking cookies go to Marketing group -->
        <group>
            <snippet-name>cookie.groupMarketing</snippet-name>
            <entries>
                <cookie>
                    <cookie>myapp_conversion_tracking</cookie>
                    <snippet-name>myapp.cookie.conversionTracking</snippet-name>
                    <snippet-description>myapp.cookie.conversionTrackingDescription</snippet-description>
                    <value>1</value>
                    <expiration>90</expiration>
                </cookie>
                <cookie>
                    <cookie>myapp_ad_targeting</cookie>
                    <snippet-name>myapp.cookie.adTargeting</snippet-name>
                    <value>1</value>
                    <expiration>365</expiration>
                </cookie>
            </entries>
        </group>
    </cookies>
</manifest>
```

## Snippet handling

As already mentioned in the previous sections, both the `cookie` and the `group` elements can contain `snippet-name` and `snippet-description` child elements. Although their values can be strings that will be displayed in the Storefront, the preferred way to set up cookie names and descriptions is to provide Storefront snippets. It gives you and the shop owner the possibility to add translations for your cookie's name and description.

To learn how to set up Storefront snippets, refer to the snippet guide.

## Automatic Configuration Change Detection

Any changes made to the cookie definitions in your app's `manifest.xml` are automatically detected by Shopware's consent system. This will trigger a re-consent flow for users, ensuring they are always prompted about the latest cookie settings.

This process is handled by a configuration hash mechanism, which is explained in detail in the [Cookie Consent Management Concept](../../../../concepts/commerce/content/cookie-consent-management.md#configuration-hash-mechanism).

## Reacting to cookie consent changes

As described in the previous section, `cookie` elements without a `value` element will not be set automatically. Instead, you have to react to cookie consent changes within your JavaScript. Find out how to [respond to cookie consent changes](../../../plugins/plugins/storefront/advanced/reacting-to-cookie-consent-changes.md).

---

---
url: /docs/guides/plugins/apps/administration/add-custom-action-button.md
---

# Add custom action button

## Overview

This guide covers how to add custom action buttons to the Shopware Administration using the manifest file. This works for simple applications; however, to write more advanced applications, the [Meteor Admin SDK](meteor-admin-sdk.md) is recommended. It has many more features and is more flexible.

For further details and guidance on custom action buttons, refer to the documentation provided on the Meteor Admin SDK's [action button](https://developer.shopware.com/resources/admin-extension-sdk/api-reference/ui/actionButton.html) section.

One extension possibility in the Administration is the ability to add custom action buttons to the smartbar. For now, you can add them in the smartbar of detail and list views:

![Custom action buttons in the Administration](../../../../assets/custom-buttons.png)

To get those buttons, you start in the `admin` section of your manifest file. There you can define `<action-button>` elements in order to add your button, as seen as below:

::: code-group

```xml [manifest.xml]
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        ...
    </meta>
    <admin>
        <action-button action="setPromotion" entity="promotion" view="detail" url="https://example.com/promotion/set-promotion">
            <label>set Promotion</label>
        </action-button>
        <action-button action="deletePromotion" entity="promotion" view="detail" url="https://example.com/promotion/delete-promotion">
            <label>delete Promotion</label>
        </action-button>
        <action-button action="restockProduct" entity="product" view="list" url="https://example.com/restock">
            <label>restock</label>
        </action-button>
    </admin>
</manifest>
```

:::

For a complete reference of the structure of the manifest file take a look at the [Manifest reference](../../../../resources/references/app-reference/manifest-reference.md).

An action button must have the following attributes:

* `action`: Unique identifier for the action, can be set freely.
* `entity`: Here you define which entity you're working on.
* `view`: `detail`or `list`; to set the view the button should be added to. Currently, you can choose between detail and listing view.

When the user clicks on the action button your app receives a request similar to the one generated by a [webhook](../lifecycle/webhook.md).
The main difference is that it contains the name of the entity and an array of ids that the user selected (or an array containing only a single id if the action button was executed on a detail page).

A sample payload may look like the following:

```json
{
  "source":{
    "url":"http:\/\/localhost:8000",
    "appVersion":"1.0.0",
    "shopId":"F0nWInXj5Xyr"
  },
  "data":{
    "ids":[
      "2132f284f71f437c9da71863d408882f"
    ],
    "entity":"product",
    "action":"restockProduct"
  },
  "meta":{
    "timestamp":1592403610,
    "reference":"9e968471797b4f29be3e3cf09f52d8da",
    "language":"2fbb5fe2e29a4d70aa5854ce7ce3e20b"
  }
}
```

```php
// injected or build by yourself
$shopResolver = new ShopResolver($repository);
$contextResolver = new ContextResolver();

$shop = $shopResolver->resolveShop($serverRequest);
$actionButton = $contextResolver->assembleActionButton($serverRequest, $shop);
```

```php
use Shopware\App\SDK\Context\ActionButton\ActionButtonAction;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\AsController;
use Symfony\Component\Routing\Attribute\Route;
use Psr\Http\Message\ResponseInterface;

#[AsController]
class ActionButtonController {
    #[Route('/action/product/detail')]
    public function handle(ActionButtonAction $button): ResponseInterface
    {
        // handle button
        
        return ActionButtonResponse::notification('success', 'Success message');
    }
}
```

::: info
Starting from Shopware version 6.4.1.0, the current shopware version will be sent as a `sw-version` header.
:::

Again you can verify the authenticity of the incoming request, like with [webhooks](../lifecycle/webhook.md), by checking the `shopware-shop-signature`. It also contains the SHA256 HMAC of the request body, that is signed with the secret your app assigned the shop during the [registration](../lifecycle/app-registration-setup.md#setup).

## Providing feedback in the Administration

::: info
This feature was added in Shopware 6.4.3.0, previous versions will ignore the response content.
:::

::: info
Starting from Shopware version 6.4.8.0, the requests of the [tab](#opening-a-new-tab-for-the-user) and [custom modal](#open-a-custom-modal) have the following additional query parameters:

* `shop-id`
* `shop-url`
* `timestamp`
* `sw-context-language`
* `sw-user-language`
* `shopware-shop-signature`

You **must** make sure to verify the authenticity of the incoming request by checking the `shopware-shop-signature`, which is a hash of the request's query part, signed with the shop's secret key.
:::

If you want to trigger an action inside the Administration upon completing the action, the app should return a response with a valid body and the header `shopware-app-signature` containing the SHA256 HMAC of the whole response body signed with the app secret.
If you do not need to trigger any actions, a response with an empty body is also always valid.

### Opening a new tab for the user

Examples response body:
To open a new tab in the user browser you can use the `openNewTab` action type. You need to pass the url that should be opened as the `redirectUrl` property inside the payload.

```txt
Content-Type: application/json

{
  "actionType": "openNewTab",
  "payload": {
    "redirectUrl": "http://google.com"
  }
}
```

```php
use Shopware\App\SDK\Response\ActionButtonResponse;

ActionButtonResponse::openNewTab('https://www.shopware.com');
```

### Show a notification to the user

To send a notification, you can use the `notification` action type. You need to pass the `status` property and the content of the notification as `message` property inside the payload.

```json
{
  "actionType": "notification",
  "payload": {
    "status": "success",
    "message": "This is the successful message"
  }
}
```

```php
use Shopware\App\SDK\Response\ActionButtonResponse;

ActionButtonResponse::notification('success', 'foo');
```

### Reload the current page

To reload the data in the user's current page you can use the `reload` action type with an empty payload.

```json
{
  "actionType": "reload",
  "payload": {}
}
```

```php
use Shopware\App\SDK\Response\ActionButtonResponse;

ActionButtonResponse::reload();
```

### Open a custom modal

To open a modal with the embedded link in the iframe, you can use the `openModal` action type. You need to pass the url that should be opened as the `iframeUrl` property and the `size` property inside the payload.

```json
{
  "actionType": "openModal",
  "payload": {
    "iframeUrl": "http://google.com",
    "size": "medium",
    "expand": true
  }
}
```

```php
use Shopware\App\SDK\Response\ActionButtonResponse;

ActionButtonResponse::modal('https://shopware.com', size: 'medium', expand: true)
```

### General structure

* `actionType`: The type of action the app want to be triggered, including `notification`, `reload`, `openNewTab`, `openModal`
* `payload`: The needed data to perform the action.
  * `redirectUrl`: The url to open new tab
  * `iframeUrl`: The embedded link in modal iframe
  * `status`: Notification status, including `success`, `error`, `info`, `warning`
  * `message`: The content of the notification
  * `size`: The size of the modal in `openModal` type, including `small`, `medium`, `large`, `fullscreen`, default `medium`
  * `expand`: The expansion of the modal in `openModal` type, including `true`, `false`, default `false`

## Using Custom Endpoints as target

It is also possible to use [custom endpoints](../app-scripts/custom-endpoints.md) as target for action buttons.

::: info
This feature was added in Shopware 6.4.10.0, previous versions don't support relative target urls for action buttons.
:::

To use custom endpoints as the target url for action buttons you can define the target url as a relative url in your apps manifest.xml:

::: code-group

```xml [manifest.xml]
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        ...
    </meta>
    <admin>
      <action-button action="test-button" entity="product" view="list" url="/api/script/action-button">
        <label>test-api-endpoint</label>
      </action-button>
    </admin>
</manifest>
```

:::

And then add the corresponding app script that should be executed when the user clicks the action button.

```twig
// Resources/scripts/api-action-button/action-button-script.twig
{% set ids = hook.request.ids %}

{% set response = services.response.json({
    "actionType": "notification",
    "payload": {
        "status": "success",
        "message": "You selected " ~ ids|length ~ " products."
    }
}) %}

{% do hook.setResponse(response) %}
```

As you can see it is possible to provide a [`JsonResponse`](../../../../resources/references/app-reference/script-reference/custom-endpoint-script-services-reference.md#json) to give [feedback to the user in the Administration](#providing-feedback-in-the-administration).

---

---
url: /docs/v6.5/guides/plugins/apps/administration/add-custom-action-button.md
---

# Add custom action button

:::info
This guide will show you how to add custom action buttons to the Shopware Administration using your manifest file. This works for simple applications; however, if you want to write more advanced applications, the [Meteor Admin SDK](https://shopware.github.io/meteor-admin-sdk/) is recommended. It has many more features and is more flexible.

For further details and guidance on custom action buttons, refer to the documentation provided on the Meteor Admin SDK's [action button](https://shopware.github.io/meteor-admin-sdk/docs/guide/api-reference/ui/actionButton) section.
:::

One extension possibility in the Administration is the ability to add custom action buttons to the smartbar. For now, you can add them in the smartbar of detail and list views:

![Custom action buttons in the Administration](../../../../assets/custom-buttons.png)

To get those buttons, you start in the `admin` section of your manifest file. There you can define `<action-button>` elements in order to add your button, as seen as below:

```xml
// manifest.xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        ...
    </meta>
    <admin>
        <action-button action="setPromotion" entity="promotion" view="detail" url="https://example.com/promotion/set-promotion">
            <label>set Promotion</label>
        </action-button>
        <action-button action="deletePromotion" entity="promotion" view="detail" url="https://example.com/promotion/delete-promotion">
            <label>delete Promotion</label>
        </action-button>
        <action-button action="restockProduct" entity="product" view="list" url="https://example.com/restock">
            <label>restock</label>
        </action-button>
    </admin>
</manifest>
```

For a complete reference of the structure of the manifest file take a look at the [Manifest reference](../../../../resources/references/app-reference/manifest-reference).

An action button must have the following attributes:

* `action`: Unique identifier for the action, can be set freely.
* `entity`: Here you define which entity you're working on.
* `view`: `detail`or `list`;  to set the view the button should be added to. Currently, you can choose between detail and listing view.

When the user clicks on the action button your app receives a request similar to the one generated by a [webhook](../app-base-guide#webhooks).
The main difference is that it contains the name of the entity and an array of ids that the user selected (or an array containing only a single id if the action button was executed on a detail page).

A sample payload may look like the following:

```json
{
  "source":{
    "url":"http:\/\/localhost:8000",
    "appVersion":"1.0.0",
    "shopId":"F0nWInXj5Xyr"
  },
  "data":{
    "ids":[
      "2132f284f71f437c9da71863d408882f"
    ],
    "entity":"product",
    "action":"restockProduct"
  },
  "meta":{
    "timestamp":1592403610,
    "reference":"9e968471797b4f29be3e3cf09f52d8da",
    "language":"2fbb5fe2e29a4d70aa5854ce7ce3e20b"
  }
}
```

```php
// injected or build by yourself
$shopResolver = new ShopResolver($repository);
$contextResolver = new ContextResolver();

$shop = $shopResolver->resolveShop($serverRequest);
$actionButton = $contextResolver->assembleActionButton($serverRequest, $shop);
```

```php
use Shopware\App\SDK\Context\ActionButton\ActionButtonAction;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\AsController;
use Symfony\Component\Routing\Annotation\Route;
use Psr\Http\Message\ResponseInterface;

#[AsController]
class ActionButtonController {
    #[Route('/action/product/detail')]
    public function handle(ActionButtonAction $button): ResponseInterface
    {
        // handle button
        
        return ActionButtonResponse::notification('success', 'Success message');
    }
}
```

::: info
Starting from Shopware version 6.4.1.0, the current shopware version will be sent as a `sw-version` header.
:::

Again you can verify the authenticity of the incoming request, like with [webhooks](../app-base-guide#webhooks), by checking the `shopware-shop-signature` it too contains the SHA256 HMAC of the request body, that is signed with the secret your app assigned the shop during the [registration](../app-base-guide#setup).

## Providing feedback in the Administration

::: info
This feature was added in Shopware 6.4.3.0, previous versions will ignore the response content.
:::

::: info
Starting from Shopware version 6.4.8.0, the requests of the [tab](#opening-a-new-tab-for-the-user) and [custom modal](#open-a-custom-modal) have the following additional query parameters:

* `shop-id`
* `shop-url`
* `timestamp`
* `sw-context-language`
* `sw-user-language`
* `shopware-shop-signature`

You **must** make sure to verify the authenticity of the incoming request by checking the `shopware-shop-signature`, which is a hash of the request's query part, signed with the shop's secret key.
:::

If you want to trigger an action inside the Administration upon completing the action, the app should return a response with a valid body and the header `shopware-app-signature` containing the SHA256 HMAC of the whole response body signed with the app secret.
If you do not need to trigger any actions, a response with an empty body is also always valid.

### Opening a new tab for the user

Examples response body:
To open a new tab in the user browser you can use the `openNewTab` action type. You need to pass the url that should be opened as the `redirectUrl` property inside the payload.

```txt
Content-Type: application/json

{
  "actionType": "openNewTab",
  "payload": {
    "redirectUrl": "http://google.com"
  }
}
```

```php
use Shopware\App\SDK\Response\ActionButtonResponse;

ActionButtonResponse::openNewTab('https://www.shopware.com');
```

### Show a notification to the user

To send a notification, you can use the `notification` action type. You need to pass the `status` property and the content of the notification as `message` property inside the payload.

```json
{
  "actionType": "notification",
  "payload": {
    "status": "success",
    "message": "This is the successful message"
  }
}
```

```php
use Shopware\App\SDK\Response\ActionButtonResponse;

ActionButtonResponse::notification('success', 'foo');
```

### Reload the current page

To reload the data in the user's current page you can use the `reload` action type with an empty payload.

```json
{
  "actionType": "reload",
  "payload": {}
}
```

```php
use Shopware\App\SDK\Response\ActionButtonResponse;

ActionButtonResponse::reload();
```

### Open a custom modal

To open a modal with the embedded link in the iframe, you can use the `openModal` action type. You need to pass the url that should be opened as the `iframeUrl` property and the `size` property inside the payload.

```json
{
  "actionType": "openModal",
  "payload": {
    "iframeUrl": "http://google.com",
    "size": "medium",
    "expand": true
  }
}
```

```php
use Shopware\App\SDK\Response\ActionButtonResponse;

ActionButtonResponse::modal('https://shopware.com', size: 'medium', expand: true)
```

### General structure

* `actionType`: The type of action the app want to be triggered, including `notification`, `reload`, `openNewTab`, `openModal`
* `payload`: The needed data to perform the action.
  * `redirectUrl`: The url to open new tab
  * `iframeUrl`: The embedded link in modal iframe
  * `status`: Notification status, including `success`, `error`, `info`, `warning`
  * `message`: The content of the notification
  * `size`: The size of the modal in `openModal` type, including `small`, `medium`, `large`, `fullscreen`, default `medium`
  * `expand`: The expansion of the modal in `openModal` type, including `true`, `false`, default `false`

## Using Custom Endpoints as target

It is also possible to use [custom endpoints](../app-scripts/custom-endpoints) as target for action buttons.

::: info
This feature was added in Shopware 6.4.10.0, previous versions don't support relative target urls for action buttons.
:::

To use custom endpoints as the target url for action buttons you can define the target url as a relative url in your apps manifest.xml:

```xml
// manifest.xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        ...
    </meta>
    <admin>
      <action-button action="test-button" entity="product" view="list" url="/api/script/action-button">
        <label>test-api-endpoint</label>
      </action-button>
    </admin>
</manifest>
```

And then add the corresponding app script that should be executed when the user clicks the action button.

```twig
// Resources/scripts/api-action-button/action-button-script.twig
{% set ids = hook.request.ids %}

{% set response = services.response.json({
    "actionType": "notification",
    "payload": {
        "status": "success",
        "message": "You selected " ~ ids|length ~ " products."
    }
}) %}

{% do hook.setResponse(response) %}
```

As you can see it is possible to provide a [`JsonResponse`](../../../../resources/references/app-reference/script-reference/custom-endpoint-script-services-reference#json) to give [feedback to the user in the administration](#providing-feedback-in-the-administration).

---

---
url: /docs/v6.6/guides/plugins/apps/administration/add-custom-action-button.md
---

# Add custom action button

:::info
This guide will show you how to add custom action buttons to the Shopware Administration using your manifest file. This works for simple applications; however, if you want to write more advanced applications, the [Meteor Admin SDK](/resources/admin-extension-sdk/) is recommended. It has many more features and is more flexible.

For further details and guidance on custom action buttons, refer to the documentation provided on the Meteor Admin SDK's [action button](/resources/admin-extension-sdk/api-reference/ui/actionButton) section.
:::

One extension possibility in the Administration is the ability to add custom action buttons to the smartbar. For now, you can add them in the smartbar of detail and list views:

![Custom action buttons in the Administration](../../../../assets/custom-buttons.png)

To get those buttons, you start in the `admin` section of your manifest file. There you can define `<action-button>` elements in order to add your button, as seen as below:

::: code-group

```xml [manifest.xml]
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        ...
    </meta>
    <admin>
        <action-button action="setPromotion" entity="promotion" view="detail" url="https://example.com/promotion/set-promotion">
            <label>set Promotion</label>
        </action-button>
        <action-button action="deletePromotion" entity="promotion" view="detail" url="https://example.com/promotion/delete-promotion">
            <label>delete Promotion</label>
        </action-button>
        <action-button action="restockProduct" entity="product" view="list" url="https://example.com/restock">
            <label>restock</label>
        </action-button>
    </admin>
</manifest>
```

:::

For a complete reference of the structure of the manifest file take a look at the [Manifest reference](../../../../resources/references/app-reference/manifest-reference).

An action button must have the following attributes:

* `action`: Unique identifier for the action, can be set freely.
* `entity`: Here you define which entity you're working on.
* `view`: `detail`or `list`;  to set the view the button should be added to. Currently, you can choose between detail and listing view.

When the user clicks on the action button your app receives a request similar to the one generated by a [webhook](../app-base-guide#webhooks).
The main difference is that it contains the name of the entity and an array of ids that the user selected (or an array containing only a single id if the action button was executed on a detail page).

A sample payload may look like the following:

```json
{
  "source":{
    "url":"http:\/\/localhost:8000",
    "appVersion":"1.0.0",
    "shopId":"F0nWInXj5Xyr"
  },
  "data":{
    "ids":[
      "2132f284f71f437c9da71863d408882f"
    ],
    "entity":"product",
    "action":"restockProduct"
  },
  "meta":{
    "timestamp":1592403610,
    "reference":"9e968471797b4f29be3e3cf09f52d8da",
    "language":"2fbb5fe2e29a4d70aa5854ce7ce3e20b"
  }
}
```

```php
// injected or build by yourself
$shopResolver = new ShopResolver($repository);
$contextResolver = new ContextResolver();

$shop = $shopResolver->resolveShop($serverRequest);
$actionButton = $contextResolver->assembleActionButton($serverRequest, $shop);
```

```php
use Shopware\App\SDK\Context\ActionButton\ActionButtonAction;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\AsController;
use Symfony\Component\Routing\Attribute\Route;
use Psr\Http\Message\ResponseInterface;

#[AsController]
class ActionButtonController {
    #[Route('/action/product/detail')]
    public function handle(ActionButtonAction $button): ResponseInterface
    {
        // handle button
        
        return ActionButtonResponse::notification('success', 'Success message');
    }
}
```

::: info
Starting from Shopware version 6.4.1.0, the current shopware version will be sent as a `sw-version` header.
:::

Again you can verify the authenticity of the incoming request, like with [webhooks](../app-base-guide#webhooks), by checking the `shopware-shop-signature` it too contains the SHA256 HMAC of the request body, that is signed with the secret your app assigned the shop during the [registration](../app-base-guide#setup).

## Providing feedback in the Administration

::: info
This feature was added in Shopware 6.4.3.0, previous versions will ignore the response content.
:::

::: info
Starting from Shopware version 6.4.8.0, the requests of the [tab](#opening-a-new-tab-for-the-user) and [custom modal](#open-a-custom-modal) have the following additional query parameters:

* `shop-id`
* `shop-url`
* `timestamp`
* `sw-context-language`
* `sw-user-language`
* `shopware-shop-signature`

You **must** make sure to verify the authenticity of the incoming request by checking the `shopware-shop-signature`, which is a hash of the request's query part, signed with the shop's secret key.
:::

If you want to trigger an action inside the Administration upon completing the action, the app should return a response with a valid body and the header `shopware-app-signature` containing the SHA256 HMAC of the whole response body signed with the app secret.
If you do not need to trigger any actions, a response with an empty body is also always valid.

### Opening a new tab for the user

Examples response body:
To open a new tab in the user browser you can use the `openNewTab` action type. You need to pass the url that should be opened as the `redirectUrl` property inside the payload.

```txt
Content-Type: application/json

{
  "actionType": "openNewTab",
  "payload": {
    "redirectUrl": "http://google.com"
  }
}
```

```php
use Shopware\App\SDK\Response\ActionButtonResponse;

ActionButtonResponse::openNewTab('https://www.shopware.com');
```

### Show a notification to the user

To send a notification, you can use the `notification` action type. You need to pass the `status` property and the content of the notification as `message` property inside the payload.

```json
{
  "actionType": "notification",
  "payload": {
    "status": "success",
    "message": "This is the successful message"
  }
}
```

```php
use Shopware\App\SDK\Response\ActionButtonResponse;

ActionButtonResponse::notification('success', 'foo');
```

### Reload the current page

To reload the data in the user's current page you can use the `reload` action type with an empty payload.

```json
{
  "actionType": "reload",
  "payload": {}
}
```

```php
use Shopware\App\SDK\Response\ActionButtonResponse;

ActionButtonResponse::reload();
```

### Open a custom modal

To open a modal with the embedded link in the iframe, you can use the `openModal` action type. You need to pass the url that should be opened as the `iframeUrl` property and the `size` property inside the payload.

```json
{
  "actionType": "openModal",
  "payload": {
    "iframeUrl": "http://google.com",
    "size": "medium",
    "expand": true
  }
}
```

```php
use Shopware\App\SDK\Response\ActionButtonResponse;

ActionButtonResponse::modal('https://shopware.com', size: 'medium', expand: true)
```

### General structure

* `actionType`: The type of action the app want to be triggered, including `notification`, `reload`, `openNewTab`, `openModal`
* `payload`: The needed data to perform the action.
  * `redirectUrl`: The url to open new tab
  * `iframeUrl`: The embedded link in modal iframe
  * `status`: Notification status, including `success`, `error`, `info`, `warning`
  * `message`: The content of the notification
  * `size`: The size of the modal in `openModal` type, including `small`, `medium`, `large`, `fullscreen`, default `medium`
  * `expand`: The expansion of the modal in `openModal` type, including `true`, `false`, default `false`

## Using Custom Endpoints as target

It is also possible to use [custom endpoints](../app-scripts/custom-endpoints) as target for action buttons.

::: info
This feature was added in Shopware 6.4.10.0, previous versions don't support relative target urls for action buttons.
:::

To use custom endpoints as the target url for action buttons you can define the target url as a relative url in your apps manifest.xml:

::: code-group

```xml [manifest.xml]
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        ...
    </meta>
    <admin>
      <action-button action="test-button" entity="product" view="list" url="/api/script/action-button">
        <label>test-api-endpoint</label>
      </action-button>
    </admin>
</manifest>
```

:::

And then add the corresponding app script that should be executed when the user clicks the action button.

```twig
// Resources/scripts/api-action-button/action-button-script.twig
{% set ids = hook.request.ids %}

{% set response = services.response.json({
    "actionType": "notification",
    "payload": {
        "status": "success",
        "message": "You selected " ~ ids|length ~ " products."
    }
}) %}

{% do hook.setResponse(response) %}
```

As you can see it is possible to provide a [`JsonResponse`](../../../../resources/references/app-reference/script-reference/custom-endpoint-script-services-reference#json) to give [feedback to the user in the administration](#providing-feedback-in-the-administration).

---

---
url: /docs/guides/plugins/plugins/storefront/styling/add-custom-assets.md
---

# Add Custom Assets

## Overview

When working with an own plugin, the usage of own custom images or other assets is a natural requirement. So of course you can do that in Shopware. In this guide we will discover together how it's possible to add and use custom assets in your Shopware plugin.

## Prerequisites

In order to be able to start with this guide, you need to have an own plugin running. As to most guides, this guide is also built upon the [Plugin base guide](../../plugin-base-guide.md).

Needless to say, you should have your image or another asset at hand to work with.

## Adding custom assets to your plugin

In order to add custom assets to your theme, you need to create a new folder called public inside the `src/Resources` directory of your plugin. Here you're able to store your assets files, so please feel free to save your image there - we'll do the same thing in our example plugin.

```bash
# PluginRoot
.
├── composer.json
└── src
    ├── Resources
    │   ├── public
    │   │   └── your-image.png <-- Asset file here
    └── SwagBasicExample.php
```

Afterwards, you need to make sure your plugin assets are copied over to the public/bundles folder. However, don't to this by hand - the command `bin/console assets:install` will take care of it.

```text
# shopware-root/public/bundles
.
├── administration
├── framework
├── storefront
└── swagbasicexample
    └── your-image.png <-- Your asset is copied here
```

## Linking to assets

### Using custom assets in your template

Let's think about a simple example, displaying our image right in the base template of the Storefront. In there we're able to link our assets by simply using the [asset](https://symfony.com/doc/current/templates.html#linking-to-css-javascript-and-image-assets) function Symfony provides:

```twig
// <plugin root>/src/Resources/views/storefront/base.html.twig
{% sw_extends '@Storefront/storefront/base.html.twig' %}

{% block base_main %}
    <h2>Asset:</h2>

    {# Using asset function to display our custom asset #}
    <img src="{{ asset('bundles/swagbasicexample/image.png', 'asset') }}">
    {{ parent() }}
{% endblock %}
```

That's basically all you need to do to link your plugin's custom assets.

### Using custom assets in your CSS files

There's one more interesting possibility though. If you want, you can use your custom asset in your CSS files. Look at the following example:

```css
// <plugin root>/src/Resources/app/storefront/src/scss/base.scss
body {
    background-image: url("#{$sw-asset-public-url}/bundles/swagbasicexample/image.png");
}
```

You see, we can use our custom assets by using the asset path provided by the `bundle` directory.

### Adding custom assets in themes

Of course, you're able to use custom assets in themes as well. In this context there's another way on integration custom assets into your theme. Please take a look on the guide about adding assets to a theme for further detail:

## Next steps

One of the said custom assets are medias. For more information on that, refer to [Media and thumbnails](../howto/use-media-thumbnails.md).

---

---
url: /docs/v6.5/guides/plugins/plugins/storefront/add-custom-assets.md
---

# Add Custom Assets

## Overview

When working with an own plugin, the usage of own custom images or other assets is a natural requirement. So of course you can do that in Shopware. In this guide we will discover together how it's possible to add and use custom assets in your Shopware plugin.

## Prerequisites

In order to be able to start with this guide, you need to have an own plugin running. As to most guides, this guide is also built upon the [Plugin base guide](../plugin-base-guide)

Needless to say, you should have your image or another asset at hand to work with.

## Adding custom assets to your plugin

In order to add custom assets to your theme, you need to create a new folder called public inside the `src/Resources` directory of your plugin. Here you're able to store your assets files, so please feel free to save your image there - we'll do the same thing in our example plugin.

```bash
# PluginRoot
.
├── composer.json
└── src
    ├── Resources
    │   ├── public
    │   │   └── your-image.png <-- Asset file here
    └── SwagBasicExample.php
```

Afterwards, you need to make sure your plugin assets are copied over to the public/bundles folder. However, don't to this by hand - the command `bin/console assets:install` will take care of it.

```text
# shopware-root/public/bundles
.
├── administration
├── framework
├── storefront
└── swagbasicexample
    └── your-image.png <-- Your asset is copied here
```

## Linking to assets

### Using custom assets in your template

Let's think about a simple example, displaying our image right in the base template of the Storefront. In there we're able to link our assets by simply using the [asset](https://symfony.com/doc/current/templates.html#linking-to-css-javascript-and-image-assets) function Symfony provides:

```twig
// <plugin root>/src/Resources/views/storefront/base.html.twig
{% sw_extends '@Storefront/storefront/base.html.twig' %}

{% block base_main %}
    <h2>Asset:</h2>

    {# Using asset function to display our custom asset #}
    <img src="{{ asset('bundles/swagbasicexample/image.png', 'asset') }}">
    {{ parent() }}
{% endblock %}
```

That's basically all you need to do to link your plugin's custom assets.

### Using custom assets in your CSS files

There's one more interesting possibility though. If you want, you can use your custom asset in your CSS files. Look at the following example:

```css
// <plugin root>/src/Resources/app/storefront/src/scss/base.scss
body {
    background-image: url("#{$sw-asset-public-url}/bundles/swagbasicexample/image.png");
}
```

You see, we can use our custom assets by using the asset path provided by the `bundle` directory.

### Adding custom assets in themes

Of course, you're able to use custom assets in themes as well. In this context there's another way on integration custom assets into your theme. Please take a look on the guide about adding assets to a theme for further detail:

## Next steps

One of the said custom assets are medias. For more information on that, refer to [Media and thumbnails](use-media-thumbnails).

---

---
url: /docs/v6.6/guides/plugins/plugins/storefront/add-custom-assets.md
---

# Add Custom Assets

## Overview

When working with an own plugin, the usage of own custom images or other assets is a natural requirement. So of course you can do that in Shopware. In this guide we will discover together how it's possible to add and use custom assets in your Shopware plugin.

## Prerequisites

In order to be able to start with this guide, you need to have an own plugin running. As to most guides, this guide is also built upon the [Plugin base guide](../plugin-base-guide)

Needless to say, you should have your image or another asset at hand to work with.

## Adding custom assets to your plugin

In order to add custom assets to your theme, you need to create a new folder called public inside the `src/Resources` directory of your plugin. Here you're able to store your assets files, so please feel free to save your image there - we'll do the same thing in our example plugin.

```bash
# PluginRoot
.
├── composer.json
└── src
    ├── Resources
    │   ├── public
    │   │   └── your-image.png <-- Asset file here
    └── SwagBasicExample.php
```

Afterwards, you need to make sure your plugin assets are copied over to the public/bundles folder. However, don't to this by hand - the command `bin/console assets:install` will take care of it.

```text
# shopware-root/public/bundles
.
├── administration
├── framework
├── storefront
└── swagbasicexample
    └── your-image.png <-- Your asset is copied here
```

## Linking to assets

### Using custom assets in your template

Let's think about a simple example, displaying our image right in the base template of the Storefront. In there we're able to link our assets by simply using the [asset](https://symfony.com/doc/current/templates.html#linking-to-css-javascript-and-image-assets) function Symfony provides:

```twig
// <plugin root>/src/Resources/views/storefront/base.html.twig
{% sw_extends '@Storefront/storefront/base.html.twig' %}

{% block base_main %}
    <h2>Asset:</h2>

    {# Using asset function to display our custom asset #}
    <img src="{{ asset('bundles/swagbasicexample/image.png', 'asset') }}">
    {{ parent() }}
{% endblock %}
```

That's basically all you need to do to link your plugin's custom assets.

### Using custom assets in your CSS files

There's one more interesting possibility though. If you want, you can use your custom asset in your CSS files. Look at the following example:

```css
// <plugin root>/src/Resources/app/storefront/src/scss/base.scss
body {
    background-image: url("#{$sw-asset-public-url}/bundles/swagbasicexample/image.png");
}
```

You see, we can use our custom assets by using the asset path provided by the `bundle` directory.

### Adding custom assets in themes

Of course, you're able to use custom assets in themes as well. In this context there's another way on integration custom assets into your theme. Please take a look on the guide about adding assets to a theme for further detail:

## Next steps

One of the said custom assets are medias. For more information on that, refer to [Media and thumbnails](use-media-thumbnails).

---

---
url: /docs/v6.5/guides/plugins/plugins/storefront/add-custom-captcha.md
---

# Add custom captcha

## Overview

You can add your custom captcha to the Shopware 6 core. This guide will show you how to do that.

## Prerequisites

In order to be able to start with this guide, you need to have an own plugin running. As to most guides, this guide is also built upon the [Plugin base guide](../plugin-base-guide)

## Adding custom captcha to your plugin

In order to add custom captcha to your plugin, create a new folder called `Captcha` inside the `src/Framework` directory of your plugin. This is optional, but it's a good practice to keep your plugin files organized.

Take a look at the AbstractCaptcha class. This class is the base class for all captcha types. It contains the following methods:

* `supports(string $type): bool` - This method is used to check if the captcha type is supported by the plugin.
* `isValid(string $code): bool` - This method is used to check if the captcha code is valid.
* `getName(): string` - This method is used to get the name of the captcha type.
* `shouldBreak(): bool` - This method is used to check if the captcha should break the validation.
* `getData(): array` - This method is used to get the data of the captcha type.

- `getViolations(): ConstraintViolationListInterface` - This method is used to get the violations of the captcha type.

Simply extend the AbstractCaptcha class and implement the methods isValid and getName. The isValid method should return true if the captcha code is valid, false otherwise. The getName method should return the name of the captcha type.

```php

<?php declare(strict_types=1);

namespace Shopware\Storefront\Framework\Captcha;

use GuzzleHttp\ClientInterface;
use Psr\Http\Client\ClientExceptionInterface;
use Shopware\Core\Framework\Log\Package;
use Symfony\Component\HttpFoundation\Request;

#[Package('storefront')]
class YourCaptcha extends AbstractCaptcha
{
    final public const CAPTCHA_NAME = 'yourCaptchaName';
    final public const CAPTCHA_REQUEST_PARAMETER = '_your_captcha_name';
    private const YOUR_CAPTCHA_ENDPOINT = 'https://www.yourcaptcha.com/verify';

    /**
     * @internal
     */
    public function __construct(private readonly ClientInterface $client)
    {
    }

    /**
     * {@inheritdoc}
     */
    public function isValid(Request $request, array $captchaConfig): bool
    {
        if (!$request->get(self::CAPTCHA_REQUEST_PARAMETER)) {
            return false;
        }
        
        try {
            $response = $this->client->request('POST', self::GOOGLE_CAPTCHA_VERIFY_ENDPOINT, [
                'form_params' => [
                    'response' => $request->get(self::CAPTCHA_REQUEST_PARAMETER),
                    'remoteip' => $request->getClientIp(),
                ],
            ]);

            $responseRaw = $response->getBody()->getContents();
            $response = json_decode($responseRaw, true);

            return $response && (bool) $response['success'];
        } catch (ClientExceptionInterface) {
            return false;
        }
    }

    /**
     * {@inheritdoc}
     */
    public function getName(): string
    {
        return self::CAPTCHA_NAME;
    }
}

```

## Google reCAPTCHA v3 example

You might want to check out the example [GoogleReCaptchaV3](https://github.com/shopware/shopware/blob/trunk/src/Storefront/Framework/Captcha/GoogleReCaptchaV3.php) class from the Shopware 6 core. It's a good example of how to implement a custom captcha type.

---

---
url: /docs/v6.6/guides/plugins/plugins/storefront/add-custom-captcha.md
---

# Add custom captcha

## Overview

You can add your custom captcha to the Shopware 6 core. This guide will show you how to do that.

## Prerequisites

In order to be able to start with this guide, you need to have an own plugin running. As to most guides, this guide is also built upon the [Plugin base guide](../plugin-base-guide)

## Adding custom captcha to your plugin

In order to add custom captcha to your plugin, create a new folder called `Captcha` inside the `src/Framework` directory of your plugin. This is optional, but it's a good practice to keep your plugin files organized.

Take a look at the AbstractCaptcha class. This class is the base class for all captcha types. It contains the following methods:

* `supports(string $type): bool` - This method is used to check if the captcha type is supported by the plugin.
* `isValid(string $code): bool` - This method is used to check if the captcha code is valid.
* `getName(): string` - This method is used to get the name of the captcha type.
* `shouldBreak(): bool` - This method is used to check if the captcha should break the validation.
* `getData(): array` - This method is used to get the data of the captcha type.
* `getViolations(): ConstraintViolationListInterface` - This method is used to get the violations of the captcha type.

Extend the AbstractCaptcha class and implement the methods isValid and getName. The isValid method should return true if the captcha code is valid, false otherwise. The getName method should return the name of the captcha type.

```php

<?php declare(strict_types=1);

namespace Shopware\Storefront\Framework\Captcha;

use GuzzleHttp\ClientInterface;
use Psr\Http\Client\ClientExceptionInterface;
use Shopware\Core\Framework\Log\Package;
use Symfony\Component\HttpFoundation\Request;

#[Package('storefront')]
class YourCaptcha extends AbstractCaptcha
{
    final public const CAPTCHA_NAME = 'yourCaptchaName';
    final public const CAPTCHA_REQUEST_PARAMETER = '_your_captcha_name';
    private const YOUR_CAPTCHA_ENDPOINT = 'https://www.yourcaptcha.com/verify';

    /**
     * @internal
     */
    public function __construct(private readonly ClientInterface $client)
    {
    }

    /**
     * {@inheritdoc}
     */
    public function isValid(Request $request, array $captchaConfig): bool
    {
        if (!$request->get(self::CAPTCHA_REQUEST_PARAMETER)) {
            return false;
        }
        
        try {
            $response = $this->client->request('POST', self::GOOGLE_CAPTCHA_VERIFY_ENDPOINT, [
                'form_params' => [
                    'response' => $request->get(self::CAPTCHA_REQUEST_PARAMETER),
                    'remoteip' => $request->getClientIp(),
                ],
            ]);

            $responseRaw = $response->getBody()->getContents();
            $response = json_decode($responseRaw, true);

            return $response && (bool) $response['success'];
        } catch (ClientExceptionInterface) {
            return false;
        }
    }

    /**
     * {@inheritdoc}
     */
    public function getName(): string
    {
        return self::CAPTCHA_NAME;
    }
}

```

## Google reCAPTCHA v3 example

You might want to check out the example [GoogleReCaptchaV3](https://github.com/shopware/shopware/blob/trunk/src/Storefront/Framework/Captcha/GoogleReCaptchaV3.php) class from the Shopware 6 core. It's a good example of how to implement a custom captcha type.

---

---
url: /docs/guides/plugins/plugins/storefront/howto/add-custom-captcha.md
---

# Add Custom Captcha

## Overview

Add your custom captcha to the Shopware 6 core. This guide shows you how.

## Prerequisites

A running plugin is required. Review the [Plugin base guide](../../plugin-base-guide.md) for guidance on creating one.

## Adding custom captcha to your plugin

In order to add custom captcha to your plugin, create a new folder called `Captcha` inside the `src/Framework` directory of your plugin. This is optional, but it's a good practice to keep your plugin files organized.

Take a look at the AbstractCaptcha class. This class is the base class for all captcha types. It contains the following methods:

* `supports(string $type): bool` - This method is used to check if the captcha type is supported by the plugin.
* `isValid(string $code): bool` - This method is used to check if the captcha code is valid.
* `getName(): string` - This method is used to get the name of the captcha type.
* `shouldBreak(): bool` - This method is used to check if the captcha should break the validation.
* `getData(): array` - This method is used to get the data of the captcha type.
* `getViolations(): ConstraintViolationListInterface` - This method is used to get the violations of the captcha type.

Extend the AbstractCaptcha class and implement the methods isValid and getName. The isValid method should return true if the captcha code is valid, false otherwise. The getName method should return the name of the captcha type.

```php

<?php declare(strict_types=1);

namespace Shopware\Storefront\Framework\Captcha;

use GuzzleHttp\ClientInterface;
use Psr\Http\Client\ClientExceptionInterface;
use Shopware\Core\Framework\Log\Package;
use Symfony\Component\HttpFoundation\Request;

#[Package('storefront')]
class YourCaptcha extends AbstractCaptcha
{
    final public const CAPTCHA_NAME = 'yourCaptchaName';
    final public const CAPTCHA_REQUEST_PARAMETER = '_your_captcha_name';
    private const YOUR_CAPTCHA_ENDPOINT = 'https://www.yourcaptcha.com/verify';

    /**
     * @internal
     */
    public function __construct(private readonly ClientInterface $client)
    {
    }

    /**
     * {@inheritdoc}
     */
    public function isValid(Request $request, array $captchaConfig): bool
    {
        if (!$request->get(self::CAPTCHA_REQUEST_PARAMETER)) {
            return false;
        }
        
        try {
            $response = $this->client->request('POST', self::GOOGLE_CAPTCHA_VERIFY_ENDPOINT, [
                'form_params' => [
                    'response' => $request->get(self::CAPTCHA_REQUEST_PARAMETER),
                    'remoteip' => $request->getClientIp(),
                ],
            ]);

            $responseRaw = $response->getBody()->getContents();
            $response = json_decode($responseRaw, true);

            return $response && (bool) $response['success'];
        } catch (ClientExceptionInterface) {
            return false;
        }
    }

    /**
     * {@inheritdoc}
     */
    public function getName(): string
    {
        return self::CAPTCHA_NAME;
    }
}

```

## Google reCAPTCHA v3 example

You might want to check out the example [GoogleReCaptchaV3](https://github.com/shopware/shopware/blob/trunk/src/Storefront/Framework/Captcha/GoogleReCaptchaV3.php) class from the Shopware 6 core. It's a good example of how to implement a custom captcha type.

---

---
url: /docs/guides/plugins/plugins/framework/system-check/add-custom-check.md
---

# Add Custom Check

## Overview

In this guide, we will be building a dummy example of a custom system check that verifies if the local system has enough disk space to operate normally.

## Add a new Custom Check

First, you need to add a new `LocalDiskSpaceCheck` class that extends the `Shopware\Core\Framework\SystemCheck\BaseCheck` and implement the essential categorization methods.

### Fill the categorization methods

Each check contains a set of categorization methods that help to classify the check, and determine when and where it should be executed.

```php
class LocalDiskSpaceCheck extends BaseCheck
{
    public function category(): Category
    {
        // crucial for the system to function at all. 
        return Category::SYSTEM;
    }

    public function name(): string
    {
        return 'LocalDiskSpaceCheck';
    }

    protected function allowedSystemCheckExecutionContexts(): array
    {   // a potentially long-running check, because it has an IO operation.
        return SystemCheckExecutionContext::longRunning();
    }
}
```

### Create the check logic

The next step is to implement the actual check logic. We will check if the disk space is below a certain threshold and return the appropriate result.

```php
class LocalDiskSpaceCheck extends BaseCheck
{
    public function __construct(
        private readonly string $adapterType,
        private readonly string $installationPath,
        private readonly int $warningThresholdInMb
    )
    {
    }

    public function run(): Result
    {
        if ($this->adapterType !== 'local') {
           return new Result(name: $this->name(), status: Status::SKIPPED, message: 'Disk space check is only available for local file systems.', healthy: true)
        }
        
        $availableSpaceInMb = $this->getFreeDiskSpaceInMegaBytes();
        if ($availableSpaceInMb < $this->warningThresholdInMb) {
            return new Result(name: $this->name(), status: Status::WARNING, message: sprintf('Available disk space is below the warning threshold of %s.', $this->warningThresholdInMb), healthy: true);
        }

        return new Result(name: $this->name(), status: Status::OK, message: 'Disk space is sufficient.', healthy: true);
    }

     private function getFreeDiskSpaceInMegaBytes()
     {
        $freeSpace = disk_free_space($this->installationPath);
        $totalSpace = disk_total_space($this->installationPath);
        $availableSpace = $totalSpace - $freeSpace;

        return $availableSpace / 1024 / 1024;
     }
    ...
    ...
}
```

> An important consideration is the healthy flag, which is subjective and can vary depending on the specific shop's criteria. For example, if the disk space threshold is set high, the system can still function normally, so the healthy flag could be true. Conversely, if the threshold is too low for normal operation, the healthy flag could be false.

### Register the custom check

Finally, you need to register the custom check as a service resource.

```php
$services->set(YourNameSpace\LocalDiskSpaceCheck::class)
    ->args([
        '%shopware.filesystem.public.type%',
        '%shopware.filesystem.public.config.root%',
        '%warning_threshold_in_mb%',
    ])
    ->tag('shopware.system_check');
```

### Trigger the check

The system check is now part of the system check collection and will be executed when the system check is triggered. Refer to the [System Check](index.md) guide for more information.

---

---
url: /docs/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md
---

# Add Custom CLI Commands

Shopware CLI commands are based on [Symfony Console](https://symfony.com/doc/current/console.html). This means that creating custom commands in Shopware plugins follows the standard Symfony approach.

To add a custom command in a Shopware plugin, you must register it as a service in your plugin's `src/Resources/config/services.php` and tag it with `console.command`:

```php
$services->set(Swag\BasicExample\Command\ExampleCommand::class)
    ->tag('console.command');
```

Commands registered as services in a Shopware plugin are automatically available via `bin/console`.

A minimal command class:

```php
// <plugin root>/src/Command/ExampleCommand.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Command;

use Symfony\Component\Console\Attribute\AsCommand;
use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

#[AsCommand(name: 'swag:example', description: 'Example command')]
class ExampleCommand extends Command
{
    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $output->writeln('Hello from ExampleCommand');

        return Command::SUCCESS;
    }
}
```

## Next steps

[Adding a scheduled task](add-scheduled-task.md)

---

---
url: /docs/v6.5/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md
---

# Add Custom CLI Commands

To ease development tasks, Shopware contains the Symfony commands functionality. This allows (plugin-) developers to define new commands executable via the Symfony console at `bin/console`. The best thing about commands is, that they're more than just simple standalone PHP scripts - they integrate into Symfony and Shopware, so you've got access to all the functionality offered by both of them.

Creating a command for Shopware 6 via a plugin works exactly like you would add a command to Symfony. Make sure to have a look at the Symfony commands guide:

## Prerequisites

This guide **does not** explain how to create a new plugin for Shopware 6. Head over to our plugin base guide to learn how to create a plugin at first:

The main requirement here is to have a `services.xml` file loaded in your plugin. This can be achieved by placing the file into a `Resources/config` directory relative to your plugin's base class location.

::: info
Refer to this video on custom **[Creating a CLI command](https://www.youtube.com/watch?v=OL_qNVLLyaI)**. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

## Registering your command

From here on, everything works exactly like in Symfony itself. Commands are recognised by Shopware, once they're tagged with the `console.command` tag in the [dependency injection](dependency-injection) container. So to register a new command, just add it to your plugin's `services.xml` and specify the `console.command` tag:

```html
<services>
   <!-- ... -->

   <service id="Swag\BasicExample\Command\ExampleCommand">
       <tag name="console.command"/>
   </service>
</services>
<!-- ... -->
```

Here's a full example `services.xml` which registers your custom command:

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Command\ExampleCommand">
            <tag name="console.command"/>
        </service>
    </services>
</container>
```

Your command's class should extend from the `Symfony\Component\Console\Command\Command` class, here's an example:

```php
// <plugin root>/src/Command/ExampleCommand.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Command;

use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;

class ExampleCommand extends Command
{
    // Command name
    protected static $defaultName = 'swag-commands:example';

    // Provides a description, printed out in bin/console
    protected function configure(): void
    {
        $this->setDescription('Does something very special.');
    }

    // Actual code executed in the command
    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $output->writeln('It works!');

        // Exit code 0 for success
        return 0;
    }
}
```

This command is of course only a basic example, so feel free to experiment. As stated above, you now have access to all the functionality offered by Symfony and Shopware.

::: info
For inspiration, maybe have a look at the Symfony documentation - you may for example use [tables](https://symfony.com/doc/current/components/console/helpers/table.html), [progress bars](https://symfony.com/doc/current/components/console/helpers/progressbar.html), or [custom formats](https://symfony.com/doc/current/components/console/helpers/formatterhelper.html).
:::

### Running commands

Commands are run via the `bin/console` executable. To list all available commands, run `bin/console list`:

```text
$: php bin/console list
Symfony 4.4.4 (env: dev, debug: true)

Usage:
  command [options] [arguments]

Options:
  -h, --help            Display this help message
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi            Force ANSI output
      --no-ansi         Disable ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -e, --env=ENV         The Environment name. [default: "dev"]
      --no-debug        Switches off debug mode.
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Available commands:
  about                                   Displays information about the current project
  help                                    Displays help for a command
  list                                    Lists commands
 feature
  feature:dump                            Creating json file with feature config for js testing and hot reloading capabilities.
 assets
  assets:install                          
 bundle
  bundle:dump                             Creates a json file with the configuration for each active Shopware bundle.
 cache
  cache:clear                             Clears the cache
  cache:pool:clear                        Clears cache pools
  cache:pool:delete                       Deletes an item from a cache pool
  cache:pool:list                         List available cache pools
  cache:pool:prune                        Prunes cache pools
  cache:warmup                            Warms up an empty cache
 [...]
```

Each command usually has a namespace like `cache`, so to clear the cache you would execute `php bin/console cache:clear`. If you would like to learn more about commands in general, have a look at [this article](https://symfony.com/doc/current/console.html) in the Symfony documentation.

## More interesting topics

* [Adding a scheduled task](add-scheduled-task)

---

---
url: /docs/v6.6/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md
---

# Add Custom CLI Commands

To ease development tasks, Shopware contains the Symfony commands functionality. This allows (plugin-) developers to define new commands executable via the Symfony console at `bin/console`. The best thing about commands is, that they're more than just simple standalone PHP scripts - they integrate into Symfony and Shopware, so you've got access to all the functionality offered by both of them.

Creating a command for Shopware 6 via a plugin works exactly like you would add a command to Symfony. Make sure to have a look at the Symfony commands guide:

## Prerequisites

This guide **does not** explain how to create a new plugin for Shopware 6. Head over to our plugin base guide to learn how to create a plugin at first:

The main requirement here is to have a `services.xml` file loaded in your plugin. This can be achieved by placing the file into a `Resources/config` directory relative to your plugin's base class location.

::: info
Refer to this video on custom **[Creating a CLI command](https://www.youtube.com/watch?v=OL_qNVLLyaI)**. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

## Registering your command

From here on, everything works exactly like in Symfony itself. Commands are recognised by Shopware, once they're tagged with the `console.command` tag in the [dependency injection](dependency-injection) container. So to register a new command, just add it to your plugin's `services.xml` and specify the `console.command` tag:

```html
<services>
   <!-- ... -->

   <service id="Swag\BasicExample\Command\ExampleCommand">
       <tag name="console.command"/>
   </service>
</services>
<!-- ... -->
```

Here's a full example `services.xml` which registers your custom command:

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Command\ExampleCommand">
            <tag name="console.command"/>
        </service>
    </services>
</container>
```

Your command's class should extend from the `Symfony\Component\Console\Command\Command` class, here's an example:

```php
// <plugin root>/src/Command/ExampleCommand.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Command;

use Symfony\Component\Console\Command\Command;
use Symfony\Component\Console\Input\InputInterface;
use Symfony\Component\Console\Output\OutputInterface;
use Symfony\Component\Console\Attribute\AsCommand;

// Command name
#[AsCommand(name: 'swag-commands:example')]
class ExampleCommand extends Command
{
    // Provides a description, printed out in bin/console
    protected function configure(): void
    {
        $this->setDescription('Does something very special.');
    }

    // Actual code executed in the command
    protected function execute(InputInterface $input, OutputInterface $output): int
    {
        $output->writeln('It works!');

        return Command::SUCCESS;
    }
}
```

This command is of course only a basic example, so feel free to experiment. As stated above, you now have access to all the functionality offered by Symfony and Shopware.

::: info
For inspiration, maybe have a look at the Symfony documentation - you may for example use [tables](https://symfony.com/doc/current/components/console/helpers/table.html), [progress bars](https://symfony.com/doc/current/components/console/helpers/progressbar.html), or [custom formats](https://symfony.com/doc/current/components/console/helpers/formatterhelper.html).
:::

### Running commands

Commands are run via the `bin/console` executable. To list all available commands, run `bin/console list`:

```text
$: php bin/console list
Symfony 4.4.4 (env: dev, debug: true)

Usage:
  command [options] [arguments]

Options:
  -h, --help            Display this help message
  -q, --quiet           Do not output any message
  -V, --version         Display this application version
      --ansi            Force ANSI output
      --no-ansi         Disable ANSI output
  -n, --no-interaction  Do not ask any interactive question
  -e, --env=ENV         The Environment name. [default: "dev"]
      --no-debug        Switches off debug mode.
  -v|vv|vvv, --verbose  Increase the verbosity of messages: 1 for normal output, 2 for more verbose output and 3 for debug

Available commands:
  about                                   Displays information about the current project
  help                                    Displays help for a command
  list                                    Lists commands
 feature
  feature:dump                            Creating json file with feature config for js testing and hot reloading capabilities.
 assets
  assets:install                          
 bundle
  bundle:dump                             Creates a json file with the configuration for each active Shopware bundle.
 cache
  cache:clear                             Clears the cache
  cache:pool:clear                        Clears cache pools
  cache:pool:delete                       Deletes an item from a cache pool
  cache:pool:list                         List available cache pools
  cache:pool:prune                        Prunes cache pools
  cache:warmup                            Warms up an empty cache
 [...]
```

Each command usually has a namespace like `cache`, so to clear the cache you would execute `php bin/console cache:clear`. If you would like to learn more about commands in general, have a look at [this article](https://symfony.com/doc/current/console.html) in the Symfony documentation.

## More interesting topics

* [Adding a scheduled task](add-scheduled-task)

---

---
url: /docs/v6.5/guides/plugins/apps/content/cms/add-custom-cms-blocks.md
---

# Add custom CMS blocks

::: info
This functionality is available starting with Shopware 6.4.4.0.

You can [add custom CMS blocks](../../../plugins/content/cms/add-cms-block) using the plugin system, however these will not be available in Shopware cloud stores.
:::

Didn't get in touch with Shopware's Shopping Experiences (CMS) yet? Check out the concept behind it first:

## Prerequisites

This guide is based on our [App Base Guide](../../app-base-guide) and assumes you have already set up an app.

## Overview

Adding custom CMS blocks from an app works a bit differently than [adding them from a plugin](../../../plugins/content/cms/add-cms-block).
Custom CMS blocks are added by providing a `cms.xml` in the `Resources/` directory of your app.
The basic directory structure looks as follows:

```text
├── Resources
│   ├── app
│   │   └── storefront
│   │       └── src
│   │           └── scss
│   │               └── base.scss
│   ├── cms
│   │   └── blocks
│   │       └── swag-image-text-reversed
│   │           ├── preview.html
│   │           └── styles.css
│   ├── views
│   │   └── storefront
│   │       └── block
│   │           └── cms-block-swag-image-text-reversed-component.html.twig
│   └── cms.xml
└── manifest.xml
```

Each CMS block defined within your `cms.xml` must have a directory matching the block's name in `Resources/cms/blocks/`.
In those directories you shape your blocks for the CMS module in the Administration by supplying a `preview.html` containing the template used for displaying a preview.
Styling the preview in the sidebar and the component in the CMS editor is possible from the `styles.css`.

::: info
Due to technical limitations it's not possible to use templating engines (like Twig) or preprocessors (like Sass) for rendering and styling the preview.
:::

The Storefront representations of your blocks reside in `Resources/views/storefront/block/`.

## Defining blocks

As already mentioned above and similar to an app's `manifest.xml`, CMS blocks also require some definition done in the `cms.xml`.
In this example we will define a custom CMS block that will extend the default block `image-text` and reverse its elements:

```xml
// <app root>/Resources/cms.xml
<?xml version="1.0" encoding="utf-8" ?>
<cms xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Cms/Schema/cms-1.0.xsd">
    <blocks>
        <block>
            <!-- A unique technical name for your block. We recommend to use a shorthand prefix for your company, e.g. "Swag" for shopware AG. -->
            <name>swag-image-text-reversed</name>

            <!-- The category your block is associated with. See the XSD for available categories. -->
            <category>text-image</category>

            <!-- Your block's label which will be shown in the CMS module in the Administration. -->
            <label>Two columns, text &amp; boxed image</label>
            <label lang="de-DE">Zwei Spalten, Text &amp; gerahmtes Bild</label>

            <!-- The slots that your block holds which again hold CMS elements. -->
            <slots>
                <!-- A slot requires a unique name and a type which refers to the CMS element it shows. Right now you can only use the CMS elements provided by Shopware but at a later point you will be able to add custom elements too. -->
                <slot name="left" type="text">
                    <!-- The slot requires some basic configuration. The following config-value elements highly depend on which element the slot holds. -->
                    <config>
                        <!-- The following config-value will be interpreted as 'verticalAlign: { source: "static", value: "top"}' in the JavaScript. -->
                        <config-value name="vertical-align" source="static" value="top"/>
                    </config>
                </slot>

                <slot name="right" type="image">
                    <config>
                        <config-value name="display-mode" source="static" value="auto"/>
                        <config-value name="vertical-align" source="static" value="top"/>
                    </config>
                </slot>
            </slots>

            <!-- Each block comes with a default configuration which is pre-filled and customizable when adding a block to a section in the CMS module in the Administration. -->
            <default-config>
                <margin-top>20px</margin-top>
                <margin-right>20px</margin-right>
                <margin-bottom>20px</margin-bottom>
                <margin-left>20px</margin-left>
                <!-- The sizing mode of your block. Allowed values are "boxed" or "full_width". -->
                <sizing-mode>boxed</sizing-mode>
            </default-config>
        </block>
    </blocks>
</cms>
```

Let's have a look at how to configure a CMS block from your app's `cms.xml`:

`<name>` : A **unique** technical name for your block.

`<category>` : Blocks are divided into categories. Available categories can be found in the [plugin guide](../../../plugins/content/cms/add-cms-block#custom-block-in-the-administration).

`<label>` : The **translatable** label will be shown in the Administration.

`<default-config>` : Some default configuration for the block.

`<slots>` : Each block holds slots that configure which element they show.

The full CMS reference is available here:

### Block preview

The preview template for `swag-image-text-reversed` looks like this:

```html
// <app root>/Resources/cms/blocks/swag-image-text-reversed/preview.html
<div class="sw-cms-preview-swag-image-text-reversed">
    <div>
        <h2>Lorem ipsum dolor</h2>
        <p>Lorem ipsum dolor sit amet, consetetur sadipscing elitr.</p>
    </div>

    <!-- Alternatively you might e.g. also use a base64 encoded preview image instead of an external resource. -->
    <img src="https://example.com/preview.jpg" alt="Preview image">
</div>
```

::: info
For security reasons you can only use pure HTML in the preview template.
The template will be sanitized from possibly malicious tags like `<script>` or attributes like `:src="'/administration/static/img/cms/preview_mountain_small.jpg' | asset"`.
:::

The styling of the preview looks as follows:

```css
// <app root>/Resources/cms/blocks/swag-image-text-reversed/styles.css
/* 
 * Styling of your block preview in the CMS sidebar
 */
.sw-cms-preview-swag-image-text-reversed {
    display: grid;
    grid-template-columns: 1fr 1fr;
    grid-column-gap: 20px;
    padding: 15px;
}

/*
 * Styling of your block in the CMS editor
 * Pattern: sw-cms-block-${block.name}-component
 */
.sw-cms-block-swag-image-text-reversed-component {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(195px, 1fr));
    grid-gap: 40px;
}

/*
 * Each slot will have an additional class
 * Pattern: sw-cms-slot-${slot.name}
 */
.sw-cms-block-swag-image-text-reversed-component .sw-cms-slot-left {
    
}

/*
 * Each slot will have an additional class
 * Pattern: sw-cms-slot-${slot.name}
 */
.sw-cms-block-swag-image-text-reversed-component .sw-cms-slot-right {

}
```

The DOM structure of the block in the CMS editor will look like this:

```html
<div class="sw-cms-block-swag-image-text-reversed-component">
    <div class="sw-cms-slot sw-cms-slot-left"></div>
    <div class="sw-cms-slot sw-cms-slot-right"></div>
</div>
```

## Defining slots

Each slot has a **unique** `name` and a `type` that refers to which element it shows.
All available elements can be found in [src/Administration/Resources/app/administration/src/module/sw-cms/elements](https://github.com/shopware/shopware/tree/trunk/src/Administration/Resources/app/administration/src/module/sw-cms/elements).
At a later point you will also be able to define custom elements but for now you can use the elements shipped by Shopware.

The `config` of a slot is very dynamic as it highly depends on which `type` you have chosen.
A good starting point to find out which elements require which configuration is each element's `index.js` in the corresponding directory in [src/Administration/Resources/app/administration/src/module/sw-cms/blocks](https://github.com/shopware/shopware/tree/trunk/src/Administration/Resources/app/administration/src/module/sw-cms/blocks).

## Registering blocks

Unlike adding blocks from a plugin, blocks provided from an app will be automatically registered during runtime - so all you need to take care of is to properly define and configure them.

## Storefront representation

Providing the Storefront representation of your blocks works very similarly as in the [plugin example](../../../plugins/content/cms/add-cms-block#storefront-representation).
In `Resources/views/storefront/block/` a Twig template matching the pattern `cms-block-${block.name}-component.html.twig` is expected.

So in this example, it's sufficient to simply extend the existing `image-text` element:

```twig
// <app root>/Resources/views/storefront/block/cms-block-swag-image-text-reversed-component.html.twig
{% sw_extends '@Storefront/storefront/block/cms-block-image-text.html.twig' %}
```

Styling of your blocks in the Storefront can then be done in `Resources/app/storefront/src/scss/base.scss`.

## Further reading

You can further take a look at the [CMS references](../../../../../resources/references/app-reference/cms-reference).

---

---
url: /docs/v6.6/guides/plugins/apps/content/cms/add-custom-cms-blocks.md
---

# Add custom CMS blocks

::: info
This functionality is available starting with Shopware 6.4.4.0.

Alternatively, you can [add custom CMS blocks](../../../plugins/content/cms/add-cms-block) using the plugin system, however these will not be available in Shopware cloud stores.
:::

Didn't get in touch with Shopware's Shopping Experiences (CMS) yet? Check out the concept behind it first:

## Prerequisites

This guide is based on our [App Base Guide](../../app-base-guide) and assumes you have already set up an app.

## Overview

Adding custom CMS blocks from an app works a bit differently than [adding them from a plugin](../../../plugins/content/cms/add-cms-block).
Custom CMS blocks are added by providing a `cms.xml` in the `Resources/` directory of your app.
The basic directory structure looks as follows:

```text
├── Resources
│   ├── app
│   │   └── storefront
│   │       └── src
│   │           └── scss
│   │               └── base.scss
│   ├── cms
│   │   └── blocks
│   │       └── swag-image-text-reversed
│   │           ├── preview.html
│   │           └── styles.css
│   ├── views
│   │   └── storefront
│   │       └── block
│   │           └── cms-block-swag-image-text-reversed-component.html.twig
│   └── cms.xml
└── manifest.xml
```

Each CMS block defined within your `cms.xml` must have a directory matching the block's name in `Resources/cms/blocks/`.
In those directories you shape your blocks for the CMS module in the Administration by supplying a `preview.html` containing the template used for displaying a preview.
Styling the preview in the sidebar and the component in the CMS editor is possible from the `styles.css`.

::: info
Due to technical limitations it's not possible to use templating engines (like Twig) or preprocessors (like Sass) for rendering and styling the preview.
:::

The Storefront representations of your blocks reside in `Resources/views/storefront/block/`.

## Defining blocks

As already mentioned above and similar to an app's `manifest.xml`, CMS blocks also require some definition done in the `cms.xml`.
In this example we will define a custom CMS block that will extend the default block `image-text` and reverse its elements:

```xml
// <app root>/Resources/cms.xml
<?xml version="1.0" encoding="utf-8" ?>
<cms xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Cms/Schema/cms-1.0.xsd">
    <blocks>
        <block>
            <!-- A unique technical name for your block. We recommend to use a shorthand prefix for your company, e.g. "Swag" for shopware AG. -->
            <name>swag-image-text-reversed</name>

            <!-- The category your block is associated with. See the XSD for available categories. -->
            <category>text-image</category>

            <!-- Your block's label which will be shown in the CMS module in the Administration. -->
            <label>Two columns, text &amp; boxed image</label>
            <label lang="de-DE">Zwei Spalten, Text &amp; gerahmtes Bild</label>

            <!-- The slots that your block holds which again hold CMS elements. -->
            <slots>
                <!-- A slot requires a unique name and a type which refers to the CMS element it shows. Right now you can only use the CMS elements provided by Shopware but at a later point you will be able to add custom elements too. -->
                <slot name="left" type="text">
                    <!-- The slot requires some basic configuration. The following config-value elements highly depend on which element the slot holds. -->
                    <config>
                        <!-- The following config-value will be interpreted as 'verticalAlign: { source: "static", value: "top"}' in the JavaScript. -->
                        <config-value name="vertical-align" source="static" value="top"/>
                    </config>
                </slot>

                <slot name="right" type="image">
                    <config>
                        <config-value name="display-mode" source="static" value="auto"/>
                        <config-value name="vertical-align" source="static" value="top"/>
                    </config>
                </slot>
            </slots>

            <!-- Each block comes with a default configuration which is pre-filled and customizable when adding a block to a section in the CMS module in the Administration. -->
            <default-config>
                <margin-top>20px</margin-top>
                <margin-right>20px</margin-right>
                <margin-bottom>20px</margin-bottom>
                <margin-left>20px</margin-left>
                <!-- The sizing mode of your block. Allowed values are "boxed" or "full_width". -->
                <sizing-mode>boxed</sizing-mode>
            </default-config>
        </block>
    </blocks>
</cms>
```

Let's have a look at how to configure a CMS block from your app's `cms.xml`:

`<name>` : A **unique** technical name for your block.

`<category>` : Blocks are divided into categories. Available categories can be found in the [plugin guide](../../../plugins/content/cms/add-cms-block#custom-block-in-the-administration).

`<label>` : The **translatable** label will be shown in the Administration.

`<default-config>` : Some default configuration for the block.

`<slots>` : Each block holds slots that configure which element they show.

The full CMS reference is available here:

### Block preview

The preview template for `swag-image-text-reversed` looks like this:

```html
// <app root>/Resources/cms/blocks/swag-image-text-reversed/preview.html
<div class="sw-cms-preview-swag-image-text-reversed">
    <div>
        <h2>Lorem ipsum dolor</h2>
        <p>Lorem ipsum dolor sit amet, consetetur sadipscing elitr.</p>
    </div>

    <!-- Alternatively you might e.g. also use a base64 encoded preview image instead of an external resource. -->
    <img src="https://example.com/preview.jpg" alt="Preview image">
</div>
```

::: info
For security reasons you can only use pure HTML in the preview template.
The template will be sanitized from possibly malicious tags like `<script>` or attributes like `:src="assetFilter('/administration/static/img/cms/preview_mountain_small.jpg')"`.
:::

The styling of the preview looks as follows:

```css
// <app root>/Resources/cms/blocks/swag-image-text-reversed/styles.css
/* 
 * Styling of your block preview in the CMS sidebar
 */
.sw-cms-preview-swag-image-text-reversed {
    display: grid;
    grid-template-columns: 1fr 1fr;
    grid-column-gap: 20px;
    padding: 15px;
}

/*
 * Styling of your block in the CMS editor
 * Pattern: sw-cms-block-${block.name}-component
 */
.sw-cms-block-swag-image-text-reversed-component {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(195px, 1fr));
    grid-gap: 40px;
}

/*
 * Each slot will have an additional class
 * Pattern: sw-cms-slot-${slot.name}
 */
.sw-cms-block-swag-image-text-reversed-component .sw-cms-slot-left {
    
}

/*
 * Each slot will have an additional class
 * Pattern: sw-cms-slot-${slot.name}
 */
.sw-cms-block-swag-image-text-reversed-component .sw-cms-slot-right {

}
```

The DOM structure of the block in the CMS editor will look like this:

```html
<div class="sw-cms-block-swag-image-text-reversed-component">
    <div class="sw-cms-slot sw-cms-slot-left"></div>
    <div class="sw-cms-slot sw-cms-slot-right"></div>
</div>
```

## Defining slots

Each slot has a **unique** `name` and a `type` that refers to which element it shows.
All available elements can be found in [src/Administration/Resources/app/administration/src/module/sw-cms/elements](https://github.com/shopware/shopware/tree/trunk/src/Administration/Resources/app/administration/src/module/sw-cms/elements).
At a later point you will also be able to define custom elements but for now you can use the elements shipped by Shopware.

The `config` of a slot is very dynamic as it highly depends on which `type` you have chosen.
A good starting point to find out which elements require which configuration is each element's `index.js` in the corresponding directory in [src/Administration/Resources/app/administration/src/module/sw-cms/blocks](https://github.com/shopware/shopware/tree/trunk/src/Administration/Resources/app/administration/src/module/sw-cms/blocks).

## Registering blocks

Unlike adding blocks from a plugin, blocks provided from an app will be automatically registered during runtime - so all you need to take care of is to properly define and configure them.

## Storefront representation

Providing the Storefront representation of your blocks works very similarly as in the [plugin example](../../../plugins/content/cms/add-cms-block#storefront-representation).
In `Resources/views/storefront/block/` a Twig template matching the pattern `cms-block-${block.name}-component.html.twig` is expected.

So in this example, it's sufficient to simply extend the existing `image-text` element:

```twig
// <app root>/Resources/views/storefront/block/cms-block-swag-image-text-reversed-component.html.twig
{% sw_extends '@Storefront/storefront/block/cms-block-image-text.html.twig' %}
```

Styling of your blocks in the Storefront can then be done in `Resources/app/storefront/src/scss/base.scss`.

## Further reading

You can further take a look at the [CMS references](../../../../../resources/references/app-reference/cms-reference).

---

---
url: /docs/guides/plugins/apps/content/cms/add-custom-cms-blocks.md
---

# Add Custom CMS Blocks

::: info
This functionality is available starting with Shopware 6.4.4.0.
::: info

## Overview

You can [add custom CMS blocks](../../../plugins/content/cms/add-cms-block.md) using the plugin system. However, these will not be available in Shopware cloud stores.

New to Shopware's Shopping Experiences (CMS)? Start with the concept behind it:

## Prerequisites

This guide is based on our [App Base Guide](../../app-base-guide.md) and assumes you have already set up an app.

## Add CMS blocks from an app

Adding custom CMS blocks from an app works a bit differently than [adding them from a plugin](../../../plugins/content/cms/add-cms-block.md). Custom CMS blocks are added by providing a `cms.xml` in the `Resources/` directory of your app.

The basic directory structure looks as follows:

```text
├── Resources
│   ├── app
│   │   └── storefront
│   │       └── src
│   │           └── scss
│   │               └── base.scss
│   ├── cms
│   │   └── blocks
│   │       └── swag-image-text-reversed
│   │           ├── preview.html
│   │           └── styles.css
│   ├── views
│   │   └── storefront
│   │       └── block
│   │           └── cms-block-swag-image-text-reversed-component.html.twig
│   └── cms.xml
└── manifest.xml
```

Each CMS block defined within your `cms.xml` must have a directory matching the block's name in `Resources/cms/blocks/`. In those directories, you define your blocks for the CMS module in the Administration by supplying a `preview.html` file containing the template used to display a preview. Styling the preview in the sidebar and the component in the CMS editor can be done in `styles.css`.

::: info
Due to technical limitations, it's not possible to use templating engines (like Twig) or preprocessors (like Sass) for rendering and styling the preview.
:::

The Storefront representations of your blocks reside in `Resources/views/storefront/block/`.

## Defining blocks

As already mentioned above, and similar to an app's `manifest.xml`, CMS blocks also require a definition in `cms.xml`. In this example, we will define a custom CMS block that will extend the default block `image-text` and reverse its elements:

```xml
// <app root>/Resources/cms.xml
<?xml version="1.0" encoding="utf-8" ?>
<cms xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Cms/Schema/cms-1.0.xsd">
    <blocks>
        <block>
            <!-- A unique technical name for your block. We recommend using a shorthand prefix for your company, e.g., "Swag" for shopware AG. -->
            <name>swag-image-text-reversed</name>

            <!-- The category your block is associated with. See the XSD for available categories. -->
            <category>text-image</category>

            <!-- Your block's label which will be shown in the CMS module in the Administration. -->
            <label>Two columns, text &amp; boxed image</label>
            <label lang="de-DE">Zwei Spalten, Text &amp; gerahmtes Bild</label>

            <!-- The slots that your block holds, which again hold CMS elements. -->
            <slots>
                <!-- A slot requires a unique name and a type which refers to the CMS element it shows. Currently, app CMS blocks can only use CMS elements provided by Shopware. -->
                <slot name="left" type="text">
                    <!-- The slot requires some basic configuration. The following config-value elements highly depend on which element the slot holds. -->
                    <config>
                        <!-- The following config-value will be interpreted as 'verticalAlign: { source: "static", value: "top"}' in the JavaScript. -->
                        <config-value name="vertical-align" source="static" value="top"/>
                    </config>
                </slot>

                <slot name="right" type="image">
                    <config>
                        <config-value name="display-mode" source="static" value="auto"/>
                        <config-value name="vertical-align" source="static" value="top"/>
                    </config>
                </slot>
            </slots>

            <!-- Each block comes with a default configuration, which is pre-filled and customizable when adding a block to a section in the CMS module in the Administration. -->
            <default-config>
                <margin-top>20px</margin-top>
                <margin-right>20px</margin-right>
                <margin-bottom>20px</margin-bottom>
                <margin-left>20px</margin-left>
                <!-- The sizing mode of your block. Allowed values are "boxed" or "full_width". -->
                <sizing-mode>boxed</sizing-mode>
            </default-config>
        </block>
    </blocks>
</cms>
```

Let's have a look at how to configure a CMS block from your app's `cms.xml`:

`<name>` : A **unique** technical name for your block.

`<category>` : Blocks are divided into categories. Available categories can be found in the [plugin guide](../../../plugins/content/cms/add-cms-block.md#how-to-create-a-block-in-the-administration).

`<label>` : The **translatable** label will be shown in the Administration.

`<default-config>` : Some default configuration for the block.

`<slots>` : Each block holds slots that configure which element they show.

The full CMS reference is available here:

### Block preview

The preview template for `swag-image-text-reversed` looks like this:

```html
// <app root>/Resources/cms/blocks/swag-image-text-reversed/preview.html
<div class="sw-cms-preview-swag-image-text-reversed">
    <div>
        <h2>Lorem ipsum dolor</h2>
        <p>Lorem ipsum dolor sit amet, consetetur sadipscing elitr.</p>
    </div>

    <!-- Alternatively, you might e.g. also use a base64 encoded preview image instead of an external resource. -->
    <img src="https://example.com/preview.jpg" alt="Preview image">
</div>
```

::: info
For security reasons, you can only use pure HTML in the preview template.
The template will be sanitized from possibly malicious tags like `<script>` or attributes like `:src="assetFilter('/administration/static/img/cms/preview_mountain_small.jpg')"`.
:::

The styling of the preview looks as follows:

```css
// <app root>/Resources/cms/blocks/swag-image-text-reversed/styles.css
/* 
 * Styling of your block preview in the CMS sidebar
 */
.sw-cms-preview-swag-image-text-reversed {
    display: grid;
    grid-template-columns: 1fr 1fr;
    grid-column-gap: 20px;
    padding: 15px;
}

/*
 * Styling of your block in the CMS editor
 * Pattern: sw-cms-block-${block.name}-component
 */
.sw-cms-block-swag-image-text-reversed-component {
    display: grid;
    grid-template-columns: repeat(auto-fit, minmax(195px, 1fr));
    grid-gap: 40px;
}

/*
 * Each slot will have an additional class
 * Pattern: sw-cms-slot-${slot.name}
 */
.sw-cms-block-swag-image-text-reversed-component .sw-cms-slot-left {
    
}

/*
 * Each slot will have an additional class
 * Pattern: sw-cms-slot-${slot.name}
 */
.sw-cms-block-swag-image-text-reversed-component .sw-cms-slot-right {

}
```

The DOM structure of the block in the CMS editor will look like this:

```html
<div class="sw-cms-block-swag-image-text-reversed-component">
    <div class="sw-cms-slot sw-cms-slot-left"></div>
    <div class="sw-cms-slot sw-cms-slot-right"></div>
</div>
```

## Defining slots

Each slot has a **unique** `name` and a `type` that refers to which element it shows.
All available elements can be found in [src/Administration/Resources/app/administration/src/module/sw-cms/elements](https://github.com/shopware/shopware/tree/trunk/src/Administration/Resources/app/administration/src/module/sw-cms/elements).
Currently, app CMS blocks defined via `cms.xml` can only use the elements shipped by Shopware. If you need a fully custom element with its own configuration UI and rendering logic, use the [Meteor Admin SDK approach](../../administration/add-cms-element-via-admin-sdk) instead.

The `config` of a slot is highly dynamic, as it depends heavily on the `type` you choose.
A good starting point for finding out which elements require which configuration is each element's `index.js` file in the corresponding directory in [src/Administration/Resources/app/administration/src/module/sw-cms/elements](https://github.com/shopware/shopware/tree/trunk/src/Administration/Resources/app/administration/src/module/sw-cms/elements).

## Registering blocks

Unlike adding blocks from a plugin, blocks provided from an app will be automatically registered during runtime - so all you need to take care of is to define and configure them properly.

## Storefront representation

Providing the Storefront representation of your blocks works very similarly to the [plugin example](../cms/add-custom-cms-blocks.md#storefront-representation).
In `Resources/views/storefront/block/`, a Twig template matching the pattern `cms-block-${block.name}-component.html.twig` is expected.

So in this example, it's sufficient to simply extend the existing `image-text` element:

```twig
// <app root>/Resources/views/storefront/block/cms-block-swag-image-text-reversed-component.html.twig
{% sw_extends '@Storefront/storefront/block/cms-block-image-text.html.twig' %}
```

Styling of your blocks in the Storefront can then be done in `Resources/app/storefront/src/scss/base.scss`.

## Further reading

You can further take a look at the [CMS references](../../../../../resources/references/app-reference/cms-reference.md).

---

---
url: /docs/v6.5/guides/plugins/plugins/administration/add-custom-component.md
---

# Add custom component

## Overview

Since the Shopware 6 Administration is using [VueJS](https://vuejs.org/) as its framework, it also supports creating custom components. This guide will teach you how to register your own custom component with your plugin.

In this example, you will create a component that will print a 'Hello world!' everywhere it's being used.

## Prerequisites

This guide **does not** explain how to create a new plugin for Shopware 6. Head over to our Plugin base guide to learn how to create a plugin at first:

If you want to work with entities in your custom component or page, it might be useful to take a look at how to create a custom entity guide first:

Especially if you want to add a new page for an own module, you should consider looking at the process on how to add a custom module first.

This way, you're able to start building your own module in the right order.

### Injecting into the Administration

Same as with all custom extensions of the Administration, the main entry point to extend the Administration via plugin is the `main.js` file. It has to be placed into a `<plugin root>/src/Resources/app/administration/src` directory in order to be found by Shopware 6.

## Creating a custom component

### Path to the component

Usually there's one question you have to ask yourself first: Will your new component be used as a `page` for your plugin's custom route, or is this going to be a component to be used by several other components, such as an element that prints 'Hello world' everywhere it's used? In order to properly structure your plugin's code and to be similar to the core structure, you have to answer this question first. If it's going to be used as page for a module, it should be placed here: `<plugin-root>/src/Resources/app/administration/src/module/<your module's name>/page/<your component name>`

Otherwise, if it's going to be a general component to be used by other components, the following will be the proper path. For this example, this component scenario is used. `<plugin-root>/src/Resources/app/administration/src/component/<name of your plugin>/<name of your component>`

::: info
Using this path is **not** a hard requirement, but rather a recommendation. This way, third party developers having a glance at your code will get used to it real quick, because you stuck to Shopware 6's core conventions.
:::

Since the latter example is being used, this is the path being created in the plugin now: `<plugin-root>/src/Resources/app/administration/src/component/custom-component/hello-world`

### Import your custom component via main.js file

In the directory mentioned above, create a new file `index.js`. We will get you covered with more information about it later. Now import your custom component using your plugin's `main.js` file:

You can use the `Shopware.Component.register` method to register your component. This method expects a name and a function that will import your component. By using a dynamic import here, your component will be loaded asynchronously when it's being used.

```javascript
// <plugin root>/src/Resources/app/administration/src
Shopware.Component.register('hello-world', () => import('./component/custom-component/hello-world'));
```

To import your component synchronously, you need to import it directly in the `main.js` file. The component registration
will be done in the `index.js` file of your component.

```javascript
// <plugin root>/src/Resources/app/administration/src
import './component/custom-component/hello-world';
```

### Index.js as main entry point for this component

Head back to the `index.js` file, this one will be the most important for your component.

The structure of this file depends on the type of your component. If it loads synchronously, you need to register your component directly in this file. If it loads asynchronously, you can just export the component and register it in the `main.js` file.

```javascript
export default Shopware.Component.wrapComponentConfig({
    // Configuration here
});
```

```javascript
// <plugin-root>/src/Resources/app/administration/src/component/custom-component/hello-world
Shopware.Component.register('hello-world', {
    // Configuration here
});
```

A component's template is being defined by using the `template` property. For this short example, the template will be defined inline. An example for a bigger template will also be provided later on this page.

```javascript
// <plugin-root>/src/Resources/app/administration/src/component/custom-component/hello-world
export default Shopware.Component.wrapComponentConfig('hello-world', {
    template: '<h2>Hello world!</h2>'
});
```

That's it. You can now use your component like this `<hello-world></hello-world>` in any other template in the Administration.

### Long template example

It's quite uncommon to have such a small template example and you don't want to define huge templates inside a javascript file. For this case, just create a new template file in your component's directory, which should be named after your component. For this example `hello-world.html.twig` is used.

Now simply import this file in your component's JS file and use the variable for your property.

```javascript
// <plugin-root>/src/Resources/app/administration/src/component/custom-component/hello-world.html.twig
import template from 'hello-world.html.twig';

export default Shopware.Component.wrapComponentConfig('hello-world', {
    template: template
});
```

In the core code, you will find another syntax for the same result though:

```javascript
// <plugin-root>/src/Resources/app/administration/src/component/custom-component/hello-world.html.twig
import template from 'hello-world.html.twig';

export default Shopware.Component.wrapComponentConfig('hello-world', {
    template
});
```

This is a [shorthand](https://eslint.org/docs/latest/rules/object-shorthand), which can only be used if the variable is named exactly like the property.

## Next steps

You've now added a custom component, including a little template. However, there's more to discover here.

* [More about templates](writing-templates)
* [Add some styling to your component](add-custom-styles)
* [Use shortcuts for your component](add-shortcuts)

Furthermore, what about [customizing other components](customizing-components), instead of creating new ones?

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/administration/module-component-management/add-custom-component.md
---

# Add custom component

## Overview

Since the Shopware 6 Administration is using [VueJS](https://vuejs.org/) as its framework, it also supports creating custom components. This guide will teach you how to register your own custom component with your plugin.

In this example, you will create a component that will print a 'Hello world!' everywhere it's being used.

## Prerequisites

This guide **does not** explain how to create a new plugin for Shopware 6. Head over to our Plugin base guide to learn how to create a plugin at first:

If you want to work with entities in your custom component or page, it might be useful to take a look at how to create a custom entity guide first:

Especially if you want to add a new page for an own module, you should consider looking at the process on how to add a custom module first.

This way, you're able to start building your own module in the right order.

### Injecting into the Administration

Same as with all custom extensions of the Administration, the main entry point to extend the Administration via plugin is the `main.js` file. It has to be placed into a `<plugin root>/src/Resources/app/administration/src` directory in order to be found by Shopware 6.

## Creating a custom component

### Path to the component

Usually there's one question you have to ask yourself first: Will your new component be used as a `page` for your plugin's custom route, or is this going to be a component to be used by several other components, such as an element that prints 'Hello world' everywhere it's used? In order to properly structure your plugin's code and to be similar to the core structure, you have to answer this question first. If it's going to be used as page for a module, it should be placed here: `<plugin-root>/src/Resources/app/administration/src/module/<your module's name>/page/<your component name>`

Otherwise, if it's going to be a general component to be used by other components, the following will be the proper path. For this example, this component scenario is used. `<plugin-root>/src/Resources/app/administration/src/component/<name of your plugin>/<name of your component>`

::: info
Using this path is **not** a hard requirement, but rather a recommendation. This way, third party developers having a glance at your code will get used to it real quick, because you stuck to Shopware 6's core conventions.
:::

Since the latter example is being used, this is the path being created in the plugin now: `<plugin-root>/src/Resources/app/administration/src/component/custom-component/hello-world`

### Import your custom component via main.js file

In the directory mentioned above, create a new file `index.js`. We will get you covered with more information about it later. Now import your custom component using your plugin's `main.js` file:

You can use the `Shopware.Component.register` method to register your component. This method expects a name and a function that will import your component. By using a dynamic import here, your component will be loaded asynchronously when it's being used.

```javascript
// <plugin root>/src/Resources/app/administration/src
Shopware.Component.register('hello-world', () => import('./component/custom-component/hello-world'));
```

To import your component synchronously, you need to import it directly in the `main.js` file. The component registration
will be done in the `index.js` file of your component.

```javascript
// <plugin root>/src/Resources/app/administration/src
import './component/custom-component/hello-world';
```

### Index.js as main entry point for this component

Head back to the `index.js` file, this one will be the most important for your component.

The structure of this file depends on the type of your component. If it loads synchronously, you need to register your component directly in this file. If it loads asynchronously, you can just export the component and register it in the `main.js` file.

```javascript
export default Shopware.Component.wrapComponentConfig({
    // Configuration here
});
```

```javascript
// <plugin-root>/src/Resources/app/administration/src/component/custom-component/hello-world
Shopware.Component.register('hello-world', {
    // Configuration here
});
```

A component's template is being defined by using the `template` property. For this short example, the template will be defined inline. An example for a bigger template will also be provided later on this page.

```javascript
// <plugin-root>/src/Resources/app/administration/src/component/custom-component/hello-world
export default Shopware.Component.wrapComponentConfig({
    template: '<h2>Hello world!</h2>'
});
```

That's it. You can now use your component like this `<hello-world></hello-world>` in any other template in the Administration.

### Long template example

It's quite uncommon to have such a small template example and you don't want to define huge templates inside a javascript file. For this case, just create a new template file in your component's directory, which should be named after your component. For this example `hello-world.html.twig` is used.

Now simply import this file in your component's JS file and use the variable for your property.

```javascript
// <plugin-root>/src/Resources/app/administration/src/component/custom-component/hello-world.html.twig
import template from 'hello-world.html.twig';

export default Shopware.Component.wrapComponentConfig('hello-world', {
    template: template
});
```

In the core code, you will find another syntax for the same result though:

```javascript
// <plugin-root>/src/Resources/app/administration/src/component/custom-component/hello-world.html.twig
import template from 'hello-world.html.twig';

export default Shopware.Component.wrapComponentConfig('hello-world', {
    template
});
```

This is a [shorthand](https://eslint.org/docs/latest/rules/object-shorthand), which can only be used if the variable is named exactly like the property.

## Next steps

You've now added a custom component, including a little template. However, there's more to discover here.

* [More about templates](../templates-styling/writing-templates.md)
* [Add some styling to your component](../templates-styling/add-custom-styles.md)
* [Use shortcuts for your component](../advanced-configuration/add-shortcuts.md)

Furthermore, what about [customizing other components](customizing-components.md), instead of creating new ones?

---

---
url: >-
  /docs/guides/plugins/plugins/administration/module-component-management/add-custom-component.md
---

# Add Custom Components

## Overview

Since the Shopware 6 Administration is using [VueJS](https://vuejs.org/) as its framework, it also supports creating custom components. This guide will teach you how to register your own custom component with your plugin.

In this example, you will create a component that will print a 'Hello world!' everywhere it's being used.

## Prerequisites

This guide **does not** explain how to create a new plugin for Shopware 6. Head over to our Plugin base guide to learn how to create a plugin at first:

If you want to work with entities in your custom component or page, it might be useful to take a look at how to create a custom entity guide first:

Especially if you want to add a new page for an own module, you should consider looking at the process on how to add a custom module first.

This way, you're able to start building your own module in the right order.

### Injecting into the Administration

Same as with all custom extensions of the Administration, the main entry point to extend the Administration via plugin is the `main.js` file. It has to be placed into a `<plugin root>/src/Resources/app/administration/src` directory in order to be found by Shopware 6.

## Creating a custom component

### Path to the component

Usually there's one question you have to ask yourself first: Will your new component be used as a `page` for your plugin's custom route, or is this going to be a component to be used by several other components, such as an element that prints 'Hello world' everywhere it's used? In order to properly structure your plugin's code and to be similar to the core structure, you have to answer this question first. If it's going to be used as page for a module, it should be placed here: `<plugin-root>/src/Resources/app/administration/src/module/<your module's name>/page/<your component name>`

Otherwise, if it's going to be a general component to be used by other components, the following will be the proper path. For this example, this component scenario is used. `<plugin-root>/src/Resources/app/administration/src/component/<name of your plugin>/<name of your component>`

::: info
Using this path is **not** a hard requirement, but rather a recommendation. This way, third party developers having a glance at your code will get used to it real quick, because you stuck to Shopware 6's core conventions.
:::

Since the latter example is being used, this is the path being created in the plugin now: `<plugin-root>/src/Resources/app/administration/src/component/custom-component/hello-world`

### Import your custom component via main.js file

In the directory mentioned above, create a new file `index.js`. We will get you covered with more information about it later. Now import your custom component using your plugin's `main.js` file:

You can use the `Shopware.Component.register` method to register your component. This method expects a name and a function that will import your component. By using a dynamic import here, your component will be loaded asynchronously when it's being used.

```javascript
// <plugin root>/src/Resources/app/administration/src
Shopware.Component.register('hello-world', () => import('./component/custom-component/hello-world'));
```

To import your component synchronously, you need to import it directly in the `main.js` file. The component registration
will be done in the `index.js` file of your component.

```javascript
// <plugin root>/src/Resources/app/administration/src
import './component/custom-component/hello-world';
```

### Index.js as main entry point for this component

Head back to the `index.js` file, this one will be the most important for your component.

The structure of this file depends on the type of your component. If it loads synchronously, you need to register your component directly in this file. If it loads asynchronously, you can just export the component and register it in the `main.js` file.

```javascript
export default Shopware.Component.wrapComponentConfig({
    // Configuration here
});
```

```javascript
// <plugin-root>/src/Resources/app/administration/src/component/custom-component/hello-world
Shopware.Component.register('hello-world', {
    // Configuration here
});
```

A component's template is being defined by using the `template` property. For this short example, the template will be defined inline. An example for a bigger template will also be provided later on this page.

```javascript
// <plugin-root>/src/Resources/app/administration/src/component/custom-component/hello-world
export default Shopware.Component.wrapComponentConfig({
    template: '<h2>Hello world!</h2>'
});
```

That's it. You can now use your component like this `<hello-world></hello-world>` in any other template in the Administration.

### Long template example

It's quite uncommon to have such a small template example and you don't want to define huge templates inside a javascript file. For this case, just create a new template file in your component's directory, which should be named after your component. For this example `hello-world.html.twig` is used.

Now simply import this file in your component's JS file and use the variable for your property.

```javascript
// <plugin-root>/src/Resources/app/administration/src/component/custom-component/hello-world.html.twig
import template from 'hello-world.html.twig';

export default Shopware.Component.wrapComponentConfig('hello-world', {
    template: template
});
```

In the core code, you will find another syntax for the same result though:

```javascript
// <plugin-root>/src/Resources/app/administration/src/component/custom-component/hello-world.html.twig
import template from 'hello-world.html.twig';

export default Shopware.Component.wrapComponentConfig('hello-world', {
    template
});
```

This is a [shorthand](https://eslint.org/docs/latest/rules/object-shorthand), which can only be used if the variable is named exactly like the property.

## Next steps

You've now added a custom component, including a little template. However, there's more to discover here.

* [More about templates](../templates-styling/writing-templates.md)
* [Add some styling to your component](../templates-styling/add-custom-styles.md)
* [Use shortcuts for your component](../advanced-configuration/add-shortcuts.md)

Furthermore, what about [customizing other components](customizing-components.md), instead of creating new ones?

---

---
url: /docs/guides/plugins/plugins/storefront/controllers/add-custom-controller.md
---

# Add Custom Controller

## Overview

In this guide you will learn how to create a custom Storefront controller.

## Prerequisites

In order to add your own controller for your plugin, you first need a plugin as base.
Therefore, you can refer to the [Plugin Base Guide](../../plugin-base-guide.md).

::: info
Refer to this video on **[Common Storefront controller tasks](https://www.youtube.com/watch?v=5eXXNh4cQG0)** explaining the basics about Storefront controllers.
Available also on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

## Adding custom Storefront controller

### Storefront Controller class example

First of all we have to create a new controller which extends from the `StorefrontController` class.
A controller is also just a service which can be registered via the service container.
Furthermore, we have to define our `Route` with `defaults` and `_routeScope` via attributes, it is used to define which domain a route is part of and **needs to be set for every route**.
In our case the scope is `storefront`.

::: info
Prior to Shopware 6.4.11.0 the `_routeScope` was configured by a dedicated annotation: `@RouteScope`.
This way of defining the route scope is deprecated for the 6.5 major version.
:::

Go ahead and create a new file `ExampleController.php` in the directory `<plugin root>/src/Storefront/Controller/`.

::: code-group

```php [PLUGIN_ROOT/src/Storefront/Controller/ExampleController.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

use Shopware\Core\PlatformRequest;
use Shopware\Storefront\Framework\Routing\StorefrontRouteScope;
use Shopware\Storefront\Controller\StorefrontController;
use Symfony\Component\Routing\Attribute\Route;

#[Route(defaults: [PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [StorefrontRouteScope::ID]])]
class ExampleController extends StorefrontController
{
}
```

:::

Now we can create a new example method with a `Route` attribute which has to contain our route, in this case it will be `/example`.
The route defines how our new method will be accessible.

Below you can find an example implementation of a controller method including a route, where we render an `example.html.twig` template file with a template variable `example`.

::: code-group

```php [PLUGIN_ROOT/src/Storefront/Controller/ExampleController.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

use Shopware\Core\PlatformRequest;
use Shopware\Storefront\Framework\Routing\StorefrontRouteScope;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Controller\StorefrontController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

#[Route(defaults: [PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [StorefrontRouteScope::ID]])]
class ExampleController extends StorefrontController
{
    #[Route(path: '/example', name: 'frontend.example.example', methods: ['GET'])]
    public function showExample(): Response
    {
        return $this->renderStorefront('@SwagBasicExample/storefront/page/example.html.twig', [
            'example' => 'Hello world'
        ]);
    }
}
```

:::

The name of the method does not really matter, but it should somehow fit its purpose.
More important is the `Route` attribute, that points to the route `/example`.
Also note its name, which is also quite important.
Make sure to use prefixes `frontend`, `widgets`, `payment`, `api` or `store-api` here, depending on what your route does.
The first three prefixes are necessary to identify the route as a Storefront route.
If you do not want to use the prefixes, you can [add allowed route names via configuration](#allow-custom-route-names-as-storefront-routes).
Inside the method, we're using the method `renderStorefront` to render a twig template file in addition with the template variable `example`, which contains `Hello world`.
This template variable will be usable in the rendered template file.
The method `renderStorefront` then returns a `Response`, as every routed controller method has to.

It is also possible to define the `_routeScope` per route.

::: info
Prior to Shopware 6.4.11.0 the `_routeScope` was configured by a dedicated annotation: `@RouteScope`.
This way of defining the route-scope is deprecated for the 6.5 major version.
:::

::: code-group

```php [PLUGIN_ROOT/src/Storefront/Controller/ExampleController.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

use Shopware\Core\PlatformRequest;
use Shopware\Storefront\Framework\Routing\StorefrontRouteScope;
use Shopware\Storefront\Controller\StorefrontController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

#[Route(defaults: [PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [StorefrontRouteScope::ID]])]
class ExampleController extends StorefrontController
{
    #[Route(path: '/example', name: 'frontend.example.example', methods: ['GET'], defaults: [PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [StorefrontRouteScope::ID]])]
    public function showExample(): Response
    {
        ...
    }
}
```

:::

### Services.php example

Next, we need to register our controller in the DI-container and make it public.

::: code-group

```php [PLUGIN_ROOT/src/Resources/config/services.php]
<?php declare(strict_types=1);

use Swag\BasicExample\Storefront\Controller\ExampleController;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(ExampleController::class)
        ->public()
        ->call('setContainer', [service('service_container')]);
};
```

:::

Please also note the `call` method, which is necessary in order to set the DI container to the controller.

### Routes.php example

Once we've registered our new controller, we have to tell Shopware how we want it to search for new routes in our plugin.
This is done with a `routes.php` file at `<plugin root>/src/Resources/config/` location.
Take a look at the official [Symfony documentation](https://symfony.com/doc/current/routing.html) about routes and how they are registered.

::: code-group

```php [PLUGIN_ROOT/src/Resources/config/routes.php]
<?php declare(strict_types=1);

use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return static function (RoutingConfigurator $routes): void {
    $routes->import('../../Storefront/Controller/*Controller.php', 'attribute');
};
```

:::

### Adding template

Now we registered our controller and Shopware indexes the route, but the template file, that is supposed to be rendered, is still missing.
Let's change that now.

As previously mentioned, the code will try to render an `index.html.twig` file.
Thus, we have to create an `index.html.twig` in the `<plugin root>/src/Resources/views/storefront/page/example` directory, as defined in our controller.
Below you can find an example, where we extend from the template `base.html.twig` and override the block `base_content`.
In our [Customize templates](../templates/customize-templates.md) guide, you can learn more about customizing templates.

::: code-group

```twig [PLUGIN_ROOT/src/Resources/views/storefront/page/example.html.twig]
{% sw_extends '@Storefront/storefront/base.html.twig' %}

{% block base_content %}
    <h1>Our example controller!</h1>
{% endblock %}
```

:::

### Request and Context

If necessary, we can access the `Request` and `SalesChannelContext` instances in our controller method.

Here's an example:

::: code-group

```php [PLUGIN_ROOT/src/Storefront/Controller/ExampleController.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

use Shopware\Core\PlatformRequest;
use Shopware\Storefront\Framework\Routing\StorefrontRouteScope;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Controller\StorefrontController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

#[Route(defaults: [PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [StorefrontRouteScope::ID]])]
class ExampleController extends StorefrontController
{
    #[Route(path: '/example', name: 'frontend.example.example', methods: ['GET'])]
    public function showExample(Request $request, SalesChannelContext $context): Response
    {
        ...
    }
}
```

:::

### Allow custom route names as Storefront routes

::: info
This feature is available since Shopware 6.7.2.0
:::

To allow custom route names without a `frontend`, `widgets` or `payment` prefix, add the following configuration file to your plugin.

::: code-group

```yaml [PLUGIN_ROOT]/src/Resources/config/packages/storefront.yaml]
storefront:
    router:
        allowed_routes:
            - swag.test.foo-bar

```

:::

Make sure, this file is loaded during the container build process.
Overwrite the `build` method in your plugin base class to load the configuration files from the `Resources/config` directory.

::: code-group

```php [PLUGIN_ROOT/src/SwagBasicExample.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample;

use Shopware\Core\Framework\Plugin;
use Symfony\Component\Config\FileLocator;
use Symfony\Component\Config\Loader\DelegatingLoader;
use Symfony\Component\Config\Loader\LoaderResolver;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\DependencyInjection\Loader\DirectoryLoader;
use Symfony\Component\DependencyInjection\Loader\GlobFileLoader;
use Symfony\Component\DependencyInjection\Loader\YamlFileLoader;

class SwagBasicExample extends Plugin
{
    public function build(ContainerBuilder $container): void
    {
        parent::build($container);

        $locator = new FileLocator('Resources/config');

        $resolver = new LoaderResolver([
            new YamlFileLoader($container, $locator),
            new GlobFileLoader($container, $locator),
            new DirectoryLoader($container, $locator),
        ]);

        $configLoader = new DelegatingLoader($resolver);

        $confDir = \rtrim($this->getPath(), '/') . '/Resources/config';

        $configLoader->load($confDir . '/{packages}/*.yaml', 'glob');
    }
}
```

:::

Now you can use the route name `swag.test.foo-bar` in your controller without the need for a prefix.

```php
#[Route(path: '/example', name: 'swag.test.foo-bar', methods: ['GET'])]
public function showExample(Request $request, SalesChannelContext $context): Response
{
    //...
}
```

## Next steps

Since you've already created a controller now, which is also part of creating a so-called "page" in Shopware, you might want to head over to our guide about [creating a page](../controllers/add-custom-page.md).

---

---
url: /docs/v6.5/guides/plugins/plugins/storefront/add-custom-controller.md
---

# Add Custom Controller

## Overview

In this guide you will learn how to create a custom Storefront controller.

## Prerequisites

In order to add your own controller for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide).

::: info
Refer to this video on **[Common Storefront controller tasks](https://www.youtube.com/watch?v=5eXXNh4cQG0)** explaining the basics about Storefront controllers. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

## Adding custom Storefront controller

### Storefront Controller class example

First of all we have to create a new controller which extends from the `StorefrontController` class. A controller is also just a service which can be registered via the service container. Furthermore, we have to define our `Route` with `defaults` and `_routeScope` via annotation, it is used to define which domain a route is part of and **needs to be set for every route**. In our case the scope is `storefront`.

::: info
Prior to Shopware 6.4.11.0 the `_routeScope` was configured by a dedicated annotation: `@RouteScope`. This way of defining the route scope is deprecated for the 6.5 major version.
:::

Go ahead and create a new file `ExampleController.php` in the directory `<plugin root>/src/Storefront/Controller/`.

```php
// <plugin root>/src/Storefront/Controller/ExampleController.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

use Shopware\Storefront\Controller\StorefrontController;

#[Route(defaults: ['_routeScope' => ['storefront']])]
class ExampleController extends StorefrontController
{
}
```

Now we can create a new example method with a `Route` annotation which has to contain our route, in this case it will be `/example`. The route defines how our new method will be accessible.

Below you can find an example implementation of a controller method including a route, where we render an `example.html.twig` template file with a template variable `example`.

```php
// <plugin root>/src/Storefront/Controller/ExampleController.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Controller\StorefrontController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

#[Route(defaults: ['_routeScope' => ['storefront']])]
class ExampleController extends StorefrontController
{
    #[Route(path: '/example', name: 'frontend.example.example', methods: ['GET'])]
    public function showExample(): Response
    {
        return $this->renderStorefront('@SwagBasicExample/storefront/page/example.html.twig', [
            'example' => 'Hello world'
        ]);
    }
}
```

The name of the method does not really matter, but it should somehow fit its purpose. More important is the `Route` annotation, that points to the route `/example`. Also note its name, which is also quite important. Make sure to use prefixes `frontend`, `widgets`, `payment`, `api` or `store-api` here, depending on what your route does. Inside the method, we're using the method `renderStorefront` to render a twig template file in addition with the template variable `example`, which contains `Hello world`. This template variable will be usable in the rendered template file. The method `renderStorefront` then returns a `Response`, as every routed controller method has to.

It is also possible to define the `_routeScope` per route.

::: info
Prior to Shopware 6.4.11.0 the `_routeScope` was configured by a dedicated annotation: `@RouteScope`. This way of defining the route-scope is deprecated for the 6.5 major version.
:::

```php
// <plugin root>/src/Storefront/Controller/ExampleController.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

use Shopware\Storefront\Controller\StorefrontController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

#[Route(defaults: ['_routeScope' => ['storefront']])]
class ExampleController extends StorefrontController
{
    #[Route(path: '/example', name: 'frontend.example.example', methods: ['GET'], defaults: ['_routeScope' => 'storefront'])]
    public function showExample(): Response
    {
        ...
    }
}
```

### Services.xml example

Next, we need to register our controller in the DI-container and make it public.

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services" 
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Storefront\Controller\ExampleController" public="true">
            <call method="setContainer">
                <argument type="service" id="service_container"/>
            </call>
            <call method="setTwig">
                <argument type="service" id="twig"/>
            </call>
        </service>
    </services>
</container>
```

Please also note the `call` tag, which is necessary in order to set the DI container to the controller.

### Routes.xml example

Once we‘ve registered our new controller, we have to tell Shopware how we want it to search for new routes in our plugin. This is done with a `routes.xml` file at `<plugin root>/src/Resources/config/` location. Have a look at the official [Symfony documentation](https://symfony.com/doc/current/routing.html) about routes and how they are registered.

```xml
// <plugin root>/src/Resources/config/routes.xml
<?xml version="1.0" encoding="UTF-8" ?>
<routes xmlns="http://symfony.com/schema/routing"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://symfony.com/schema/routing
        https://symfony.com/schema/routing/routing-1.0.xsd">

    <import resource="../../Storefront/Controller/**/*Controller.php" type="annotation" />
</routes>
```

### Adding template

Now we registered our controller and Shopware indexes the route, but the template file, that is supposed to be rendered, is still missing. Let's change that now.

As previously mentioned, the code will try to render an `index.html.twig` file. Thus we have to create an `index.html.twig` in the `<plugin root>/src/Resources/views/storefront/page/example` directory, as defined in our controller. Below you can find an example, where we extend from the template `base.html.twig` and override the block `base_content`. In our [Customize templates](customize-templates) guide, you can learn more about customizing templates.

```twig
// <plugin root>/src/Resources/views/storefront/page/example.html.twig
{% sw_extends '@Storefront/storefront/base.html.twig' %}

{% block base_content %}
    <h1>Our example controller!</h1>
{% endblock %}
```

### Request and Context

If necessary, we can access the `Request` and `SalesChannelContext` instances in our controller method.

Here's an example:

```php
// <plugin root>/src/Storefront/Controller/ExampleController.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Controller\StorefrontController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

#[Route(defaults: ['_routeScope' => ['storefront']])]
class ExampleController extends StorefrontController
{    
    #[Route(path: '/example', name: 'frontend.example.example', methods: ['GET'])]
    public function showExample(Request $request, SalesChannelContext $context): Response
    {
        ...
    }
}
```

## Next steps

Since you've already created a controller now, which is also part of creating a so called "page" in Shopware, you might want to head over to our guide about [creating a page](add-custom-page).

---

---
url: /docs/v6.6/guides/plugins/plugins/storefront/add-custom-controller.md
---

# Add Custom Controller

## Overview

In this guide you will learn how to create a custom Storefront controller.

## Prerequisites

In order to add your own controller for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide).

::: info
Refer to this video on **[Common Storefront controller tasks](https://www.youtube.com/watch?v=5eXXNh4cQG0)** explaining the basics about Storefront controllers. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

## Adding custom Storefront controller

### Storefront Controller class example

First of all we have to create a new controller which extends from the `StorefrontController` class. A controller is also just a service which can be registered via the service container. Furthermore, we have to define our `Route` with `defaults` and `_routeScope` via attributes, it is used to define which domain a route is part of and **needs to be set for every route**. In our case the scope is `storefront`.

::: info
Prior to Shopware 6.4.11.0 the `_routeScope` was configured by a dedicated annotation: `@RouteScope`. This way of defining the route scope is deprecated for the 6.5 major version.
:::

Go ahead and create a new file `ExampleController.php` in the directory `<plugin root>/src/Storefront/Controller/`.

```php
// <plugin root>/src/Storefront/Controller/ExampleController.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

use Shopware\Storefront\Controller\StorefrontController;
use Symfony\Component\Routing\Attribute\Route;

#[Route(defaults: ['_routeScope' => ['storefront']])]
class ExampleController extends StorefrontController
{
}
```

Now we can create a new example method with a `Route` attribute which has to contain our route, in this case it will be `/example`. The route defines how our new method will be accessible.

Below you can find an example implementation of a controller method including a route, where we render an `example.html.twig` template file with a template variable `example`.

```php
// <plugin root>/src/Storefront/Controller/ExampleController.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Controller\StorefrontController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

#[Route(defaults: ['_routeScope' => ['storefront']])]
class ExampleController extends StorefrontController
{
    #[Route(path: '/example', name: 'frontend.example.example', methods: ['GET'])]
    public function showExample(): Response
    {
        return $this->renderStorefront('@SwagBasicExample/storefront/page/example.html.twig', [
            'example' => 'Hello world'
        ]);
    }
}
```

The name of the method does not really matter, but it should somehow fit its purpose. More important is the `Route` attribute, that points to the route `/example`. Also note its name, which is also quite important. Make sure to use prefixes `frontend`, `widgets`, `payment`, `api` or `store-api` here, depending on what your route does. Inside the method, we're using the method `renderStorefront` to render a twig template file in addition with the template variable `example`, which contains `Hello world`. This template variable will be usable in the rendered template file. The method `renderStorefront` then returns a `Response`, as every routed controller method has to.

It is also possible to define the `_routeScope` per route.

::: info
Prior to Shopware 6.4.11.0 the `_routeScope` was configured by a dedicated annotation: `@RouteScope`. This way of defining the route-scope is deprecated for the 6.5 major version.
:::

```php
// <plugin root>/src/Storefront/Controller/ExampleController.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

use Shopware\Storefront\Controller\StorefrontController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

#[Route(defaults: ['_routeScope' => ['storefront']])]
class ExampleController extends StorefrontController
{
    #[Route(path: '/example', name: 'frontend.example.example', methods: ['GET'], defaults: ['_routeScope' => ['storefront']])]
    public function showExample(): Response
    {
        ...
    }
}
```

### Services.xml example

Next, we need to register our controller in the DI-container and make it public.

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services" 
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Storefront\Controller\ExampleController" public="true">
            <call method="setContainer">
                <argument type="service" id="service_container"/>
            </call>
            <call method="setTwig">
                <argument type="service" id="twig"/>
            </call>
        </service>
    </services>
</container>
```

Please also note the `call` tag, which is necessary in order to set the DI container to the controller.

### Routes.xml example

Once we‘ve registered our new controller, we have to tell Shopware how we want it to search for new routes in our plugin. This is done with a `routes.xml` file at `<plugin root>/src/Resources/config/` location. Have a look at the official [Symfony documentation](https://symfony.com/doc/current/routing.html) about routes and how they are registered.

```xml
// <plugin root>/src/Resources/config/routes.xml
<?xml version="1.0" encoding="UTF-8" ?>
<routes xmlns="http://symfony.com/schema/routing"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://symfony.com/schema/routing
        https://symfony.com/schema/routing/routing-1.0.xsd">

    <import resource="../../Storefront/Controller/*Controller.php" type="attribute" />
</routes>
```

### Adding template

Now we registered our controller and Shopware indexes the route, but the template file, that is supposed to be rendered, is still missing. Let's change that now.

As previously mentioned, the code will try to render an `index.html.twig` file. Thus we have to create an `index.html.twig` in the `<plugin root>/src/Resources/views/storefront/page/example` directory, as defined in our controller. Below you can find an example, where we extend from the template `base.html.twig` and override the block `base_content`. In our [Customize templates](customize-templates) guide, you can learn more about customizing templates.

```twig
// <plugin root>/src/Resources/views/storefront/page/example.html.twig
{% sw_extends '@Storefront/storefront/base.html.twig' %}

{% block base_content %}
    <h1>Our example controller!</h1>
{% endblock %}
```

### Request and Context

If necessary, we can access the `Request` and `SalesChannelContext` instances in our controller method.

Here's an example:

```php
// <plugin root>/src/Storefront/Controller/ExampleController.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Controller\StorefrontController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

#[Route(defaults: ['_routeScope' => ['storefront']])]
class ExampleController extends StorefrontController
{    
    #[Route(path: '/example', name: 'frontend.example.example', methods: ['GET'])]
    public function showExample(Request $request, SalesChannelContext $context): Response
    {
        ...
    }
}
```

## Next steps

Since you've already created a controller now, which is also part of creating a so called "page" in Shopware, you might want to head over to our guide about [creating a page](add-custom-page).

---

---
url: /docs/v6.5/guides/plugins/plugins/administration/search-custom-data.md
---

# Add custom data to the search

## Overview

When developing a customization that has a frequently visited entity listing you're able to make use of an interesting opportunity: You can enable the user to take a shortcut finding his desired entry using the global search.

There are two different ways how the global search works:

* Global search without type specification
* Typed global search

They only differ in the API they use and get displayed in a slightly different way.

::: warning
Think twice about adding this shortcut because if every plugin adds their own search tag it gets cluttered.
:::

## Prerequisites

For this guide, it's necessary to have a running Shopware 6 instance and full access to both the files and a running plugin. See our plugin page guide to learn how to create your own plugins.

In addition, you need a custom entity to add to the search to begin with. Head over to the following guide to learn how to achieve that:

## Support custom entity via search API

To support an entity in the untyped global search the definition in the symfony container needs the tag `shopware.composite_search.definition`. The priority of the tag defines the order in the search order.

The typed global search needs an instance of the JavaScript class `ApiService` with the key of the entity in camelcase suffixed with `Service`. E.g. The service key is `yourCustomSearchService` when requesting a service for `your_custom_search`. Every entity definition gets automatically an instance in the injection container but can be overridden so there is no additional work needed.

## Support in the Administration UI

### Add search tag

The search tag displays the entity type that is used in the typed search and is a clickable button to switch from the untyped to the typed search. In order to add the tag, a service decorator is used to add a type to the `searchTypeService`:

```javascript
const { Application } = Shopware;

Application.addServiceProviderDecorator('searchTypeService', searchTypeService => {
    searchTypeService.upsertType('foo_bar', {
        entityName: 'foo_bar',
        entityService: 'fooBarService',
        placeholderSnippet: 'foo-bar.general.placeholderSearchBar',
        listingRoute: 'foo.bar.index'
    });

    return searchTypeService;
});
```

Let's take a closer look on how this decorator is used:

* The key and `entityName` is used as the same to change also existing types.
* The `entityService` is used for the typed search.
* This service can be overridden with an own implementation for customization.
* The `placeholderSnippet` is a translation key that is shown when no search term is entered.
* The `listingRoute` is used to show a link to continue the search in the module specific listing view.

### Add the search result item

By default, the search bar does not know how to display the result items, so a current search request will not show any result. In order to declare a search result view the `sw-search-bar-item` template has to be altered as seen below, starting with the template:

```twig
// <plugin root>/src/Resources/app/administration/src/app/component/structure/sw-search-bar-item/sw-search-bar-item.html.twig
{% block sw_search_bar_item_cms_page %}
    {% parent %}

    <router-link v-else-if="type === 'foo_bar'"
                 v-bind:to="{ name: 'foo.bar.detail', params: { id: item.id } }"
                 ref="routerLink"
                 class="sw-search-bar-item__link">
        {% block sw_search_bar_item_foo_bar_label %}
            <span class="sw-search-bar-item__label">
                <sw-highlight-text v-bind:searchTerm="searchTerm"
                                   v-bind:text="item.name">
                </sw-highlight-text>
            </span>
        {% endblock %}
    </router-link>
{% endblock %}
```

Here you see the changes in the `index.js` file:

```javascript
// <plugin root>/src/Resources/app/administration/src/app/component/structure/sw-search-bar-item/index.js
import template from './sw-search-bar-item.html.twig';

Shopware.Component.override('sw-search-bar-item', {
    template
})
```

The `sw_search_bar_item_cms_page` block is used as it is the last block, but it is not important which shopware type is extended as long as the vue else-if structure is kept working.

### Add custom show more results link

By default, the search bar tries to resolve to the registered listing route. If your entity can be searched externally you can edit the `sw-search-more-results` or `sw-search` components as well:

```twig
// <plugin root>/src/Resources/app/administration/src/app/component/structure/sw-search-more-results/sw-search-more-results.html.twig
{% block sw_search_more_results %}
    <template v-if="result.entity === 'foo_bar'">
        There are so many hits.
        <a :href="'https://my.erp.localhost/?q=' + searchTerm"
           class="sw-search-bar-item__link"
           target="_blank">
             Look it directly up
        </a>
        in the ERP instead.
    </template>
    <template v-else>
        {% parent %}
    </template>
{% endblock %}
```

See for the changes in the `index.js` file below:

```javascript
// <plugin root>/src/Resources/app/administration/src/app/component/structure/sw-search-more-results/index.js
import template from './sw-search-more-results.html.twig';

Shopware.Component.override('sw-search-more-results', {
    template
})
```

### Potential pitfalls

In case of a tag with a technical name with a missing translation, proceed like this:

```json
{
    "global": {
        "entities": {
            "my_entity": "My entity | My entities"
        }
    }
}
```

To change the color of the tag, or the icon in the untyped global search a module has to be registered with an entity reference in the module:

```javascript
Shopware.Module.register('any-name', {
    color: '#ff0000',
    icon: 'default-basic-shape-triangle',
    entity: 'my_entity',
})
```

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/administration/data-handling-processing/search-custom-data.md
---

# Add custom data to the search

## Overview

When developing a customization that has a frequently visited entity listing, you're able to make use of an interesting opportunity: You can enable the user to take a shortcut finding his desired entry using the global search.

There are two different ways how the global search works:

* Global search without type specification
* Typed global search

They only differ in the API they use and get displayed in a slightly different way.

::: warning
Think twice about adding this shortcut because if every plugin adds their own search tag, it gets cluttered.
:::

## Prerequisites

For this guide, it's necessary to have a running Shopware 6 instance and full access to both the files and a running plugin. See our plugin page guide to learn how to create your own plugins.

In addition, you need a custom entity to add to the search to begin with. Head over to the following guide to learn how to achieve that:

## Support custom entity via search API

To support an entity in the untyped global search, the entity has to be defined in one of the Administration Modules.

Add the `entity` and `defaultSearchConfiguration` values to your module to make it available to the search bar component.

```javascript
Shopware.Module.register('swag-plugin', {
    entity: 'swag_example',
    defaultSearchConfiguration: {
        _searchable: true,
        name: {
            _searchable: true,
            _score: 500,
        },
        description: {
            name: {
                _searchable: true,
                _score: 500,
            },
        },
    },
});
```

## Support in the Administration UI

### Add search tag

The search tag displays the entity type used in the typed search and is a clickable button to switch from the untyped to the typed search. To add the tag, a service decorator is used to add a type to the `searchTypeService`:

```javascript
const { Application } = Shopware;

Application.addServiceProviderDecorator('searchTypeService', searchTypeService => {
    searchTypeService.upsertType('foo_bar', {
        entityName: 'foo_bar',
        placeholderSnippet: 'foo-bar.general.placeholderSearchBar',
        listingRoute: 'foo.bar.index',
        hideOnGlobalSearchBar: false,
    });

    return searchTypeService;
});
```

Let's take a closer look at how this decorator is used:

* The key and `entityName` is used as the same to change also existing types.
* This service can be overridden with an own implementation for customization.
* The `placeholderSnippet` is a translation key that is shown when no search term is entered.
* The `listingRoute` is used to show a link to continue the search in the module-specific listing view.
* The `hideOnGlobalSearchBar` is used to determine whether the entity should be searched when searching globally untyped.

### Add the search result item

By default, the search bar does not know how to display the result items, so a current search request will not show any result. In order to declare a search result view the `sw-search-bar-item` template has to be altered as seen below, starting with the template:

```twig
// <plugin root>/src/Resources/app/administration/src/app/component/structure/sw-search-bar-item/sw-search-bar-item.html.twig
{% block sw_search_bar_item_cms_page %}
    {% parent %}

    <router-link v-else-if="type === 'foo_bar'"
                 v-bind:to="{ name: 'foo.bar.detail', params: { id: item.id } }"
                 ref="routerLink"
                 class="sw-search-bar-item__link">
        {% block sw_search_bar_item_foo_bar_label %}
            <span class="sw-search-bar-item__label">
                <sw-highlight-text v-bind:searchTerm="searchTerm"
                                   v-bind:text="item.name">
                </sw-highlight-text>
            </span>
        {% endblock %}
    </router-link>
{% endblock %}
```

Here you see the changes in the `index.js` file:

```javascript
// <plugin root>/src/Resources/app/administration/src/main.js

Shopware.Component.override('sw-search-bar-item', () => import('./app/component/structure/sw-search-bar-item'));
```

```javascript
// <plugin root>/src/Resources/app/administration/src/app/component/structure/sw-search-bar-item/index.js
import template from './sw-search-bar-item.html.twig';

export default {
    template
};
```

The `sw_search_bar_item_cms_page` block is used as it is the last block, but it is not important which shopware type is extended as long as the vue else-if structure is kept working.

### Add custom show more results link

By default, the search bar tries to resolve to the registered listing route. If your entity can be searched externally you can edit the `sw-search-more-results` or `sw-search` components as well:

```twig
// <plugin root>/src/Resources/app/administration/src/app/component/structure/sw-search-more-results/sw-search-more-results.html.twig
{% block sw_search_more_results %}
    <template v-if="result.entity === 'foo_bar'">
        There are so many hits.
        <a :href="'https://my.erp.localhost/?q=' + searchTerm"
           class="sw-search-bar-item__link"
           target="_blank">
             Look it directly up
        </a>
        in the ERP instead.
    </template>
    <template v-else>
        {% parent %}
    </template>
{% endblock %}
```

See for the changes in the `index.js` file below:

```javascript
// <plugin root>/src/Resources/app/administration/src/main.js

Shopware.Component.override('sw-search-more-results', () => import('./app/component/structure/sw-search-more-results'));
```

```javascript
// <plugin root>/src/Resources/app/administration/src/app/component/structure/sw-search-more-results/index.js
import template from './sw-search-more-results.html.twig';

export default {
    template
};
```

### Potential pitfalls

In case of a tag with a technical name with a missing translation, proceed like this:

```json
{
    "global": {
        "entities": {
            "my_entity": "My entity | My entities"
        }
    }
}
```

To change the color of the tag, or the icon in the untyped global search, a module has to be registered with an entity reference in the module:

```javascript
Shopware.Module.register('any-name', {
    color: '#ff0000',
    icon: 'default-basic-shape-triangle',
    entity: 'my_entity',
})
```

---

---
url: >-
  /docs/guides/plugins/plugins/administration/data-handling-processing/search-custom-data.md
---

# Add Custom Data to the Search

## Overview

When developing a customization that has a frequently visited entity listing, you're able to make use of an interesting opportunity: You can enable the user to take a shortcut finding his desired entry using the global search.

There are two different ways how the global search works:

* Global search without type specification
* Typed global search

They only differ in the API they use and get displayed in a slightly different way.

::: warning
Think twice about adding this shortcut because if every plugin adds their own search tag, it gets cluttered.
:::

## Prerequisites

For this guide, it's necessary to have a running Shopware 6 instance and full access to both the files and a running plugin. See our plugin page guide to learn how to create your own plugins.

In addition, you need a custom entity to add to the search to begin with. Head over to the following guide to learn how to achieve that:

## Support custom entity via search API

To support an entity in the untyped global search, the entity has to be defined in one of the Administration Modules.

Add the `entity` and `defaultSearchConfiguration` values to your module to make it available to the search bar component.

```javascript
Shopware.Module.register('swag-plugin', {
    entity: 'swag_example',
    defaultSearchConfiguration: {
        _searchable: true,
        name: {
            _searchable: true,
            _score: 500,
        },
        description: {
            name: {
                _searchable: true,
                _score: 500,
            },
        },
    },
});
```

## Support in the Administration UI

### Add search tag

The search tag displays the entity type used in the typed search and is a clickable button to switch from the untyped to the typed search. To add the tag, a service decorator is used to add a type to the `searchTypeService`:

```javascript
const { Application } = Shopware;

Application.addServiceProviderDecorator('searchTypeService', searchTypeService => {
    searchTypeService.upsertType('foo_bar', {
        entityName: 'foo_bar',
        placeholderSnippet: 'foo-bar.general.placeholderSearchBar',
        listingRoute: 'foo.bar.index',
        hideOnGlobalSearchBar: false,
    });

    return searchTypeService;
});
```

Let's take a closer look at how this decorator is used:

* The key and `entityName` is used as the same to change also existing types.
* This service can be overridden with an own implementation for customization.
* The `placeholderSnippet` is a translation key that is shown when no search term is entered.
* The `listingRoute` is used to show a link to continue the search in the module-specific listing view.
* The `hideOnGlobalSearchBar` is used to determine whether the entity should be searched when searching globally untyped.

### Add the search result item

By default, the search bar does not know how to display the result items, so a current search request will not show any result. In order to declare a search result view the `sw-search-bar-item` template has to be altered as seen below, starting with the template:

```twig
// <plugin root>/src/Resources/app/administration/src/app/component/structure/sw-search-bar-item/sw-search-bar-item.html.twig
{% block sw_search_bar_item_cms_page %}
    {% parent %}

    <router-link v-else-if="type === 'foo_bar'"
                 v-bind:to="{ name: 'foo.bar.detail', params: { id: item.id } }"
                 ref="routerLink"
                 class="sw-search-bar-item__link">
        {% block sw_search_bar_item_foo_bar_label %}
            <span class="sw-search-bar-item__label">
                <sw-highlight-text v-bind:searchTerm="searchTerm"
                                   v-bind:text="item.name">
                </sw-highlight-text>
            </span>
        {% endblock %}
    </router-link>
{% endblock %}
```

Here you see the changes in the `index.js` file:

```javascript
// <plugin root>/src/Resources/app/administration/src/main.js

Shopware.Component.override('sw-search-bar-item', () => import('./app/component/structure/sw-search-bar-item'));
```

```javascript
// <plugin root>/src/Resources/app/administration/src/app/component/structure/sw-search-bar-item/index.js
import template from './sw-search-bar-item.html.twig';

export default {
    template
};
```

The `sw_search_bar_item_cms_page` block is used as it is the last block, but it is not important which shopware type is extended as long as the vue else-if structure is kept working.

### Add custom show more results link

By default, the search bar tries to resolve to the registered listing route. If your entity can be searched externally you can edit the `sw-search-more-results` or `sw-search` components as well:

```twig
// <plugin root>/src/Resources/app/administration/src/app/component/structure/sw-search-more-results/sw-search-more-results.html.twig
{% block sw_search_more_results %}
    <template v-if="result.entity === 'foo_bar'">
        There are so many hits.
        <a :href="'https://my.erp.localhost/?q=' + searchTerm"
           class="sw-search-bar-item__link"
           target="_blank">
             Look it directly up
        </a>
        in the ERP instead.
    </template>
    <template v-else>
        {% parent %}
    </template>
{% endblock %}
```

See for the changes in the `index.js` file below:

```javascript
// <plugin root>/src/Resources/app/administration/src/main.js

Shopware.Component.override('sw-search-more-results', () => import('./app/component/structure/sw-search-more-results'));
```

```javascript
// <plugin root>/src/Resources/app/administration/src/app/component/structure/sw-search-more-results/index.js
import template from './sw-search-more-results.html.twig';

export default {
    template
};
```

### Potential pitfalls

In case of a tag with a technical name with a missing translation, proceed like this:

```json
{
    "global": {
        "entities": {
            "my_entity": "My entity | My entities"
        }
    }
}
```

To change the color of the tag, or the icon in the untyped global search, a module has to be registered with an entity reference in the module:

```javascript
Shopware.Module.register('any-name', {
    color: '#ff0000',
    icon: 'default-basic-shape-triangle',
    entity: 'my_entity',
})
```

---

---
url: /docs/guides/plugins/plugins/checkout/document/add-custom-document.md
---

# Add Custom Document

## Overview

Using the Shopware Administration, you can easily create new documents. This guide explains how to create a new document using a plugin.

## Prerequisites

Reviewing the [plugin base guide](../../plugin-base-guide) and the guide on [plugin database migrations](../../database/database-migrations.md) is advisable.

## Adding a custom document

Documents in Shopware are stored in the database table `document_base_config`. Do not confuse it with the `document` table, which contains the actually generated documents for an order and not the config for them.

Adding a new document is done by adding two entries to the database:

* One entry in the `document_base_config` table, which contains the whole configuration and the documents name
* One or more entries in the `document_base_config_sales_channel` table for each sales channel you want this document to be available

  for

We're doing this via a migration. In the following example migration, a new document named "custom" will be created, which is assigned to the `Storefront` sales channel.

```php
// <plugin root>/src/Migration/Migration1616668698AddDocument.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Framework\Uuid\Uuid;

class Migration1616668698AddDocument extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1616668698;
    }

    public function update(Connection $connection): void
    {
        $documentConfigId = Uuid::randomBytes();
        $documentTypeId = $this->getDocumentTypeId($connection);

        $connection->insert('document_base_config', [
            'id' => $documentConfigId,
            'name' => 'custom',
            'filename_prefix' => 'custom_',
            'global' => 0,
            'document_type_id' => $documentTypeId,
            'config' => $this->getConfig(),
            'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT)
        ]);

        $storefrontSalesChannelId = $this->getStorefrontSalesChannelId($connection);
        if (!$storefrontSalesChannelId) {
            return;
        }

        $connection->insert('document_base_config_sales_channel', [
            'id' => Uuid::randomBytes(),
            'document_base_config_id' => $documentConfigId,
            'sales_channel_id' => $storefrontSalesChannelId,
            'document_type_id' => $documentTypeId,
            'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT)
        ]);
    }

    private function getDocumentTypeId(Connection $connection): string
    {
        $sql = <<<SQL
            SELECT id
            FROM document_type
            WHERE technical_name = "delivery_note"
SQL;
        return $connection->fetchOne($sql);
    }

    private function getConfig(): string
    {
        $config = [
            'displayPrices' => false,
            'displayFooter' => true,
            'displayHeader' => true,
            'displayLineItems' => true,
            'displayLineItemPosition' => true,
            'displayPageCount' => true,
            'displayCompanyAddress' => true,
            'pageOrientation' => 'portrait',
            'pageSize' => 'a4',
            'itemsPerPage' => 10,
            'companyName' => 'Example company',
            'companyAddress' => 'Example company address',
            'companyEmail' => 'custom@example.org'
        ];

        return json_encode($config);
    }

    private function getStorefrontSalesChannelId(Connection $connection): ?string
    {
        $sql = <<<SQL
            SELECT id
            FROM sales_channel
            WHERE type_id = :typeId
SQL;
        $salesChannelId = $connection->fetchOne($sql, [
            'typeId' => Uuid::fromHexToBytes(Defaults::SALES_CHANNEL_TYPE_STOREFRONT)
        ]);

        if (!$salesChannelId) {
            return null;
        }

        return $salesChannelId;
    }
}
```

So it's basically fetching the "Storefront" sales channel ID, and the document type ID of the "Delivery note" document type and then inserts the necessary entries with some example data.

You'll have to provide a `name` and a `filename_prefix` for your custom document. If you create a new document for e.g. a completely new document type, you might want to set `global` to `1`, so it acts like a fallback. Also make sure to have a look at the `getConfig` method here, since it contains important configurations you can set for your custom document.

Basically, that's it already! You can now browse your Administration and use your newly configured document.

## Next steps

Defining custom templates for custom documents is possible by adding a new document **type**, as explained in [the Add Custom Document Type guide](add-custom-document-type).

---

---
url: /docs/v6.5/guides/plugins/plugins/checkout/document/add-custom-document.md
---

# Add Custom Document

## Overview

Using the Shopware Administration, you can easily create new documents. This guide will teach you how to achieve the same result, which is creating a new document, using your plugin.

## Prerequisites

This guide is built upon the [plugin base guide](../../plugin-base-guide), but of course you can use those examples with any other plugin.

Furthermore adding a document via your plugin is done by using [plugin database migrations](../../plugin-fundamentals/database-migrations). Since this isn't explained in this guide, you'll have to know and understand the plugin database migrations first.

## Adding a custom document

Documents in Shopware are stored in the database table `document_base_config`. Do not confuse it with the `document` table, which contains the actually generated documents for an order and not the config for them.

Adding a new document is done by adding two entries to the database:

* One entry in the `document_base_config` table, which contains the whole configuration and the documents name
* One or more entries in the `document_base_config_sales_channel` table for each sales channel you want this document to be available

  for

We're doing this via a migration. In the following example migration, a new document named "custom" will be created, which is assigned to the `Storefront` sales channel.

```php
// <plugin root>/src/Migration/Migration1616668698AddDocument.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Framework\Uuid\Uuid;

class Migration1616668698AddDocument extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1616668698;
    }

    public function update(Connection $connection): void
    {
        $documentConfigId = Uuid::randomBytes();
        $documentTypeId = $this->getDocumentTypeId($connection);

        $connection->insert('document_base_config', [
            'id' => $documentConfigId,
            'name' => 'custom',
            'filename_prefix' => 'custom_',
            'global' => 0,
            'document_type_id' => $documentTypeId,
            'config' => $this->getConfig(),
            'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT)
        ]);

        $storefrontSalesChannelId = $this->getStorefrontSalesChannelId($connection);
        if (!$storefrontSalesChannelId) {
            return;
        }

        $connection->insert('document_base_config_sales_channel', [
            'id' => Uuid::randomBytes(),
            'document_base_config_id' => $documentConfigId,
            'sales_channel_id' => $storefrontSalesChannelId,
            'document_type_id' => $documentTypeId,
            'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT)
        ]);
    }

    public function updateDestructive(Connection $connection): void
    {
    }

    private function getDocumentTypeId(Connection $connection): string
    {
        $sql = <<<SQL
            SELECT id
            FROM document_type
            WHERE technical_name = "delivery_note"
SQL;
        return $connection->fetchOne($sql);
    }

    private function getConfig(): string
    {
        $config = [
            'displayPrices' => false,
            'displayFooter' => true,
            'displayHeader' => true,
            'displayLineItems' => true,
            'displayLineItemPosition' => true,
            'displayPageCount' => true,
            'displayCompanyAddress' => true,
            'pageOrientation' => 'portrait',
            'pageSize' => 'a4',
            'itemsPerPage' => 10,
            'companyName' => 'Example company',
            'companyAddress' => 'Example company address',
            'companyEmail' => 'custom@example.org'
        ];

        return json_encode($config);
    }

    private function getStorefrontSalesChannelId(Connection $connection): ?string
    {
        $sql = <<<SQL
            SELECT id
            FROM sales_channel
            WHERE type_id = :typeId
SQL;
        $salesChannelId = $connection->fetchOne($sql, [
            ':typeId' => Uuid::fromHexToBytes(Defaults::SALES_CHANNEL_TYPE_STOREFRONT)
        ]);

        if (!$salesChannelId) {
            return null;
        }

        return $salesChannelId;
    }
}
```

So it's basically fetching the "Storefront" sales channel ID, and the document type ID of the "Delivery note" document type and then inserts the necessary entries with some example data.

You'll have to provide a `name` and a `filename_prefix` for your custom document. If you create a new document for e.g. a completely new document type, you might want to set `global` to `1`, so it acts like a fallback. Also make sure to have a look at the `getConfig` method here, since it contains important configurations you can set for your custom document.

Basically, that's it already! You can now browse your Administration and use your newly configured document.

## Next steps

You might wonder "But where do I define my custom template for my custom document?". This is done by adding a new document **type**, which is covered in [this guide](add-custom-document-type).

---

---
url: /docs/v6.6/guides/plugins/plugins/checkout/document/add-custom-document.md
---

# Add Custom Document

## Overview

Using the Shopware Administration, you can easily create new documents. This guide will teach you how to achieve the same result, which is creating a new document, using your plugin.

## Prerequisites

This guide is built upon the [plugin base guide](../../plugin-base-guide), but of course you can use those examples with any other plugin.

Furthermore adding a document via your plugin is done by using [plugin database migrations](../../plugin-fundamentals/database-migrations). Since this isn't explained in this guide, you'll have to know and understand the plugin database migrations first.

## Adding a custom document

Documents in Shopware are stored in the database table `document_base_config`. Do not confuse it with the `document` table, which contains the actually generated documents for an order and not the config for them.

Adding a new document is done by adding two entries to the database:

* One entry in the `document_base_config` table, which contains the whole configuration and the documents name
* One or more entries in the `document_base_config_sales_channel` table for each sales channel you want this document to be available

  for

We're doing this via a migration. In the following example migration, a new document named "custom" will be created, which is assigned to the `Storefront` sales channel.

```php
// <plugin root>/src/Migration/Migration1616668698AddDocument.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Framework\Uuid\Uuid;

class Migration1616668698AddDocument extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1616668698;
    }

    public function update(Connection $connection): void
    {
        $documentConfigId = Uuid::randomBytes();
        $documentTypeId = $this->getDocumentTypeId($connection);

        $connection->insert('document_base_config', [
            'id' => $documentConfigId,
            'name' => 'custom',
            'filename_prefix' => 'custom_',
            'global' => 0,
            'document_type_id' => $documentTypeId,
            'config' => $this->getConfig(),
            'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT)
        ]);

        $storefrontSalesChannelId = $this->getStorefrontSalesChannelId($connection);
        if (!$storefrontSalesChannelId) {
            return;
        }

        $connection->insert('document_base_config_sales_channel', [
            'id' => Uuid::randomBytes(),
            'document_base_config_id' => $documentConfigId,
            'sales_channel_id' => $storefrontSalesChannelId,
            'document_type_id' => $documentTypeId,
            'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT)
        ]);
    }

    public function updateDestructive(Connection $connection): void
    {
    }

    private function getDocumentTypeId(Connection $connection): string
    {
        $sql = <<<SQL
            SELECT id
            FROM document_type
            WHERE technical_name = "delivery_note"
SQL;
        return $connection->fetchOne($sql);
    }

    private function getConfig(): string
    {
        $config = [
            'displayPrices' => false,
            'displayFooter' => true,
            'displayHeader' => true,
            'displayLineItems' => true,
            'displayLineItemPosition' => true,
            'displayPageCount' => true,
            'displayCompanyAddress' => true,
            'pageOrientation' => 'portrait',
            'pageSize' => 'a4',
            'itemsPerPage' => 10,
            'companyName' => 'Example company',
            'companyAddress' => 'Example company address',
            'companyEmail' => 'custom@example.org'
        ];

        return json_encode($config);
    }

    private function getStorefrontSalesChannelId(Connection $connection): ?string
    {
        $sql = <<<SQL
            SELECT id
            FROM sales_channel
            WHERE type_id = :typeId
SQL;
        $salesChannelId = $connection->fetchOne($sql, [
            'typeId' => Uuid::fromHexToBytes(Defaults::SALES_CHANNEL_TYPE_STOREFRONT)
        ]);

        if (!$salesChannelId) {
            return null;
        }

        return $salesChannelId;
    }
}
```

So it's basically fetching the "Storefront" sales channel ID, and the document type ID of the "Delivery note" document type and then inserts the necessary entries with some example data.

You'll have to provide a `name` and a `filename_prefix` for your custom document. If you create a new document for e.g. a completely new document type, you might want to set `global` to `1`, so it acts like a fallback. Also make sure to have a look at the `getConfig` method here, since it contains important configurations you can set for your custom document.

Basically, that's it already! You can now browse your Administration and use your newly configured document.

## Next steps

You might wonder "But where do I define my custom template for my custom document?". This is done by adding a new document **type**, which is covered in [this guide](add-custom-document-type).

---

---
url: /docs/guides/plugins/plugins/checkout/document/add-custom-document-type.md
---

# Add Custom Document Type

## Overview

This guide will show you how to add a custom document type to your plugin. This includes adding a new document type to the database, creating a renderer for it, and adding a number range.

## Prerequisites

Reviewing the [plugin base guide](../../plugin-base-guide) and the guide on [plugin database migrations](../../database/database-migrations.md) is advisable.

## Adding a custom document type and its own base configuration to the database

Let's start with adding your custom document type to the database, so it's actually available for new document configurations. This is done by adding a plugin database migration. To be precise, we need to add an entry to the database table `document_type` table and an entry for each supported language to the `document_type_translation` table.

Let's have a look at an example migration:

::: code-group

```php [PLUGIN_ROOT/src/Migration/Migration1616677952AddDocumentType.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Migration\Traits\ImportTranslationsTrait;
use Shopware\Core\Framework\Uuid\Uuid;
use Shopware\Core\Migration\Traits\Translations;

class Migration1616677952AddDocumentType extends MigrationStep
{
    use ImportTranslationsTrait;

    final public const TYPE = 'example';

    public function getCreationTimestamp(): int
    {
        return 1616677952;
    }

    public function update(Connection $connection): void
    {
        $documentTypeId = Uuid::randomBytes();

        $connection->insert('document_type', [
            'id' => $documentTypeId,
            'technical_name' => self::TYPE,
            'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT)
        ]);

        $this->addTranslations($connection, $documentTypeId);
        $this->addDocumentBaseConfig($connection, $documentTypeId);
    }

    private function addTranslations(Connection $connection, string $documentTypeId): void
    {
        $englishName = 'Example document type name';
        $germanName = 'Beispiel Dokumententyp Name';

        $documentTypeTranslations = new Translations(
            [
                'document_type_id' => $documentTypeId,
                'name' => $germanName,
            ],
            [
                'document_type_id' => $documentTypeId,
                'name' => $englishName,
            ]
        );

        $this->importTranslation(
            'document_type_translation',
            $documentTypeTranslations,
            $connection
        );
    }

    private function addDocumentBaseConfig(Connection $connection, string $documentTypeId): void
    {
        $defaultConfig = [
            'displayPrices' => true,
            'displayFooter' => true,
            'displayHeader' => true,
            'displayLineItems' => true,
            'diplayLineItemPosition' => true,
            'displayPageCount' => true,
            'displayCompanyAddress' => true,
            'pageOrientation' => 'portrait',
            'pageSize' => 'a4',
            'itemsPerPage' => 10,
            'companyName' => 'Example Company',
            'taxNumber' => '',
            'vatId' => '',
            'taxOffice' => '',
            'bankName' => '',
            'bankIban' => '',
            'bankBic' => '',
            'placeOfJurisdiction' => '',
            'placeOfFulfillment' => '',
            'executiveDirector' => '',
            'companyAddress' => '',
            'referencedDocumentType' => self::TYPE,
        ];

        $documentBaseConfigId = Uuid::randomBytes();

        $connection->insert(
            'document_base_config',
            [
                'id' => $documentBaseConfigId,
                'name' => self::TYPE,
                'global' => 1,
                'filename_prefix' => self::TYPE . '_',
                'document_type_id' => $documentTypeId,
                'config' => json_encode($defaultConfig, \JSON_THROW_ON_ERROR),
                'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
            ]
        );
        $connection->insert(
            'document_base_config_sales_channel',
            [
                'id' => Uuid::randomBytes(),
                'document_base_config_id' => $documentBaseConfigId,
                'document_type_id' => $documentTypeId,
                'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
            ]
        );
    }
}
```

:::

So first, we are creating the new document type with the `technical_name` as "example". Make sure to save the ID here since you are going to need it for the following translations:

Afterwards we're inserting the translations, one for German, one for English. For this we're using the `Shopware\Core\Migration\Traits\ImportTranslationsTrait`, which adds the helper method `importTranslation`. There you have to supply the translation table and an instance of `Shopware\Core\Migration\Traits\Translations`. The latter accepts two constructor parameters:

* An array of German translations, plus the respective ID column
* An array of English translations, plus the respective ID column

  It will then take care of properly inserting those translations.

And the last, We are creating the new document base configuration for the new document type to store some default configurations for our new document type.

After installing your plugin, your new document type should be available in the Administration. However, it wouldn't work yet, since every document type has to come with a respective `AbstractDocumentRenderer`. This is covered in the next section.

## Adding a renderer

The renderer for a document type is responsible for rendering the respective document, including a template. That is why we will have to create a custom renderer for the new type as well, lets call it `ExampleDocumentRenderer`.

We will place it in the same directory as all other default document renderers: `<plugin root>/src/Core/Checkout/Document/Renderer`

Your custom document renderer has to implement the `Shopware\Core\Checkout\Document\Renderer\AbstractDocumentRenderer`, which forces you to implement three methods:

* `getDecorated`: Shall return the decorated service (see decoration pattern adr).
* `supports`: Has to return a string of the document type it supports. We named our document type "**example**", so our renderer has to return "**example**".
* `render`: This needs to return the instance `Shopware\Core\Checkout\Document\Renderer\RendererResult`, which will contain the instance of `Shopware\Core\Checkout\Document\Renderer\RenderedDocument` based on each `orderId`. You will have access to the array of `DocumentGenerateOperation` which contains all respective orderIds, the context and the instance of `Shopware\Core\Checkout\Document\Renderer\DocumentRendererConfig` (additional configuration).

Furthermore, your renderer has to be registered to the [service container](../../services/dependency-injection.md) using the tag `document.renderer`.

An example renderer:

::: code-group

```php [PLUGIN_ROOT/src/Core/Checkout/Document/Renderer/ExampleDocumentRenderer.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout\Document\Renderer;

use Shopware\Core\Checkout\Document\Renderer\AbstractDocumentRenderer;
use Shopware\Core\Checkout\Document\Renderer\DocumentRendererConfig;
use Shopware\Core\Checkout\Document\Renderer\RenderedDocument;
use Shopware\Core\Checkout\Document\Renderer\RendererResult;
use Shopware\Core\Checkout\Document\Service\DocumentConfigLoader;
use Shopware\Core\Checkout\Document\Service\DocumentFileRendererRegistry;
use Shopware\Core\Checkout\Document\Struct\DocumentGenerateOperation;
use Shopware\Core\Checkout\Order\OrderEntity;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\Framework\Plugin\Exception\DecorationPatternException;
use Shopware\Core\System\NumberRange\ValueGenerator\NumberRangeValueGeneratorInterface;

class ExampleDocumentRenderer extends AbstractDocumentRenderer
{
    public const DEFAULT_TEMPLATE = '@SwagBasicExample/documents/example_document.html.twig';

    final public const TYPE = 'example';

    /**
     * @internal
     */
    public function __construct(
        private readonly EntityRepository $orderRepository,
        private readonly DocumentConfigLoader $documentConfigLoader,
        private readonly NumberRangeValueGeneratorInterface $numberRangeValueGenerator,
        private readonly DocumentFileRendererRegistry $fileRendererRegistry,
    ) {
    }

    public function supports(): string
    {
        return self::TYPE;
    }

    /**
     * @param array<DocumentGenerateOperation> $operations
     */
    public function render(array $operations, Context $context, DocumentRendererConfig $rendererConfig): RendererResult
    {
        $ids = \array_map(fn (DocumentGenerateOperation $operation) => $operation->getOrderId(), $operations);

        if (empty($ids)) {
            return new RendererResult();
        }

        $result = new RendererResult();

        $criteria = new Criteria($ids);
        $criteria->addAssociation('language');
        $criteria->addAssociation('language.locale');

        $orders = $this->orderRepository->search($criteria, $context)->getEntities();
        foreach ($orders as $order) {
            $orderId = $order->getId();

            try {
                $operation = $operations[$orderId] ?? null;
                if ($operation === null) {
                    continue;
                }

                $config = clone $this->documentConfigLoader->load(self::TYPE, $order->getSalesChannelId(), $context);

                $config->merge($operation->getConfig());

                $number = $config->getDocumentNumber() ?: $this->getNumber($context, $order, $operation);

                $now = (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT);

                $config->merge([
                    'documentDate' => $operation->getConfig()['documentDate'] ?? $now,
                    'documentNumber' => $number,
                    'custom' => [
                        'invoiceNumber' => $number,
                    ],
                ]);

                // The document that uploaded by manual
                if ($operation->isStatic()) {
                    $doc = new RenderedDocument($number, $config->buildName(), $operation->getFileType(), $config->jsonSerialize());
                    $result->addSuccess($orderId, $doc);

                    continue;
                }

                $doc = new RenderedDocument(
                    $number,
                    $config->buildName(),
                    $operation->getFileType(),
                    $config->jsonSerialize(),
                );

                // Utilize the DocumentFileRendererRegistry to generate the content, e.g. PDF or HTML
                // This is the recommended approach
                $doc->setTemplate(self::DEFAULT_TEMPLATE);
                $doc->setOrder($order);
                $doc->setContext($context);
                $content = $this->fileRendererRegistry->render($doc);
                $doc->setContent($content);

                // Alternatively you can manually set the content here, e.g. to some XML or CSV content
                // $content = '<?xml ...>...';
                // or
                // $content = 'Id;Name;...';
                // $doc->setContent($content);

                $result->addSuccess($orderId, $doc);
            } catch (\Throwable $exception) {
                $result->addError($orderId, $exception);
            }
        }

        return $result;
    }

    public function getDecorated(): AbstractDocumentRenderer
    {
        throw new DecorationPatternException(self::class);
    }

    private function getNumber(Context $context, OrderEntity $order, DocumentGenerateOperation $operation): string
    {
        return $this->numberRangeValueGenerator->getValue(
            'document_' . self::TYPE,
            $context,
            $order->getSalesChannelId(),
            $operation->isPreview()
        );
    }
}
```

:::

We inject `orderRepository` to get all order entities by list of order's id, `documentConfigLoader` to load the document configuration and `numberRangeValueGenerator` to get the document number

The `supports` method just returns the string "**example**", which is the technical name of our new document type.

Now let's have a look at the `render` method. This function contains three parameters:

* `$operations`: An array of `DocumentGenerateOperation` objects.
* `$context`: A Context object.
* `$rendererConfig`: A `DocumentRendererConfig` object, so we can add additional configuration later.

The function returns a `RendererResult` object.
Here's what the function does:

* It creates an array of `$ids`, which is populated with the `orderId` of each `DocumentGenerateOperation` object in $operations.
* If `$ids` is empty, the function returns an empty `RendererResult` object.
* A search is performed on the order repository to find all orders by `$ids`.
* For each order found, the function attempts to generate a document.
* If successful, a new `RenderedDocument` object is created. This object is then added to the `RendererResult` object as a success.
* If an error occurs, the exception is caught and the error message is added to the `RendererResult` object as an error.
* The `RendererResult` object is returned.

The service definition for our custom renderer would look like this:

```php
<?php declare(strict_types=1);

use Shopware\Core\Checkout\Document\Service\DocumentConfigLoader;
use Shopware\Core\Checkout\Document\Service\DocumentFileRendererRegistry;
use Shopware\Core\System\NumberRange\ValueGenerator\NumberRangeValueGeneratorInterface;
use Swag\BasicExample\Core\Checkout\Document\Render\ExampleDocumentRenderer;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(ExampleDocumentRenderer::class)
        ->args([
            service('order.repository'),
            service(DocumentConfigLoader::class),
            service(NumberRangeValueGeneratorInterface::class),
            service(DocumentFileRendererRegistry::class),
        ])
      ->tag('document.renderer');
};
```

### Adding a file type renderer

Depending on the file type we either get the content with `$this->fileRendererRegistry->render()` or we need to create the content on our own.
`DocumentFileRendererRegistry` acts as a central registry for document file renderers based on file extensions (e.g., .pdf, .html). It delegates the rendering of documents to the appropriate renderer implementation.

### Registering the renderer in the service container

Now we need to register our custom `ExampleDocumentRenderer` in the service container. Create or update your `services.php` file:

::: code-group

```php [PLUGIN_ROOT/src/Resources/config/services.php]
<?php declare(strict_types=1);

use Shopware\Core\Checkout\Document\Service\DocumentConfigLoader;
use Shopware\Core\Checkout\Document\Service\DocumentFileRendererRegistry;
use Shopware\Core\System\NumberRange\ValueGenerator\NumberRangeValueGeneratorInterface;
use Swag\BasicExample\Core\Checkout\Document\Render\ExampleDocumentRenderer;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(ExampleDocumentRenderer::class)
        ->args([
            service('order.repository'),
            service(DocumentConfigLoader::class),
            service(NumberRangeValueGeneratorInterface::class),
            service(DocumentFileRendererRegistry::class),
        ])
        ->tag('document.renderer');
};
```

:::

Note that we're using the tag `document.renderer` to register our custom document renderer. The tag name matches what was mentioned earlier - your renderer has to be registered using the tag `document.renderer`.

### Adding a document type template

Let's have a quick look at an example document type template. Create a new file at the path `<plugin root>/src/Resources/views/documents/example_document.html.twig`.

In there, you should extend from the default document base template:

:::code-group

```twig [PLUGIN_ROOT/src/Resources/views/documents/example_document.html.twig]
{% sw_extends '@Framework/documents/base.html.twig' %}
```

:::

The [base.html.twig](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Core/Framework/Resources/views/documents/base.html.twig) template comes with a default templating, which you can now override by using blocks. The guide on [customizing templates](../../storefront/templates/customize-templates.md) provides more details.

## Adding a number range

You are almost done here. You have a new document type in the database, a renderer for your new document type, and it even uses a custom template. However, you also need to add a new number range for your documents; otherwise, a new number wouldn't be generated for your documents.

Adding a new number range is also done by using a [plugin database migration](../../database/database-migrations.md).

For this we need a few more things:

* An entry in `number_range_type`, which is just a new type of number range with a technical name
* An entry in `number_range`, which represents a properly configured number range, which then will use the previously created type
* An entry in `number_range_sales_channel` to assign a sales channel to our configured number range
* An entry for each language in the tables `number_range_translation` and `number_range_type_translation`

Sounds like a lot, but having a look at an example migration, you will notice that it's not too much of a hassle.

::: code-group

```php [PLUGIN_ROOT/src/Migration/Migration1616974646AddDocumentNumberRange.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Framework\Uuid\Uuid;
use Shopware\Core\Migration\Traits\ImportTranslationsTrait;
use Shopware\Core\Migration\Traits\Translations;

class Migration1616974646AddDocumentNumberRange extends MigrationStep
{
    use ImportTranslationsTrait;

    public function getCreationTimestamp(): int
    {
        return 1616974646;
    }

    public function update(Connection $connection): void
    {
        $numberRangeId = Uuid::randomBytes();
        $numberRangeTypeId = Uuid::randomBytes();

        $this->insertNumberRange($connection, $numberRangeId, $numberRangeTypeId);
        $this->insertTranslations($connection, $numberRangeId, $numberRangeTypeId);

    }

    private function insertNumberRange(Connection $connection, string $numberRangeId, string $numberRangeTypeId): void
    {
        $connection->insert('number_range_type', [
            'id' => $numberRangeTypeId,
            'global' => 0,
            'technical_name' => 'document_example',
            'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT)
        ]);

        $connection->insert('number_range', [
            'id' => $numberRangeId,
            'type_id' => $numberRangeTypeId,
            'global' => 0,
            'pattern' => '{n}',
            'start' => 10000,
            'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT)
        ]);

        $storefrontSalesChannelId = $this->getStorefrontSalesChannelId($connection);
        if (!$storefrontSalesChannelId) {
            return;
        }

        $connection->insert('number_range_sales_channel', [
            'id' => Uuid::randomBytes(),
            'number_range_id' => $numberRangeId,
            'sales_channel_id' => $storefrontSalesChannelId,
            'number_range_type_id' => $numberRangeTypeId,
            'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT)
        ]);
    }

    private function getStorefrontSalesChannelId(Connection $connection): ?string
    {
        $sql = <<<SQL
            SELECT id
            FROM sales_channel
            WHERE type_id = :typeId
SQL;
        $salesChannelId = $connection->fetchOne($sql, [
            'typeId' => Uuid::fromHexToBytes(Defaults::SALES_CHANNEL_TYPE_STOREFRONT)
        ]);

        if (!$salesChannelId) {
            return null;
        }

        return $salesChannelId;
    }

    private function insertTranslations(Connection $connection, string $numberRangeId, string $numberRangeTypeId): void
    {
        $numberRangeTranslations = new Translations(
            [
                'number_range_id' => $numberRangeId,
                'name' => 'Beispiel',
            ],
            [
                'number_range_id' => $numberRangeId,
                'name' => 'Example',
            ]
        );

        $numberRangeTypeTranslations = new Translations(
            [
                'number_range_type_id' => $numberRangeTypeId,
                'type_name' => 'Beispiel',
            ],
            [
                'number_range_type_id' => $numberRangeTypeId,
                'type_name' => 'Example',
            ]
        );

        $this->importTranslation(
            'number_range_translation',
            $numberRangeTranslations,
            $connection
        );

        $this->importTranslation(
            'number_range_type_translation',
            $numberRangeTypeTranslations,
            $connection
        );
    }
}
```

:::

As already said, we're first creating the entries in the tables `number_range`, `number_range_type` and `number_range_sales_channel`. For the latter, we're assigning a Storefront sales channel, if any available. Make sure to check here, since in theory there could be no storefront sales channel.

Afterward we import the translations for the `number_range_translation` and the `number_range_type_translation` tables by using the `ImportTranslationsTrait` once again.

And that's it now. You Have just created:

* A custom document type, including translations
* A custom document renderer
* A custom number range and number range type, which will now be used by your custom document type

## Next steps

With your custom document type, you also might want to add a new actual document configuration, which is making use of your new type. Creating a custom document is explained in [this guide](add-custom-document).

---

---
url: >-
  /docs/v6.5/guides/plugins/plugins/checkout/document/add-custom-document-type.md
---

# Add Custom Document Type

## Overview

Using the Shopware Administration, you can easily create new documents. This guide will teach you how to achieve the same result, which is creating a new document, using your plugin.

## Prerequisites

This guide is built upon the [plugin base guide](../../plugin-base-guide), but of course you can use those examples with any other plugin.

Furthermore, adding a custom document type via your plugin is done by using [plugin database migrations](../../plugin-fundamentals/database-migrations). Since this isn't explained in this guide, you will have to know and understand the plugin database migrations first.

## Adding a custom document type, and its own base configuration to the database

Let's start with adding your custom document type to the database, so it's actually available for new document configurations. This is done by adding a plugin database migration. To be precise, we need to add an entry to the database table `document_type` table and an entry for each supported language to the `document_type_translation` table.

Let's have a look at an example migration:

```php
// <plugin root>/src/Migration/Migration1616677952AddDocumentType.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Migration\Traits\ImportTranslationsTrait;
use Shopware\Core\Framework\Uuid\Uuid;
use Shopware\Core\Migration\Traits\Translations;

class Migration1616677952AddDocumentType extends MigrationStep
{
    use ImportTranslationsTrait;
    
    final public const TYPE = 'example';
    
    public function getCreationTimestamp(): int
    {
        return 1616677952;
    }

    public function update(Connection $connection): void
    {
        $documentTypeId = Uuid::randomBytes();

        $connection->insert('document_type', [
            'id' => $documentTypeId,
            'technical_name' => self::TYPE,
            'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT)
        ]);

        $this->addTranslations($connection, $documentTypeId);
        $this->addDocumentBaseConfig($connection, $documentTypeId);
    }

    public function updateDestructive(Connection $connection): void
    {
    }

    private function addTranslations(Connection $connection, string $documentTypeId): void
    {
        $englishName = 'Example document type name';
        $germanName = 'Beispiel Dokumententyp Name';

        $documentTypeTranslations = new Translations(
            [
                'document_type_id' => $documentTypeId,
                'name' => $germanName,
            ],
            [
                'document_type_id' => $documentTypeId,
                'name' => $englishName,
            ]
        );

        $this->importTranslation(
            'document_type_translation',
            $documentTypeTranslations,
            $connection
        );
    }
    
    private function addDocumentBaseConfig(Connection $connection, string $documentTypeId): void
    {
        $defaultConfig = [
            'displayPrices' => true,
            'displayFooter' => true,
            'displayHeader' => true,
            'displayLineItems' => true,
            'diplayLineItemPosition' => true,
            'displayPageCount' => true,
            'displayCompanyAddress' => true,
            'pageOrientation' => 'portrait',
            'pageSize' => 'a4',
            'itemsPerPage' => 10,
            'companyName' => 'Example Company',
            'taxNumber' => '',
            'vatId' => '',
            'taxOffice' => '',
            'bankName' => '',
            'bankIban' => '',
            'bankBic' => '',
            'placeOfJurisdiction' => '',
            'placeOfFulfillment' => '',
            'executiveDirector' => '',
            'companyAddress' => '',
            'referencedDocumentType' => self::TYPE,
        ];

        $documentBaseConfigId = Uuid::randomBytes();

        $connection->insert(
            'document_base_config',
            [
                'id' => $documentBaseConfigId,
                'name' => self::TYPE,
                'global' => 1,
                'filename_prefix' => self::TYPE . '_',
                'document_type_id' => $documentTypeId,
                'config' => json_encode($defaultConfig, \JSON_THROW_ON_ERROR),
                'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
            ]
        );
        $connection->insert(
            'document_base_config_sales_channel',
            [
                'id' => Uuid::randomBytes(),
                'document_base_config_id' => $documentBaseConfigId,
                'document_type_id' => $documentTypeId,
                'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
            ]
        );
    }
}
```

So first, we are creating the new document type with the `technical_name` as "example". Make sure to save the ID here since you are going to need it for the following translations:

Afterwards we're inserting the translations, one for German, one for English. For this we're using the `Shopware\Core\Migration\Traits\ImportTranslationsTrait`, which adds the helper method `importTranslation`. There you have to supply the translation table and an instance of `Shopware\Core\Migration\Traits\Translations`. The latter accepts two constructor parameters:

* An array of German translations, plus the respective ID column
* An array of English translations, plus the respective ID column

  It will then take care of properly inserting those translations.

And the last, We are creating the new document base configuration for the new document type to store some default configurations for our new document type.

After installing your plugin, your new document type should be available in the Administration. However, it wouldn't work yet, since every document type has to come with a respective `AbstractDocumentRenderer`. This is covered in the next section.

## Adding a renderer

The renderer for a document type is responsible for rendering the respective document, including a template. That is why we will have to create a custom renderer for the new type as well, lets call it `ExampleDocumentRenderer`.

We will place it in the same directory as all other default document renderers: `<plugin root>/src/Core/Checkout/Document/Renderer`

Your custom document renderer has to implement the `Shopware\Core\Checkout\Document\Renderer\AbstractDocumentRenderer`, which forces you to implement three methods:

* `getDecorated`: Shall return the decorated service (see decoration pattern adr).
* `supports`: Has to return a string of the document type it supports. We named our document type "example", so our renderer has to return "example".
* `render`: This needs to return the instance `Shopware\Core\Checkout\Document\Renderer\RendererResult`, which will contain the instance of `Shopware\Core\Checkout\Document\Renderer\RenderedDocument` based on each `orderId`. You will have access to the array of `DocumentGenerateOperation` which contains all respective orderIds, the context and the instance of `Shopware\Core\Checkout\Document\Renderer\DocumentRendererConfig` (additional configuration).

Furthermore, your renderer has to be registered to the [service container](../../plugin-fundamentals/dependency-injection) using the tag `document.renderer`.

Let's have a look at an example renderer:

```php
// <plugin root>/src/Core/Checkout/Document/Render/ExampleDocumentRenderer.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout\Document\Render;

use Shopware\Core\Checkout\Document\Renderer\AbstractDocumentRenderer;
use Shopware\Core\Checkout\Document\Renderer\DocumentRendererConfig;
use Shopware\Core\Checkout\Document\Renderer\RenderedDocument;
use Shopware\Core\Checkout\Document\Renderer\RendererResult;
use Shopware\Core\Checkout\Document\Service\DocumentConfigLoader;
use Shopware\Core\Checkout\Document\Struct\DocumentGenerateOperation;
use Shopware\Core\Checkout\Document\Twig\DocumentTemplateRenderer;
use Shopware\Core\Checkout\Order\OrderEntity;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\Framework\Plugin\Exception\DecorationPatternException;
use Shopware\Core\System\Locale\LocaleEntity;
use Shopware\Core\System\NumberRange\ValueGenerator\NumberRangeValueGeneratorInterface;

class ExampleDocumentRenderer extends AbstractDocumentRenderer
{
    public const DEFAULT_TEMPLATE = '@SwagBasicExample/documents/example_document.html.twig';

    final public const TYPE = 'example';

    /**
     * @internal
     */
    public function __construct(
        private readonly EntityRepository $orderRepository,
        private readonly DocumentConfigLoader $documentConfigLoader,
        private readonly DocumentTemplateRenderer $documentTemplateRenderer,
        private readonly NumberRangeValueGeneratorInterface $numberRangeValueGenerator,
        private readonly string $rootDir,
    ) {
    }

    public function supports(): string
    {
        return self::TYPE;
    }

    /**
     * @param array<DocumentGenerateOperation> $operations
     */
    public function render(array $operations, Context $context, DocumentRendererConfig $rendererConfig): RendererResult
    {
        $ids = \array_map(fn (DocumentGenerateOperation $operation) => $operation->getOrderId(), $operations);

        if (empty($ids)) {
            return new RendererResult();
        }

        $result = new RendererResult();

        $template = self::DEFAULT_TEMPLATE;

        $orders = $this->orderRepository->search(new Criteria($ids), $context)->getEntities();
        foreach ($orders as $order) {
            $orderId = $order->getId();

            try {
                $operation = $operations[$orderId] ?? null;
                if ($operation === null) {
                    continue;
                }

                $config = clone $this->documentConfigLoader->load(self::TYPE, $order->getSalesChannelId(), $context);

                $config->merge($operation->getConfig());

                $number = $config->getDocumentNumber() ?: $this->getNumber($context, $order, $operation);

                $now = (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT);

                $config->merge([
                    'documentDate' => $operation->getConfig()['documentDate'] ?? $now,
                    'documentNumber' => $number,
                    'custom' => [
                        'invoiceNumber' => $number,
                    ],
                ]);

                // The document that uploaded by manual
                if ($operation->isStatic()) {
                    $doc = new RenderedDocument('', $number, $config->buildName(), $operation->getFileType(), $config->jsonSerialize());
                    $result->addSuccess($orderId, $doc);

                    continue;
                }

                /** @var LocaleEntity $locale */
                $locale = $order->getLanguage()->getLocale();

                $html = $this->documentTemplateRenderer->render(
                    $template,
                    [
                        'order' => $order,
                        'config' => $config,
                        'rootDir' => $this->rootDir,
                        'context' => $context,
                    ],
                    $context,
                    $order->getSalesChannelId(),
                    $order->getLanguageId(),
                    $locale->getCode()
                );

                $doc = new RenderedDocument(
                    $html,
                    $number,
                    $config->buildName(),
                    $operation->getFileType(),
                    $config->jsonSerialize(),
                );

                $result->addSuccess($orderId, $doc);
            } catch (\Throwable $exception) {
                $result->addError($orderId, $exception);
            }
        }

        return $result;
    }

    public function getDecorated(): AbstractDocumentRenderer
    {
        throw new DecorationPatternException(self::class);
    }

    private function getNumber(Context $context, OrderEntity $order, DocumentGenerateOperation $operation): string
    {
        return $this->numberRangeValueGenerator->getValue(
            'document_' . self::TYPE,
            $context,
            $order->getSalesChannelId(),
            $operation->isPreview()
        );
    }
}
```

First, we are injecting the `rootDir` of the Shopware installation into our renderer since we will need that for rendering our template, and the `DocumentTemplateRenderer`, which will do the template rendering. We also inject `orderRepository` to get all order entities by list of order's id, `documentConfigLoader` to load the document configuration and `numberRangeValueGenerator` to get the document number

The `supports` method just returns the string "example", which is the technical name of our new document type.

Now let's have a look at the `render` method. This function contains three parameters:

* `$operations`: An array of `DocumentGenerateOperation` objects.
* `$context`: A Context object.
* `$rendererConfig`: A `DocumentRendererConfig` object, so we can add additional configuration later.

The function returns a `RendererResult` object.
Here's what the function does:

* It creates an array of `$ids`, which is populated with the `orderId` of each `DocumentGenerateOperation` object in $operations.
* If `$ids` is empty, the function returns an empty `RendererResult` object.
* A search is performed on the order repository to find all orders by `$ids`.
* For each order found, the function attempts to generate a document.
* If successful, a new `RenderedDocument` object is created. This object is then added to the `RendererResult` object as a success.
* If an error occurs, the exception is caught and the error message is added to the `RendererResult` object as an error.
* `The RendererResult` object is returned.

In this example, we are rendering a specific template, which we will have a look at in the next section.

### Adding a document type template

Let's have a quick look at an example document type template. Go ahead and create a new file at the path `<plugin root>/src/Resources/views/documents/example_document.html.twig`.

In there you should extend from the default document base template:

```twig
// <plugin root>/src/Resources/views/documents/example\_document.html.twig
{% sw_extends '@Framework/documents/base.html.twig' %}
```

This could be it already. The [base.html.twig](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Core/Framework/Resources/views/documents/base.html.twig) template comes with a lot of default templating, which you can now override by using blocks. If you don't know how that's done, have a look at our guide regarding [customizing templates](../../storefront/customize-templates).

## Adding a number range

You are almost done here. You have a new document type in the database, a renderer for your new document type, and it even uses a custom template. However, you also need to add a new number range for your documents; otherwise, a new number wouldn't be generated for your documents.

Adding a new number range is also done by using a [plugin database migration](../../plugin-fundamentals/database-migrations).

For this we need a few more things:

* An entry in `number_range_type`, which is just a new type of a number range with a technical name
* An entry in `number_range`, which represents a properly configured number range, which then will use the previously created type
* An entry in `number_range_sales_channel` to assign a sales channel to our configured number range
* An entry for each language in the tables `number_range_translation` and `number_range_type_translation`

Sounds like a lot, but having a look at an example migration, you will notice that it's not too much of a hassle.

```php
// <plugin root>/src/Migration/Migration1616974646AddDocumentNumberRange.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Framework\Uuid\Uuid;
use Shopware\Core\Migration\Traits\ImportTranslationsTrait;
use Shopware\Core\Migration\Traits\Translations;

class Migration1616974646AddDocumentNumberRange extends MigrationStep
{
    use ImportTranslationsTrait;

    public function getCreationTimestamp(): int
    {
        return 1616974646;
    }

    public function update(Connection $connection): void
    {
        $numberRangeId = Uuid::randomBytes();
        $numberRangeTypeId = Uuid::randomBytes();

        $this->insertNumberRange($connection, $numberRangeId, $numberRangeTypeId);
        $this->insertTranslations($connection, $numberRangeId, $numberRangeTypeId);

    }

    public function updateDestructive(Connection $connection): void
    {
    }

    private function insertNumberRange(Connection $connection, string $numberRangeId, string $numberRangeTypeId): void
    {
        $connection->insert('number_range_type', [
            'id' => $numberRangeTypeId,
            'global' => 0,
            'technical_name' => 'document_example',
            'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT)
        ]);

        $connection->insert('number_range', [
            'id' => $numberRangeId,
            'type_id' => $numberRangeTypeId,
            'global' => 0,
            'pattern' => '{n}',
            'start' => 10000,
            'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT)
        ]);

        $storefrontSalesChannelId = $this->getStorefrontSalesChannelId($connection);
        if (!$storefrontSalesChannelId) {
            return;
        }

        $connection->insert('number_range_sales_channel', [
            'id' => Uuid::randomBytes(),
            'number_range_id' => $numberRangeId,
            'sales_channel_id' => $storefrontSalesChannelId,
            'number_range_type_id' => $numberRangeTypeId,
            'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT)
        ]);
    }

    private function getStorefrontSalesChannelId(Connection $connection): ?string
    {
        $sql = <<<SQL
            SELECT id
            FROM sales_channel
            WHERE type_id = :typeId
SQL;
        $salesChannelId = $connection->fetchOne($sql, [
            'typeId' => Uuid::fromHexToBytes(Defaults::SALES_CHANNEL_TYPE_STOREFRONT)
        ]);

        if (!$salesChannelId) {
            return null;
        }

        return $salesChannelId;
    }

    private function insertTranslations(Connection $connection, string $numberRangeId, string $numberRangeTypeId): void
    {
        $numberRangeTranslations = new Translations(
            [
                'number_range_id' => $numberRangeId,
                'name' => 'Beispiel',
            ],
            [
                'number_range_id' => $numberRangeId,
                'name' => 'Example',
            ]
        );

        $numberRangeTypeTranslations = new Translations(
            [
                'number_range_type_id' => $numberRangeTypeId,
                'type_name' => 'Beispiel',
            ],
            [
                'number_range_type_id' => $numberRangeTypeId,
                'type_name' => 'Example',
            ]
        );

        $this->importTranslation(
            'number_range_translation',
            $numberRangeTranslations,
            $connection
        );

        $this->importTranslation(
            'number_range_type_translation',
            $numberRangeTypeTranslations,
            $connection
        );
    }
}
```

As already said, we're first creating the entries in the tables `number_range`, `number_range_type` and `number_range_sales_channel`. For the latter, we're assigning a Storefront sales channel, if any available. Make sure to check here, since in theory there could be no storefront sales channel.

Afterwards we import the translations for the `number_range_translation` and the `number_range_type_translation` tables by using the `ImportTranslationsTrait` once again.

And that's it now. You Have just created:

* A custom document type, including translations
* A custom document renderer
* A custom number range and number range type, which will now be used by your custom document type

## Next steps

With your custom document type, you also might want to add a new actual document configuration, which is making use of your new type. Creating a custom document is explained in [this guide](add-custom-document).

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/checkout/document/add-custom-document-type.md
---

# Add Custom Document Type

## Overview

This guide will show you how to add a custom document type to your plugin. This includes adding a new document type to the database, creating a renderer for it, and adding a number range.

## Prerequisites

This guide is built upon the [plugin base guide](../../plugin-base-guide), but of course you can use those examples with any other plugin.

Furthermore, adding a custom document type via your plugin is done by using [plugin database migrations](../../plugin-fundamentals/database-migrations). Since this isn't explained in this guide, you will have to know and understand the plugin database migrations first.

## Adding a custom document type and its own base configuration to the database

Let's start with adding your custom document type to the database, so it's actually available for new document configurations. This is done by adding a plugin database migration. To be precise, we need to add an entry to the database table `document_type` table and an entry for each supported language to the `document_type_translation` table.

Let's have a look at an example migration:

::: code-group

```php [PLUGIN_ROOT/src/Migration/Migration1616677952AddDocumentType.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Migration\Traits\ImportTranslationsTrait;
use Shopware\Core\Framework\Uuid\Uuid;
use Shopware\Core\Migration\Traits\Translations;

class Migration1616677952AddDocumentType extends MigrationStep
{
    use ImportTranslationsTrait;
    
    final public const TYPE = 'example';
    
    public function getCreationTimestamp(): int
    {
        return 1616677952;
    }

    public function update(Connection $connection): void
    {
        $documentTypeId = Uuid::randomBytes();

        $connection->insert('document_type', [
            'id' => $documentTypeId,
            'technical_name' => self::TYPE,
            'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT)
        ]);

        $this->addTranslations($connection, $documentTypeId);
        $this->addDocumentBaseConfig($connection, $documentTypeId);
    }

    public function updateDestructive(Connection $connection): void
    {
    }

    private function addTranslations(Connection $connection, string $documentTypeId): void
    {
        $englishName = 'Example document type name';
        $germanName = 'Beispiel Dokumententyp Name';

        $documentTypeTranslations = new Translations(
            [
                'document_type_id' => $documentTypeId,
                'name' => $germanName,
            ],
            [
                'document_type_id' => $documentTypeId,
                'name' => $englishName,
            ]
        );

        $this->importTranslation(
            'document_type_translation',
            $documentTypeTranslations,
            $connection
        );
    }
    
    private function addDocumentBaseConfig(Connection $connection, string $documentTypeId): void
    {
        $defaultConfig = [
            'displayPrices' => true,
            'displayFooter' => true,
            'displayHeader' => true,
            'displayLineItems' => true,
            'diplayLineItemPosition' => true,
            'displayPageCount' => true,
            'displayCompanyAddress' => true,
            'pageOrientation' => 'portrait',
            'pageSize' => 'a4',
            'itemsPerPage' => 10,
            'companyName' => 'Example Company',
            'taxNumber' => '',
            'vatId' => '',
            'taxOffice' => '',
            'bankName' => '',
            'bankIban' => '',
            'bankBic' => '',
            'placeOfJurisdiction' => '',
            'placeOfFulfillment' => '',
            'executiveDirector' => '',
            'companyAddress' => '',
            'referencedDocumentType' => self::TYPE,
        ];

        $documentBaseConfigId = Uuid::randomBytes();

        $connection->insert(
            'document_base_config',
            [
                'id' => $documentBaseConfigId,
                'name' => self::TYPE,
                'global' => 1,
                'filename_prefix' => self::TYPE . '_',
                'document_type_id' => $documentTypeId,
                'config' => json_encode($defaultConfig, \JSON_THROW_ON_ERROR),
                'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
            ]
        );
        $connection->insert(
            'document_base_config_sales_channel',
            [
                'id' => Uuid::randomBytes(),
                'document_base_config_id' => $documentBaseConfigId,
                'document_type_id' => $documentTypeId,
                'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
            ]
        );
    }
}
```

:::

So first, we are creating the new document type with the `technical_name` as "example". Make sure to save the ID here since you are going to need it for the following translations:

Afterwards we're inserting the translations, one for German, one for English. For this we're using the `Shopware\Core\Migration\Traits\ImportTranslationsTrait`, which adds the helper method `importTranslation`. There you have to supply the translation table and an instance of `Shopware\Core\Migration\Traits\Translations`. The latter accepts two constructor parameters:

* An array of German translations, plus the respective ID column
* An array of English translations, plus the respective ID column

  It will then take care of properly inserting those translations.

And the last, We are creating the new document base configuration for the new document type to store some default configurations for our new document type.

After installing your plugin, your new document type should be available in the Administration. However, it wouldn't work yet, since every document type has to come with a respective `AbstractDocumentRenderer`. This is covered in the next section.

## Adding a renderer

The renderer for a document type is responsible for rendering the respective document, including a template. That is why we will have to create a custom renderer for the new type as well, lets call it `ExampleDocumentRenderer`.

We will place it in the same directory as all other default document renderers: `<plugin root>/src/Core/Checkout/Document/Renderer`

Your custom document renderer has to implement the `Shopware\Core\Checkout\Document\Renderer\AbstractDocumentRenderer`, which forces you to implement three methods:

* `getDecorated`: Shall return the decorated service (see decoration pattern adr).
* `supports`: Has to return a string of the document type it supports. We named our document type "**example**", so our renderer has to return "**example**".
* `render`: This needs to return the instance `Shopware\Core\Checkout\Document\Renderer\RendererResult`, which will contain the instance of `Shopware\Core\Checkout\Document\Renderer\RenderedDocument` based on each `orderId`. You will have access to the array of `DocumentGenerateOperation` which contains all respective orderIds, the context and the instance of `Shopware\Core\Checkout\Document\Renderer\DocumentRendererConfig` (additional configuration).

Furthermore, your renderer has to be registered to the [service container](../../plugin-fundamentals/dependency-injection) using the tag `document.renderer`.

Let's have a look at an example renderer:

::: code-group

```php [PLUGIN_ROOT/src/Core/Checkout/Document/Render/ExampleDocumentRenderer.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout\Document\Render;

use Shopware\Core\Checkout\Document\Renderer\AbstractDocumentRenderer;
use Shopware\Core\Checkout\Document\Renderer\DocumentRendererConfig;
use Shopware\Core\Checkout\Document\Renderer\RenderedDocument;
use Shopware\Core\Checkout\Document\Renderer\RendererResult;
use Shopware\Core\Checkout\Document\Service\DocumentConfigLoader;
use Shopware\Core\Checkout\Document\Service\DocumentFileRendererRegistry;
use Shopware\Core\Checkout\Document\Struct\DocumentGenerateOperation;
use Shopware\Core\Checkout\Order\OrderEntity;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\Framework\Plugin\Exception\DecorationPatternException;
use Shopware\Core\System\NumberRange\ValueGenerator\NumberRangeValueGeneratorInterface;

class ExampleDocumentRenderer extends AbstractDocumentRenderer
{
    public const DEFAULT_TEMPLATE = '@SwagBasicExample/documents/example_document.html.twig';

    final public const TYPE = 'example';

    /**
     * @internal
     */
    public function __construct(
        private readonly EntityRepository $orderRepository,
        private readonly DocumentConfigLoader $documentConfigLoader,
        private readonly NumberRangeValueGeneratorInterface $numberRangeValueGenerator,
        private readonly DocumentFileRendererRegistry $fileRendererRegistry,
    ) {
    }

    public function supports(): string
    {
        return self::TYPE;
    }

    /**
     * @param array<DocumentGenerateOperation> $operations
     */
    public function render(array $operations, Context $context, DocumentRendererConfig $rendererConfig): RendererResult
    {
        $ids = \array_map(fn (DocumentGenerateOperation $operation) => $operation->getOrderId(), $operations);

        if (empty($ids)) {
            return new RendererResult();
        }

        $result = new RendererResult();

        $criteria = new Criteria($ids);
        $criteria->addAssociation('language');
        $criteria->addAssociation('language.locale');

        $orders = $this->orderRepository->search($criteria, $context)->getEntities();
        foreach ($orders as $order) {
            $orderId = $order->getId();

            try {
                $operation = $operations[$orderId] ?? null;
                if ($operation === null) {
                    continue;
                }

                $config = clone $this->documentConfigLoader->load(self::TYPE, $order->getSalesChannelId(), $context);

                $config->merge($operation->getConfig());

                $number = $config->getDocumentNumber() ?: $this->getNumber($context, $order, $operation);

                $now = (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT);

                $config->merge([
                    'documentDate' => $operation->getConfig()['documentDate'] ?? $now,
                    'documentNumber' => $number,
                    'custom' => [
                        'invoiceNumber' => $number,
                    ],
                ]);

                // The document that uploaded by manual
                if ($operation->isStatic()) {
                    $doc = new RenderedDocument($number, $config->buildName(), $operation->getFileType(), $config->jsonSerialize());
                    $result->addSuccess($orderId, $doc);

                    continue;
                }

                $doc = new RenderedDocument(
                    $number,
                    $config->buildName(),
                    $operation->getFileType(),
                    $config->jsonSerialize(),
                );

                // Utilize the DocumentFileRendererRegistry to generate the content, e.g. PDF or HTML
                // This is the recommended approach
                $doc->setTemplate(self::DEFAULT_TEMPLATE);
                $doc->setOrder($order);
                $doc->setContext($context);
                $content = $this->fileRendererRegistry->render($doc);
                $doc->setContent($content);

                // Alternatively you can manually set the content here, e.g. to some XML or CSV content
                // $content = '<?xml ...>...';
                // or
                // $content = 'Id;Name;...';
                // $doc->setContent($content);

                $result->addSuccess($orderId, $doc);
            } catch (\Throwable $exception) {
                $result->addError($orderId, $exception);
            }
        }

        return $result;
    }

    public function getDecorated(): AbstractDocumentRenderer
    {
        throw new DecorationPatternException(self::class);
    }

    private function getNumber(Context $context, OrderEntity $order, DocumentGenerateOperation $operation): string
    {
        return $this->numberRangeValueGenerator->getValue(
            'document_' . self::TYPE,
            $context,
            $order->getSalesChannelId(),
            $operation->isPreview()
        );
    }
}
```

:::

We inject `orderRepository` to get all order entities by list of order's id, `documentConfigLoader` to load the document configuration and `numberRangeValueGenerator` to get the document number

The `supports` method just returns the string "**example**", which is the technical name of our new document type.

Now let's have a look at the `render` method. This function contains three parameters:

* `$operations`: An array of `DocumentGenerateOperation` objects.
* `$context`: A Context object.
* `$rendererConfig`: A `DocumentRendererConfig` object, so we can add additional configuration later.

The function returns a `RendererResult` object.
Here's what the function does:

* It creates an array of `$ids`, which is populated with the `orderId` of each `DocumentGenerateOperation` object in $operations.
* If `$ids` is empty, the function returns an empty `RendererResult` object.
* A search is performed on the order repository to find all orders by `$ids`.
* For each order found, the function attempts to generate a document.
* If successful, a new `RenderedDocument` object is created. This object is then added to the `RendererResult` object as a success.
* If an error occurs, the exception is caught and the error message is added to the `RendererResult` object as an error.
* The `RendererResult` object is returned.

Depending on the file type we either get the content with `$this->fileRendererRegistry->render()` or we need to create the content on our own.
`DocumentFileRendererRegistry` acts as a central registry for document file renderers based on file extensions (e.g., .pdf, .html). It delegates the rendering of documents to the appropriate renderer implementation.
Therefore, for each registered service that extends the `AbstractDocumentTypeRenderer`, the content of the document can be generated. New types of `AbstractDocumentTypeRenderer` services can be added with `document_type.renderer` as the tag name and the file extension as a key.

```xml
<service id="Shopware\Core\Checkout\Document\Service\PdfRenderer">
    ...
    <tag name="document_type.renderer" key="pdf"/>
</service>
```

### Adding a document type template

Let's have a quick look at an example document type template. Go ahead and create a new file at the path `<plugin root>/src/Resources/views/documents/example_document.html.twig`.

In there, you should extend from the default document base template:

:::code-group

```twig [PLUGIN_ROOT/src/Resources/views/documents/example_document.html.twig]
{% sw_extends '@Framework/documents/base.html.twig' %}
```

:::

This could be it already. The [base.html.twig](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Core/Framework/Resources/views/documents/base.html.twig) template comes with a lot of default templating, which you can now override by using blocks. If you don't know how that's done, have a look at our guide regarding [customizing templates](../../storefront/customize-templates).

## Adding a number range

You are almost done here. You have a new document type in the database, a renderer for your new document type, and it even uses a custom template. However, you also need to add a new number range for your documents; otherwise, a new number wouldn't be generated for your documents.

Adding a new number range is also done by using a [plugin database migration](../../plugin-fundamentals/database-migrations).

For this we need a few more things:

* An entry in `number_range_type`, which is just a new type of number range with a technical name
* An entry in `number_range`, which represents a properly configured number range, which then will use the previously created type
* An entry in `number_range_sales_channel` to assign a sales channel to our configured number range
* An entry for each language in the tables `number_range_translation` and `number_range_type_translation`

Sounds like a lot, but having a look at an example migration, you will notice that it's not too much of a hassle.

::: code-group

```php [PLUGIN_ROOT/src/Migration/Migration1616974646AddDocumentNumberRange.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Framework\Uuid\Uuid;
use Shopware\Core\Migration\Traits\ImportTranslationsTrait;
use Shopware\Core\Migration\Traits\Translations;

class Migration1616974646AddDocumentNumberRange extends MigrationStep
{
    use ImportTranslationsTrait;

    public function getCreationTimestamp(): int
    {
        return 1616974646;
    }

    public function update(Connection $connection): void
    {
        $numberRangeId = Uuid::randomBytes();
        $numberRangeTypeId = Uuid::randomBytes();

        $this->insertNumberRange($connection, $numberRangeId, $numberRangeTypeId);
        $this->insertTranslations($connection, $numberRangeId, $numberRangeTypeId);

    }

    public function updateDestructive(Connection $connection): void
    {
    }

    private function insertNumberRange(Connection $connection, string $numberRangeId, string $numberRangeTypeId): void
    {
        $connection->insert('number_range_type', [
            'id' => $numberRangeTypeId,
            'global' => 0,
            'technical_name' => 'document_example',
            'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT)
        ]);

        $connection->insert('number_range', [
            'id' => $numberRangeId,
            'type_id' => $numberRangeTypeId,
            'global' => 0,
            'pattern' => '{n}',
            'start' => 10000,
            'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT)
        ]);

        $storefrontSalesChannelId = $this->getStorefrontSalesChannelId($connection);
        if (!$storefrontSalesChannelId) {
            return;
        }

        $connection->insert('number_range_sales_channel', [
            'id' => Uuid::randomBytes(),
            'number_range_id' => $numberRangeId,
            'sales_channel_id' => $storefrontSalesChannelId,
            'number_range_type_id' => $numberRangeTypeId,
            'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT)
        ]);
    }

    private function getStorefrontSalesChannelId(Connection $connection): ?string
    {
        $sql = <<<SQL
            SELECT id
            FROM sales_channel
            WHERE type_id = :typeId
SQL;
        $salesChannelId = $connection->fetchOne($sql, [
            'typeId' => Uuid::fromHexToBytes(Defaults::SALES_CHANNEL_TYPE_STOREFRONT)
        ]);

        if (!$salesChannelId) {
            return null;
        }

        return $salesChannelId;
    }

    private function insertTranslations(Connection $connection, string $numberRangeId, string $numberRangeTypeId): void
    {
        $numberRangeTranslations = new Translations(
            [
                'number_range_id' => $numberRangeId,
                'name' => 'Beispiel',
            ],
            [
                'number_range_id' => $numberRangeId,
                'name' => 'Example',
            ]
        );

        $numberRangeTypeTranslations = new Translations(
            [
                'number_range_type_id' => $numberRangeTypeId,
                'type_name' => 'Beispiel',
            ],
            [
                'number_range_type_id' => $numberRangeTypeId,
                'type_name' => 'Example',
            ]
        );

        $this->importTranslation(
            'number_range_translation',
            $numberRangeTranslations,
            $connection
        );

        $this->importTranslation(
            'number_range_type_translation',
            $numberRangeTypeTranslations,
            $connection
        );
    }
}
```

:::

As already said, we're first creating the entries in the tables `number_range`, `number_range_type` and `number_range_sales_channel`. For the latter, we're assigning a Storefront sales channel, if any available. Make sure to check here, since in theory there could be no storefront sales channel.

Afterward we import the translations for the `number_range_translation` and the `number_range_type_translation` tables by using the `ImportTranslationsTrait` once again.

And that's it now. You Have just created:

* A custom document type, including translations
* A custom document renderer
* A custom number range and number range type, which will now be used by your custom document type

## Next steps

With your custom document type, you also might want to add a new actual document configuration, which is making use of your new type. Creating a custom document is explained in [this guide](add-custom-document).

---

---
url: /docs/guides/plugins/plugins/framework/event/add-custom-event.md
---

# Add Custom Event

## Overview

In this guide, you will learn how to create your own event. You can read more about events in the [Symfony documentation](https://symfony.com/doc/current/event_dispatcher.html).

## Prerequisites

To create your own event for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../../plugin-base-guide).

::: info
Refer to this video on **[Event dispatching and handling](https://www.youtube.com/watch?v=JBpa5nBoC78)** which is a live coding example on custom events. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

## Event interfaces and classes

In Shopware, you have multiple interfaces and classes for different types of events, in the following you can find a list of them:

* `ShopwareEvent`: This interface is just a basic event providing a `Context` we need for almost all events.
* `ShopwareSalesChannelEvent`: This interface extends from `ShopwareEvent` and additionally provides a `SalesChannelContext`.
* `SalesChannelAware`: This interface provides the `SalesChannelId`.
* `GenericEvent`: This interface will be used if you want to give your event a specific name like the database events (e.g. `product.written.`). Otherwise, you have to reference to the event class.
* `NestedEvent`: This class will be used for events using other events, for example, the `EntityDeletedEvent` extends from the `EntityWrittenEvent`.
* `BusinessEventInterface`: This interface extends from `ShopwareEvent` and will be used for dynamic assignment and is always named.

## Create the event class

First, we create a new class for our event, which we name `ExampleEvent`. In this example we implement the `Shopware\Core\Framework\Event\ShopwareSalesChannelEvent`. As mentioned above our class already implements a method for the `SalesChannelContext` and the `Context`. Now we pass an `ExampleEntity` and the `SalesChannelContext` through the constructor and create a function which returns our `ExampleEntity`.

Therefore, this is what your event class could look like:

```php
// <plugin root>/src/Core/Content/Example/Event/ExampleEvent.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\Event;

use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\Event\ShopwareSalesChannelEvent;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Swag\BasicExample\Core\Content\Example\ExampleEntity;

class ExampleEvent implements ShopwareSalesChannelEvent
{
    protected ExampleEntity $exampleEntity;

    protected SalesChannelContext $salesChannelContext;

    public function __construct(ExampleEntity $exampleEntity, SalesChannelContext $context)
    {
        $this->exampleEntity = $exampleEntity;
        $this->salesChannelContext = $context;
    }

    public function getExample(): ExampleEntity
    {
        return $this->exampleEntity;
    }

    public function getContext(): Context
    {
        return $this->salesChannelContext->getContext();
    }

    public function getSalesChannelContext(): SalesChannelContext
    {
        return $this->salesChannelContext;
    }
}
```

## Fire the event

After we've created our event class, we need to fire our new event. For this we need the service `event_dispatcher` which provides a method called `dispatch`. In this example we created a service `ExampleEventService` which fires our event. Below, you can find the example implementation.

```php
// <plugin root>/src/Service/ExampleEventService.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Swag\BasicExample\Core\Content\Example\Event\ExampleEvent;
use Swag\BasicExample\Core\Content\Example\ExampleEntity;
use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;

class ExampleEventService
{
    private EventDispatcherInterface $eventDispatcher;

    public function __construct(EventDispatcherInterface $eventDispatcher)
    {
        $this->eventDispatcher = $eventDispatcher;
    }

    public function fireEvent(ExampleEntity $exampleEntity, SalesChannelContext $context)
    {
        $this->eventDispatcher->dispatch(new ExampleEvent($exampleEntity, $context));
    }
}
```

## Next steps

Now that you know how to create your own event, read the [Listening to events](../../framework/event/listening-to-events.md) guide for information on applying it.

---

---
url: /docs/v6.5/guides/plugins/plugins/framework/event/add-custom-event.md
---

# Add Custom Event

## Overview

In this guide, you will learn how to create your own event. You can read more about events in the [Symfony documentation](https://symfony.com/doc/current/event_dispatcher.html).

## Prerequisites

To create your own event for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../../plugin-base-guide).

::: info
Refer to this video on **[Event dispatching and handling](https://www.youtube.com/watch?v=JBpa5nBoC78)** which is a live coding example on custom events. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

## Event interfaces and classes

In Shopware, you have multiple interfaces and classes for different types of events, in the following you can find a list of them:

* `ShopwareEvent`: This interface is just a basic event providing a `Context` we need for almost all events.
* `ShopwareSalesChannelEvent`: This interface extends from `ShopwareEvent` and additionally provides a `SalesChannelContext`.
* `SalesChannelAware`: This interface provides the `SalesChannelId`.
* `GenericEvent`: This interface will be used if you want to give your event a specific name like the database events (e.g. `product.written.`). Otherwise, you have to reference to the event class.
* `NestedEvent`: This class will be used for events using other events, for example, the `EntityDeletedEvent` extends from the `EntityWrittenEvent`.
* `BusinessEventInterface`: This interface extends from `ShopwareEvent` and will be used for dynamic assignment and is always named.

## Create the event class

First, we create a new class for our event, which we name `ExampleEvent`. In this example we implement the `Shopware\Core\Framework\Event\ShopwareSalesChannelEvent`. As mentioned above our class already implements a method for the `SalesChannelContext` and the `Context`. Now we pass an `ExampleEntity` and the `SalesChannelContext` through the constructor and create a function which returns our `ExampleEntity`.

Therefore, this is what your event class could look like:

```php
// <plugin root>/src/Core/Content/Example/Event/ExampleEvent.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\Event;

use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\Event\ShopwareSalesChannelEvent;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Swag\BasicExample\Core\Content\Example\ExampleEntity;

class ExampleEvent implements ShopwareSalesChannelEvent
{
    protected ExampleEntity $exampleEntity;

    protected SalesChannelContext $salesChannelContext;

    public function __construct(ExampleEntity $exampleEntity, SalesChannelContext $context)
    {
        $this->exampleEntity = $exampleEntity;
        $this->salesChannelContext = $context;
    }

    public function getExample(): ExampleEntity
    {
        return $this->exampleEntity;
    }

    public function getContext(): Context
    { 
        return $this->salesChannelContext->getContext();
    }

    public function getSalesChannelContext(): SalesChannelContext
    {
        return $this->salesChannelContext;
    }
}
```

## Fire the event

After we've created our event class, we need to fire our new event. For this we need the service `event_dispatcher` which provides a method called `dispatch`. In this example we created a service `ExampleEventService` which fires our event. Below, you can find the example implementation.

```php
// <plugin root>/src/Service/ExampleEventService.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Swag\BasicExample\Core\Content\Example\Event\ExampleEvent;
use Swag\BasicExample\Core\Content\Example\ExampleEntity;
use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;

class ExampleEventService
{
    private EventDispatcherInterface $eventDispatcher;

    public function __construct(EventDispatcherInterface $eventDispatcher)
    {
        $this->eventDispatcher = $eventDispatcher;
    }

    public function fireEvent(ExampleEntity $exampleEntity, SalesChannelContext $context)
    {
        $this->eventDispatcher->dispatch(new ExampleEvent($exampleEntity, $context));
    }
}
```

## Next steps

Now that you know how to create your own event, you may want to act on it. To get a grip on this, head over to our [Listening to events](../../plugin-fundamentals/listening-to-events) guide.

---

---
url: /docs/v6.6/guides/plugins/plugins/framework/event/add-custom-event.md
---

# Add Custom Event

## Overview

In this guide, you will learn how to create your own event. You can read more about events in the [Symfony documentation](https://symfony.com/doc/current/event_dispatcher.html).

## Prerequisites

To create your own event for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../../plugin-base-guide).

::: info
Refer to this video on **[Event dispatching and handling](https://www.youtube.com/watch?v=JBpa5nBoC78)** which is a live coding example on custom events. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

## Event interfaces and classes

In Shopware, you have multiple interfaces and classes for different types of events, in the following you can find a list of them:

* `ShopwareEvent`: This interface is just a basic event providing a `Context` we need for almost all events.
* `ShopwareSalesChannelEvent`: This interface extends from `ShopwareEvent` and additionally provides a `SalesChannelContext`.
* `SalesChannelAware`: This interface provides the `SalesChannelId`.
* `GenericEvent`: This interface will be used if you want to give your event a specific name like the database events (e.g. `product.written.`). Otherwise, you have to reference to the event class.
* `NestedEvent`: This class will be used for events using other events, for example, the `EntityDeletedEvent` extends from the `EntityWrittenEvent`.
* `BusinessEventInterface`: This interface extends from `ShopwareEvent` and will be used for dynamic assignment and is always named.

## Create the event class

First, we create a new class for our event, which we name `ExampleEvent`. In this example we implement the `Shopware\Core\Framework\Event\ShopwareSalesChannelEvent`. As mentioned above our class already implements a method for the `SalesChannelContext` and the `Context`. Now we pass an `ExampleEntity` and the `SalesChannelContext` through the constructor and create a function which returns our `ExampleEntity`.

Therefore, this is what your event class could look like:

```php
// <plugin root>/src/Core/Content/Example/Event/ExampleEvent.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\Event;

use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\Event\ShopwareSalesChannelEvent;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Swag\BasicExample\Core\Content\Example\ExampleEntity;

class ExampleEvent implements ShopwareSalesChannelEvent
{
    protected ExampleEntity $exampleEntity;

    protected SalesChannelContext $salesChannelContext;

    public function __construct(ExampleEntity $exampleEntity, SalesChannelContext $context)
    {
        $this->exampleEntity = $exampleEntity;
        $this->salesChannelContext = $context;
    }

    public function getExample(): ExampleEntity
    {
        return $this->exampleEntity;
    }

    public function getContext(): Context
    { 
        return $this->salesChannelContext->getContext();
    }

    public function getSalesChannelContext(): SalesChannelContext
    {
        return $this->salesChannelContext;
    }
}
```

## Fire the event

After we've created our event class, we need to fire our new event. For this we need the service `event_dispatcher` which provides a method called `dispatch`. In this example we created a service `ExampleEventService` which fires our event. Below, you can find the example implementation.

```php
// <plugin root>/src/Service/ExampleEventService.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Swag\BasicExample\Core\Content\Example\Event\ExampleEvent;
use Swag\BasicExample\Core\Content\Example\ExampleEntity;
use Symfony\Contracts\EventDispatcher\EventDispatcherInterface;

class ExampleEventService
{
    private EventDispatcherInterface $eventDispatcher;

    public function __construct(EventDispatcherInterface $eventDispatcher)
    {
        $this->eventDispatcher = $eventDispatcher;
    }

    public function fireEvent(ExampleEntity $exampleEntity, SalesChannelContext $context)
    {
        $this->eventDispatcher->dispatch(new ExampleEvent($exampleEntity, $context));
    }
}
```

## Next steps

Now that you know how to create your own event, you may want to act on it. To get a grip on this, head over to our [Listening to events](../../plugin-fundamentals/listening-to-events) guide.

---

---
url: /docs/guides/plugins/plugins/framework/custom-field/add-custom-field.md
---

# Add Custom Field

## Overview

Shopware's custom field system allows you to extend entities without writing a complete entity extension. This is possible by storing the additional data in a [JSON-Field](https://dev.mysql.com/doc/refman/8.0/en/json.html). Custom fields, therefore, can only be used to store scalar values. If you'd like to create associations between entities, you'll need to use an [Entity extension](../data-handling/add-complex-data-to-existing-entities).

This guide will cover two similar subjects:

* Supporting custom fields with your entity
* Add custom fields to an entity

## Prerequisites

This guide is built upon both the [Plugin base guide](../../plugin-base-guide) and the [Add custom complex data](../data-handling/add-custom-complex-data) guide. The latter explained how to create your very first entity, which is used in the following examples.

Since migrations will also be used here, it won't hurt to have a look at our guide about [Executing database queries](../../database/database-migrations.md).

Also, adding translatable custom fields is covered here in short as well, for which you'll need to understand how translatable entities work in general. This is covered in our guide about [Adding data translations](../data-handling/add-data-translations). This subject will **not** be covered in depth in this guide.

## Supporting custom fields with your entity

This short section will cover how to add a custom field support for your custom entity. As previously mentioned, the example from our [Add custom complex data](../data-handling/add-custom-complex-data) guide is used and extended here.

To support custom fields with your custom entity, there are three necessary steps :

* Add `EntityCustomFieldsTrait` trait to your `Entity`.
* Add a `CustomFields` field to your `EntityDefinition`.
* Add a column `custom_fields` to your entities' database table via migration.

Also, you may want to add translatable custom fields, which is also covered in very short here.

### Add a custom field to an entity

::: info
Available starting with Shopware 6.4.1.0.
:::

Let's assume you already got a working and running entity definition. If you want to support custom fields with your custom entity, you may add the `EntityCustomFieldsTrait` to your entity class, so the methods `getCustomFields()` and `setCustomFields()` can be used.

```php
// <plugin root>/src/Core/Content/Example/ExampleEntity.php
use Shopware\Core\Framework\DataAbstractionLayer\Entity;
use Shopware\Core\Framework\DataAbstractionLayer\EntityCustomFieldsTrait;
use Shopware\Core\Framework\DataAbstractionLayer\EntityIdTrait;

[...]
class ExampleEntity extends Entity
{
    use EntityIdTrait;
    use EntityCustomFieldsTrait;

    [...]

}
```

### Add a custom field to entity definition

Now follows the important part. For this to work, you have to add the Data Abstraction Layer (DAL) field `CustomFields` to your entity definition.

```php
// <plugin root>/src/Core/Content/Example/ExampleDefinition.php
use Shopware\Core\Framework\DataAbstractionLayer\Field\CustomFields;

[...]
class ExampleDefinition extends EntityDefinition
{

    [...]

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
            (new StringField('name', 'name')),
            (new StringField('description', 'description')),
            (new BoolField('active', 'active')),

            new CustomFields()
        ]);
    }
}
```

Note the new field that was added in the `FieldCollection`. That's already it for your custom entity definition. Now go ahead and add the column to the database.

### Add a column in the database table

Once again, this example is built upon the [Add custom complex data](../data-handling/add-custom-complex-data) guide, which also comes with an example migration. This one will be used in this example here as well.

If you want to support custom fields now, you have to add a new column `custom_fields` of type `JSON` to your migration.

```php
// <plugin root>/src/Migration/Migration1611664789Example.php
public function update(Connection $connection): void
{
    $sql = <<<SQL
        CREATE TABLE IF NOT EXISTS `swag_example` (
        `id` BINARY(16) NOT NULL,
        `name` VARCHAR(255) COLLATE utf8mb4_unicode_ci,
        `description` VARCHAR(255) COLLATE utf8mb4_unicode_ci,
        `active` TINYINT(1) COLLATE utf8mb4_unicode_ci,

        `custom_fields` json DEFAULT NULL,

        `created_at` DATETIME(3) NOT NULL,
        `updated_at` DATETIME(3),
        PRIMARY KEY (`id`)
        )
        ENGINE = InnoDB
        DEFAULT CHARSET = utf8mb4
        COLLATE = utf8mb4_unicode_ci;
    SQL;
    $connection->executeStatement($sql);
}
```

Note the new `custom_fields` column here. It has to be a JSON field and should default to `NULL`, since it doesn't have to contain values.

### Add translatable custom field to entity definition

Make sure to understand entity translations in general first, which is explained here [Add data translations](../data-handling/add-data-translations). If you want your custom fields to be translatable, you can simply work with a `TranslatedField` here as well.

```php
// <plugin root>/src/Core/Content/Example/ExampleDefinition.php
use Shopware\Core\Framework\DataAbstractionLayer\Field\TranslatedField;

[...]

class ExampleDefinition extends EntityDefinition
{
    [...]

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
            (new StringField('name', 'name')),
            (new StringField('description', 'description')),
            (new BoolField('active', 'active')),

            new TranslatedField('customFields'),
        ]);
    }
}
```

Just add the `TranslatedField` and apply `customFields` as a parameter.

In your translated entity definition, you then add the `CustomFields` field instead.

```php
// <plugin root>/src/Core/Content/Example/Aggregate/ExampleTranslation/ExampleTranslationDefinition.php
use Shopware\Core\Framework\DataAbstractionLayer\Field\CustomFields;

[...]
class ExampleTranslationDefinition extends EntityTranslationDefinition
{
    [...]

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new StringField('name', 'name'))->addFlags(new Required()),

            new CustomFields()
        ]);
    }
}
```

## Add custom fields to an entity

The previous section was about adding support for custom fields in your entity, but this section will cover how to add an actual custom field to an entity and how to fill it with data.

Technically, there is no need to define a custom field set and its fields first, before actually inserting values into the `custom_fields` column of your entities' database table via the DAL. Defining a custom field set is only necessary, if you want it to be editable in the Administration or if you need validation when writing your custom field.

Because of that, we'll start with filling data to an actual entities' custom field, before actually defining it.

### Filling data into custom fields

So let's assume you've got your own `example` entity up and running, and now you want to add data to its custom fields via the DAL.

In that case, you can use your entities' repository and start creating or updating entities with custom fields. If you don't understand what's going on here, head over to our guide about [Writing data](../data-handling/writing-data) first.

```php
$this->swagExampleRepository->upsert([[
    'id' => '<your ID here>',
    'customFields' => ['swag_example_size' => 15]
]], $context);
```

This will execute perfectly fine, and you just saved a custom field with name `swag_example_size` with its value `15` to your entity. And you haven't even defined the custom field `swag_example_size` yet.

As already mentioned, you do not have to define a custom field first before saving it. That's because there is no validation happening here yet, you can write whatever valid JSON you want to that column, so the following example would also execute without any issues:

```php
$this->swagExampleRepository->upsert([[
    'id' => '<your ID here>',
    'customFields' => [ 'foo' => 'bar', 'baz' => [] ]
]], $context);
```

### Declarative custom fields via `Resources/config/custom-fields.xml`

::: info
Available starting with Shopware 6.7.13.0.
:::

Instead of registering custom field sets imperatively through plugin lifecycle hooks (see [Add a custom field to the Administration](#add-a-custom-field-to-the-administration) below), you can define them declaratively in a `Resources/config/custom-fields.xml` file shipped with your plugin (under `src`). Shopware then handles creation, updates, and removal automatically during the plugin lifecycle (`install`, `update`, `uninstall`) — no `CustomFieldsInstaller` service or lifecycle hooks required.

Place the file at `<plugin root>/src/Resources/config/custom-fields.xml`:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<custom-fields xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/CustomField/Schema/custom-fields-1.0.xsd">
    <!-- register each custom field set you may want to add -->
    <custom-field-set>
        <!-- the technical name of the custom field set, needs to be unique, therefore use your vendor prefix -->
        <name>swag_example_set</name>
        <!-- Translatable, the label of the field set -->
        <label>Example Set</label>
        <label lang="de-DE">Beispiel-Set</label>
        <!-- define the entities to which your field set should be assigned -->
        <related-entities>
            <product/>
        </related-entities>
        <!-- define the fields in your set -->
        <fields>
            <!-- the element type defines the type of the field -->
            <!-- the name needs to be unique, therefore use your vendor prefix -->
            <int name="swag_example_weight">
                <!-- Translatable, the label of the field -->
                <label>Weight</label>
                <!-- Optional, Default = 1, order your fields by specifying the position -->
                <position>1</position>
            </int>
            <text name="swag_example_code">
                <label>Example field</label>
                <position>2</position>
                <!-- Optional, Default = false, mark a field as required -->
                <required>false</required>
                <!-- Optional, Translatable, the help text for the field -->
                <help-text>Example field</help-text>
            </text>
        </fields>
    </custom-field-set>
</custom-fields>

```

On every `install` or `update`, Shopware syncs the defined sets:

* Sets and fields present in the XML are created or updated.
* Sets and fields that were previously defined by your plugin but are no longer in the XML are removed.
* On `uninstall` (without keeping user data), the plugin's custom field sets are removed.

::: warning
The names of the custom fields are global and should always contain a vendor prefix, like "swag" for "Shopware AG", to keep them unique. This applies to the name of the custom field set as well as to each field name.
:::

The XML format is identical to the one [apps use in their manifest](../../../apps/custom-data/custom-fields.md). For a full list of available field types and their configuration options, refer to the [custom field section of the Manifest reference](../../../../../resources/references/app-reference/manifest-reference.md).

If you only need your custom fields to be available declaratively, you can stop here. The remaining sections describe the imperative alternative using the `custom_field_set.repository`, which you only need when creating sets dynamically at runtime.

### Add a custom field to the Administration

You can skip this section if you don't want your new custom field to be editable in the Administration.

So now you've already filled the custom fields of one of your entity instances via code. But what if you want your user to do that, which is the more common case?

Only if you want your custom field to show up in the Administration and to be editable in there, you have to define the custom fields first in a custom field set. For this you have to use the custom fieldset repository, which can be retrieved from the dependency injection container via the `custom_field_set.repository` key and is used like any other repository.

::: info
For most plugins, the [declarative `Resources/config/custom-fields.xml`](#declarative-custom-fields-via-resources-config-custom-fields-xml) approach is the simpler choice. Use the imperative approach below only when you need to create custom field sets dynamically at runtime.
:::

```php
// <plugin root>/src/Resources/config/services.php
<?php declare(strict_types=1);

use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Swag\BasicExample\CustomFieldClass;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(CustomFieldClass::class)
        ->args([service('custom_field_set.repository')]);
};
```

If you need to learn how that is done in full, head to our guide regarding [Writing data](../data-handling/writing-data).

Now use the `create` method of the repository to create a new custom field set.
Plugin lifecycle events are perfect for this as the container can provide the `custom_field_set.repository` service and can be used to set up on installation and remove the set on removal.

```php
use Shopware\Core\System\CustomField\CustomFieldTypes;
use \Shopware\Core\Defaults;

[...]

$this->customFieldSetRepository->create([
    [
        'name' => 'swag_example_set',
        'global' => true,
        'config' => [
            'label' => [
                'en-GB' => 'English custom field set label',
                'de-DE' => 'German custom field set label',
                Defaults::LANGUAGE_SYSTEM => "Mention the fallback label here"
            ]
        ],
        'customFields' => [
            [
                'name' => 'swag_example_size',
                'type' => CustomFieldTypes::INT,
                'includeInSearch' => true,
                'config' => [
                    'label' => [
                        'en-GB' => 'English custom field label',
                        'de-DE' => 'German custom field label',
                        Defaults::LANGUAGE_SYSTEM => "Mention the fallback label here"
                    ],
                    'customFieldPosition' => 1
                ]
            ]
        ]
    ]
], $context);
```

This will now create a custom field set with the name `swag_example_set` and the field, `swag_example_size`. This time we also define its type, which should be of type integer here. The type is important to mention because the Administration will use this information to display a proper field. Also, when trying to write the custom field `swag_example_size`, the value has to be an integer.

The translated labels are added to both the field and the set, which are going to be displayed in the Administration. Also, the fallback language can be defined in case the system language is not guaranteed to be either en\_GB or de\_DE.

If you have several custom fields and want to order them within a specific order, you can do so with the `customFieldPosition` property.

::: info
Available starting with Shopware 6.7.6.0.
:::

By default, custom fields are **not searchable**. To make a custom field searchable, you need to set the `includeInSearch` property to `true` when creating the custom field. Only custom fields explicitly marked as searchable are available in search configurations. This helps optimize index storage size and improve search performance, especially for stores with many custom fields.

If you enable searchability for an existing product custom field, you must rebuild the search index or update the products manually to include the custom field data in search results.

::: info
If you want the custom field set to be deletable and editable in the administration, you need to set global to false
:::

While theoretically your custom field is now properly defined for the Administration, you'll still have to do some work in your custom entities' Administration module. Head over to this guide to learn how to add your field to the Administration:

### Deleting a custom field

On uninstallation of your plugin, you should remove your custom field definition.
To update or delete a `custom_field_set`, you can use the standard repository methods like `update`, `upsert`, or `delete`:

```php
$setId = $this->customFieldSetRepository->searchIds((new Criteria())->addFilter(new EqualsFilter('name', 'swag_example_set')), $context)->firstId();
$this->customFieldSetRepository->delete([['id' => $setId]], $context);
```

When you delete a custom field in a set or a complete set, you should remove the values from the entity's customFields property. Without the custom field definition, the data is still taking up space, and some checks regarding API usage are no longer performed.
This batch operation is fast in SQL with a query like:

```sql
UPDATE swag_example SET custom_fields = JSON_REMOVE(custom_fields, '$.swag_example_size') WHERE JSON_CONTAINS_PATH(custom_fields, 'one', '$.swag_example_size');
```

If you have a table with a lot of data, like orders or products, you should not approach it carelessly to avoid overwhelming the database with too many changes at once.
This can look like this instead:

```php
$updateLimit = 1000;

do {
    $ids = $connection->fetchFirstColumn(
        'SELECT `id` FROM `order` WHERE JSON_CONTAINS_PATH(`custom_fields`, \'one\', \'$.swag_example_size\') LIMIT :limit',
        ['limit' => $updateLimit],
        ['limit' => ParameterType::INTEGER]
    );

    if ($ids === []) {
        break;
    }

    $connection->executeStatement(
        'UPDATE `order` SET `custom_fields` = JSON_REMOVE(`custom_fields`, \'$.swag_example_size\') WHERE `id` IN (:ids)',
        ['ids' => $ids],
        ['ids' => ArrayParameterType::BINARY]
    );
} while (\count($ids) === $updateLimit);
```

## Next steps

If you want to extend an entity with new associations and non-scalar values, head over to our guide regarding [Extending existing entities](../data-handling/add-complex-data-to-existing-entities).

---

---
url: /docs/v6.5/guides/plugins/plugins/framework/custom-field/add-custom-field.md
---

# Add Custom Field

## Overview

Shopware's custom field system allows you to extend entities, without writing a complete entity extension. This is possible by storing the additional data in a [JSON-Field](https://dev.mysql.com/doc/refman/8.0/en/json.html). Custom fields therefore can only be used to store scalar values. If you'd like to create associations between entities, you'll need to use an [Entity extension](../data-handling/add-complex-data-to-existing-entities).

This guide will cover two similar subjects:

* Supporting custom fields with your entity
* Add custom fields to an entity

## Prerequisites

This guide is built upon both the [Plugin base guide](../../plugin-base-guide) as well as the [Add custom complex data](../data-handling/add-custom-complex-data) guide. The latter explained how to create your very first entity, which is used in the following examples.

Since migrations will also be used here, it won't hurt to have a look at our guide about [Executing database queries](../../plugin-fundamentals/database-migrations).

Also, adding translatable custom fields is covered here in short as well, for which you'll need to understand how translatable entities work in general. This is covered in our guide about [Adding data translations](../data-handling/add-data-translations). This subject will **not** be covered in depth in this guide.

## Supporting custom fields with your entity

This short section will cover how to add a custom field support for your custom entity. As previously mentioned, the example from our [Add custom complex data](../data-handling/add-custom-complex-data) guide is used and extended here.

In order to support custom fields with your custom entity, there are three necessary steps :

* Add `EntityCustomFieldsTrait` trait to your `Entity`.
* Add a `CustomFields` field to your `EntityDefinition`.
* Add a column `custom_fields` to your entities' database table via migration.

Also, you may want to add translatable custom fields, which is also covered in very short here.

### Add custom field to entity

::: info
Available starting with Shopware 6.4.1.0.
:::

Let's assume you already got a working and running entity definition. If you want to support custom fields with your custom entity, you may add the `EntityCustomFieldsTrait` to your entity class, so the methods `getCustomFields()` and `setCustomFields()` can be used.

```php
// <plugin root>/src/Core/Content/Example/ExampleEntity.php
use Shopware\Core\Framework\DataAbstractionLayer\Entity;
use Shopware\Core\Framework\DataAbstractionLayer\EntityCustomFieldsTrait;
use Shopware\Core\Framework\DataAbstractionLayer\EntityIdTrait;

[...]
class ExampleEntity extends Entity
{
    use EntityIdTrait;
    use EntityCustomFieldsTrait;

    [...]

}
```

### Add custom field to entity definition

Now follows the important part. For this to work, you have to add the Data Abstraction Layer (DAL) field `CustomFields` to your entity definition.

```php
// <plugin root>/src/Core/Content/Example/ExampleDefinition.php
use Shopware\Core\Framework\DataAbstractionLayer\Field\CustomFields;                                                                    

[...]
class ExampleDefinition extends EntityDefinition
{

    [...]

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
            (new StringField('name', 'name')),
            (new StringField('description', 'description')),
            (new BoolField('active', 'active')),

            new CustomFields()
        ]);
    }
}
```

Note the new field that was added in the `FieldCollection`. That's already it for your custom entity definition. Now go ahead and add the column to the database.

### Add column in database table

Once again, this example is built upon the [Add custom complex data](../data-handling/add-custom-complex-data) guide, which also comes with an example migration. This one will be used in this example here as well.

If you want to support custom fields now, you have to add a new column `custom_fields` of type `JSON` to your migration.

```php
// <plugin root>/src/Migration/Migration1611664789Example.php
public function update(Connection $connection): void
{
    $sql = <<<SQL
        CREATE TABLE IF NOT EXISTS `swag_example` (
        `id` BINARY(16) NOT NULL,
        `name` VARCHAR(255) COLLATE utf8mb4_unicode_ci,
        `description` VARCHAR(255) COLLATE utf8mb4_unicode_ci,
        `active` TINYINT(1) COLLATE utf8mb4_unicode_ci,

        `custom_fields` json DEFAULT NULL,

        `created_at` DATETIME(3) NOT NULL,
        `updated_at` DATETIME(3),
        PRIMARY KEY (`id`)
        )
        ENGINE = InnoDB
        DEFAULT CHARSET = utf8mb4
        COLLATE = utf8mb4_unicode_ci;
    SQL;
    $connection->executeStatement($sql);
}
```

Note the new `custom_fields` column here. It has to be a JSON field and should default to `NULL`, since it doesn't have to contain values.

### Add translatable custom field to entity definition

Make sure to understand entity translations in general first, which is explained here [Add data translations](../data-handling/add-data-translations). If you want your custom fields to be translatable, you can simply work with a `TranslatedField` here as well.

```php
// <plugin root>/src/Core/Content/Example/ExampleDefinition.php
use Shopware\Core\Framework\DataAbstractionLayer\Field\TranslatedField;                                                               

[...]

class ExampleDefinition extends EntityDefinition
{
    [...]

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
            (new StringField('name', 'name')),
            (new StringField('description', 'description')),
            (new BoolField('active', 'active')),

            new TranslatedField('customFields'),
        ]);
    }
}
```

Just add the `TranslatedField` and apply `customFields` as a parameter.

In your translated entity definition, you then add the `CustomFields` field instead.

```php
// <plugin root>/src/Core/Content/Example/Aggregate/ExampleTranslation/ExampleTranslationDefinition.php
use Shopware\Core\Framework\DataAbstractionLayer\Field\CustomFields;                                                                    

[...]
class ExampleTranslationDefinition extends EntityTranslationDefinition
{
    [...]

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new StringField('name', 'name'))->addFlags(new Required()),

            new CustomFields()
        ]);
    }
}
```

## Add custom fields to an entity

The previous section was about adding support for custom fields in your entity, but this section will cover how to add an actual custom field to an entity and how to fill it with data.

Technically, there is no need to define a custom field set and its fields first, before actually inserting values into the `custom_fields` column of your entities' database table via the DAL. Defining a custom field set is only necessary, if you want it to be editable in the Administration or if you need validation when writing your custom field.

Because of that, we'll start with filling data to an actual entities' custom field, before actually defining it.

### Filling data into custom fields

So let's assume you've got your own `example` entity up and running and now you want to add data to its custom fields via the DAL.

For that case, you can simply use your entities' repository and start creating or updating entities with custom fields. If you don't understand what's going on here, head over to our guide about [Writing data](../data-handling/writing-data) first.

```php
$this->swagExampleRepository->upsert([[
    'id' => '<your ID here>',
    'customFields' => ['swag_example_size' => 15]
]], $context);
```

This will execute perfectly fine and you just saved a custom field with name `swag_example_size` with its value `15` to your entity. And you haven't even defined the custom field `swag_example_size` yet.

As already mentioned, you do not have to define a custom field first before saving it. That's because there is no validation happening here yet, you can write whatever valid JSON you want to that column, so the following example would also execute without any issues:

```php
$this->swagExampleRepository->upsert([[
    'id' => '<your ID here>',
    'customFields' => [ 'foo' => 'bar', 'baz' => [] ]
]], $context);
```

### Add a custom field to the Administration

You can skip this section if you don't want your new custom field to be editable in the Administration.

So now you've already filled the custom fields of one of your entity instances via code. But what if you want your user to do that, which is the more common case?

Only if you want your custom field to show up in the Administration and to be editable in there, you have to define the custom fields first in a custom field set. For this you have to use the custom fieldset repository, which can be retrieved from the dependency injection container via the `custom_field_set.repository` key and is used like any other repository.

```xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\CustomFieldClass">
          <argument type="service" id="custom_field_set.repository"/>
          ...
        </service>
    </services>
</container>
```

If you need to learn how that is done in full, head to our guide regarding [Writing data](../data-handling/writing-data).

Now use the `create` method of the repository to create a new custom field set.

```php
use Shopware\Core\System\CustomField\CustomFieldTypes;
use \Shopware\Core\Defaults;

[...]

$this->customFieldSetRepository->create([
    [
        'name' => 'swag_example_set',
        'config' => [
            'label' => [
                'en-GB' => 'English custom field set label',
                'de-DE' => 'German custom field set label',
                Defaults::LANGUAGE_SYSTEM => "Mention the fallback label here"
            ]
        ],
        'customFields' => [
            [
                'name' => 'swag_example_size',
                'type' => CustomFieldTypes::INT,
                'config' => [
                    'label' => [
                        'en-GB' => 'English custom field label',
                        'de-DE' => 'German custom field label',
                        Defaults::LANGUAGE_SYSTEM => "Mention the fallback label here"
                    ],
                    'customFieldPosition' => 1
                ]
            ]
        ]
    ]
], $context);
```

This will now create a custom field set with the name `swag_example_set` and the field, `swag_example_size`. This time we also define its type, which should be of type integer here. The type is important to mention, because the Administration will use this information to display a proper field. Also, when trying to write the custom field `swag_example_size`, the value has to be an integer.

The translated labels are added to both the field and the set, which are going to be displayed in the Administration. Also, the fallback language can be defined in case the system language is not guaranteed to be either en\_GB or de\_DE.

If you have several custom fields and want to order them within a specific order, you can do so with the `customFieldPosition` property.

::: warning
Custom field sets are deletable by the shop administrator, so you cannot rely on their existence.
:::

To update or delete a `custom_field_set`, you can use the standard repository methods like `update`, `upsert`, or `delete`.

While theoretically your custom field is now properly defined for the Administration, you'll still have to do some work in your custom entities' Administration module. Head over to this guide to learn how to add your field to the Administration:

## Next steps

If you want to extend an entity with new associations and non-scalar values, head over to our guide regarding [Extending existing entities](../data-handling/add-complex-data-to-existing-entities).

---

---
url: /docs/v6.6/guides/plugins/plugins/framework/custom-field/add-custom-field.md
---

# Add Custom Field

## Overview

Shopware's custom field system allows you to extend entities, without writing a complete entity extension. This is possible by storing the additional data in a [JSON-Field](https://dev.mysql.com/doc/refman/8.0/en/json.html). Custom fields therefore can only be used to store scalar values. If you'd like to create associations between entities, you'll need to use an [Entity extension](../data-handling/add-complex-data-to-existing-entities).

This guide will cover two similar subjects:

* Supporting custom fields with your entity
* Add custom fields to an entity

## Prerequisites

This guide is built upon both the [Plugin base guide](../../plugin-base-guide) as well as the [Add custom complex data](../data-handling/add-custom-complex-data) guide. The latter explained how to create your very first entity, which is used in the following examples.

Since migrations will also be used here, it won't hurt to have a look at our guide about [Executing database queries](../../plugin-fundamentals/database-migrations).

Also, adding translatable custom fields is covered here in short as well, for which you'll need to understand how translatable entities work in general. This is covered in our guide about [Adding data translations](../data-handling/add-data-translations). This subject will **not** be covered in depth in this guide.

## Supporting custom fields with your entity

This short section will cover how to add a custom field support for your custom entity. As previously mentioned, the example from our [Add custom complex data](../data-handling/add-custom-complex-data) guide is used and extended here.

In order to support custom fields with your custom entity, there are three necessary steps :

* Add `EntityCustomFieldsTrait` trait to your `Entity`.
* Add a `CustomFields` field to your `EntityDefinition`.
* Add a column `custom_fields` to your entities' database table via migration.

Also, you may want to add translatable custom fields, which is also covered in very short here.

### Add custom field to entity

::: info
Available starting with Shopware 6.4.1.0.
:::

Let's assume you already got a working and running entity definition. If you want to support custom fields with your custom entity, you may add the `EntityCustomFieldsTrait` to your entity class, so the methods `getCustomFields()` and `setCustomFields()` can be used.

```php
// <plugin root>/src/Core/Content/Example/ExampleEntity.php
use Shopware\Core\Framework\DataAbstractionLayer\Entity;
use Shopware\Core\Framework\DataAbstractionLayer\EntityCustomFieldsTrait;
use Shopware\Core\Framework\DataAbstractionLayer\EntityIdTrait;

[...]
class ExampleEntity extends Entity
{
    use EntityIdTrait;
    use EntityCustomFieldsTrait;

    [...]

}
```

### Add custom field to entity definition

Now follows the important part. For this to work, you have to add the Data Abstraction Layer (DAL) field `CustomFields` to your entity definition.

```php
// <plugin root>/src/Core/Content/Example/ExampleDefinition.php
use Shopware\Core\Framework\DataAbstractionLayer\Field\CustomFields;                                                                    

[...]
class ExampleDefinition extends EntityDefinition
{

    [...]

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
            (new StringField('name', 'name')),
            (new StringField('description', 'description')),
            (new BoolField('active', 'active')),

            new CustomFields()
        ]);
    }
}
```

Note the new field that was added in the `FieldCollection`. That's already it for your custom entity definition. Now go ahead and add the column to the database.

### Add column in database table

Once again, this example is built upon the [Add custom complex data](../data-handling/add-custom-complex-data) guide, which also comes with an example migration. This one will be used in this example here as well.

If you want to support custom fields now, you have to add a new column `custom_fields` of type `JSON` to your migration.

```php
// <plugin root>/src/Migration/Migration1611664789Example.php
public function update(Connection $connection): void
{
    $sql = <<<SQL
        CREATE TABLE IF NOT EXISTS `swag_example` (
        `id` BINARY(16) NOT NULL,
        `name` VARCHAR(255) COLLATE utf8mb4_unicode_ci,
        `description` VARCHAR(255) COLLATE utf8mb4_unicode_ci,
        `active` TINYINT(1) COLLATE utf8mb4_unicode_ci,

        `custom_fields` json DEFAULT NULL,

        `created_at` DATETIME(3) NOT NULL,
        `updated_at` DATETIME(3),
        PRIMARY KEY (`id`)
        )
        ENGINE = InnoDB
        DEFAULT CHARSET = utf8mb4
        COLLATE = utf8mb4_unicode_ci;
    SQL;
    $connection->executeStatement($sql);
}
```

Note the new `custom_fields` column here. It has to be a JSON field and should default to `NULL`, since it doesn't have to contain values.

### Add translatable custom field to entity definition

Make sure to understand entity translations in general first, which is explained here [Add data translations](../data-handling/add-data-translations). If you want your custom fields to be translatable, you can simply work with a `TranslatedField` here as well.

```php
// <plugin root>/src/Core/Content/Example/ExampleDefinition.php
use Shopware\Core\Framework\DataAbstractionLayer\Field\TranslatedField;                                                               

[...]

class ExampleDefinition extends EntityDefinition
{
    [...]

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
            (new StringField('name', 'name')),
            (new StringField('description', 'description')),
            (new BoolField('active', 'active')),

            new TranslatedField('customFields'),
        ]);
    }
}
```

Just add the `TranslatedField` and apply `customFields` as a parameter.

In your translated entity definition, you then add the `CustomFields` field instead.

```php
// <plugin root>/src/Core/Content/Example/Aggregate/ExampleTranslation/ExampleTranslationDefinition.php
use Shopware\Core\Framework\DataAbstractionLayer\Field\CustomFields;                                                                    

[...]
class ExampleTranslationDefinition extends EntityTranslationDefinition
{
    [...]

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new StringField('name', 'name'))->addFlags(new Required()),

            new CustomFields()
        ]);
    }
}
```

## Add custom fields to an entity

The previous section was about adding support for custom fields in your entity, but this section will cover how to add an actual custom field to an entity and how to fill it with data.

Technically, there is no need to define a custom field set and its fields first, before actually inserting values into the `custom_fields` column of your entities' database table via the DAL. Defining a custom field set is only necessary, if you want it to be editable in the Administration or if you need validation when writing your custom field.

Because of that, we'll start with filling data to an actual entities' custom field, before actually defining it.

### Filling data into custom fields

So let's assume you've got your own `example` entity up and running and now you want to add data to its custom fields via the DAL.

For that case, you can simply use your entities' repository and start creating or updating entities with custom fields. If you don't understand what's going on here, head over to our guide about [Writing data](../data-handling/writing-data) first.

```php
$this->swagExampleRepository->upsert([[
    'id' => '<your ID here>',
    'customFields' => ['swag_example_size' => 15]
]], $context);
```

This will execute perfectly fine and you just saved a custom field with name `swag_example_size` with its value `15` to your entity. And you haven't even defined the custom field `swag_example_size` yet.

As already mentioned, you do not have to define a custom field first before saving it. That's because there is no validation happening here yet, you can write whatever valid JSON you want to that column, so the following example would also execute without any issues:

```php
$this->swagExampleRepository->upsert([[
    'id' => '<your ID here>',
    'customFields' => [ 'foo' => 'bar', 'baz' => [] ]
]], $context);
```

### Add a custom field to the Administration

You can skip this section if you don't want your new custom field to be editable in the Administration.

So now you've already filled the custom fields of one of your entity instances via code. But what if you want your user to do that, which is the more common case?

Only if you want your custom field to show up in the Administration and to be editable in there, you have to define the custom fields first in a custom field set. For this you have to use the custom fieldset repository, which can be retrieved from the dependency injection container via the `custom_field_set.repository` key and is used like any other repository.

```xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\CustomFieldClass">
          <argument type="service" id="custom_field_set.repository"/>
          ...
        </service>
    </services>
</container>
```

If you need to learn how that is done in full, head to our guide regarding [Writing data](../data-handling/writing-data).

Now use the `create` method of the repository to create a new custom field set.

```php
use Shopware\Core\System\CustomField\CustomFieldTypes;
use \Shopware\Core\Defaults;

[...]

$this->customFieldSetRepository->create([
    [
        'name' => 'swag_example_set',
        'config' => [
            'label' => [
                'en-GB' => 'English custom field set label',
                'de-DE' => 'German custom field set label',
                Defaults::LANGUAGE_SYSTEM => "Mention the fallback label here"
            ]
        ],
        'customFields' => [
            [
                'name' => 'swag_example_size',
                'type' => CustomFieldTypes::INT,
                'config' => [
                    'label' => [
                        'en-GB' => 'English custom field label',
                        'de-DE' => 'German custom field label',
                        Defaults::LANGUAGE_SYSTEM => "Mention the fallback label here"
                    ],
                    'customFieldPosition' => 1
                ]
            ]
        ]
    ]
], $context);
```

This will now create a custom field set with the name `swag_example_set` and the field, `swag_example_size`. This time we also define its type, which should be of type integer here. The type is important to mention, because the Administration will use this information to display a proper field. Also, when trying to write the custom field `swag_example_size`, the value has to be an integer.

The translated labels are added to both the field and the set, which are going to be displayed in the Administration. Also, the fallback language can be defined in case the system language is not guaranteed to be either en\_GB or de\_DE.

If you have several custom fields and want to order them within a specific order, you can do so with the `customFieldPosition` property.

::: warning
Custom field sets are deletable by the shop administrator, so you cannot rely on their existence.
:::

To update or delete a `custom_field_set`, you can use the standard repository methods like `update`, `upsert`, or `delete`.

While theoretically your custom field is now properly defined for the Administration, you'll still have to do some work in your custom entities' Administration module. Head over to this guide to learn how to add your field to the Administration:

## Next steps

If you want to extend an entity with new associations and non-scalar values, head over to our guide regarding [Extending existing entities](../data-handling/add-complex-data-to-existing-entities).

---

---
url: >-
  /docs/guides/plugins/plugins/storefront/howto/using-custom-fields-storefront.md
---

# Add Custom Field in the Storefront

## Overview

This guide will show you how to use custom fields, e.g., labels in the Storefront.

## Prerequisites

Read the [Plugin base guide](../../plugin-base-guide.md) for guidance on creating plugins. A running plugin is necessary.

You will also need a custom field to add to the Storefront using your plugin. The guide on [adding custom fields to Shopware](../../framework/custom-field/add-custom-field.md) provides details.

## Use snippets of custom fields

First, if you add a custom field via API or Administration, automatically snippets for all languages are created. The naming of the snippet is like the following template: `customFields.` as prefix and then the name of the custom field. For example, if the name of the created custom field is `my_test_field`, then the created snippet name will be `customFields.my_test_field`.

::: info
In the snippet settings in the Administration you're able to edit and translate the snippet.
:::

## Storefront usage of custom fields

Adding custom fields in the Storefront is quite simple. You basically use Twig this way:

```twig
{{ "customFields.my_test_field"|trans|sw_sanitize }}: {{ page.product.translated.customFields.my_test_field }}
```

::: info
Did you notice the Twig function `sw_sanitize`? It's a Twig function we wrote, customized for Shopware's needs. It filters tags and attributes from a given string optimized for Shopware usage.
:::

Imagine you want to add a text field to the product description. If you want to use the snippet in the Storefront, you have to extend a template file first. Let's say we want to add our custom field to the product description's text. The block of this element is `page_product_detail_description_content_text`, so we'll use it in our example. As we want to add our custom field in there, we use `parent` Twig function to keep the original template:

```twig
// <plugin root>/src/Resources/views/storefront/page/product-detail/description.html.twig
{% sw_extends '@Storefront/storefront/page/product-detail/description.html.twig' %}

{% block page_product_detail_description_content_text %}
    {{ parent() }}
{% endblock %}
```

Now, we finally add our custom field as explained before:

```twig
// <plugin root>/src/Resources/views/storefront/page/product-detail/description.html.twig
{% sw_extends '@Storefront/storefront/page/product-detail/description.html.twig' %}

{% block page_product_detail_description_content_text %}
    {{ parent() }}

    {# Insert your custom field here, as seen below: #}
    {{ "customFields.my_test_field"|trans|sw_sanitize }}: {{ page.product.translated.customFields.my_test_field }}
{% endblock %}
```

## Custom fields in forms

Let's say you have a custom field for the customer entity through the administration; now, you want the customer to input data into it through a field in the customer register form. This can be done without the need for a subscriber or listener; simply add a field to the form using the correct custom field name.

::: info
For custom fields to work in forms, you must enable the **Modifiable via Store API** option in the custom field configuration. This setting allows the Store API to modify the field, which is required for storing custom data from storefront forms such as registration forms.
:::

```twig
// <plugin root>/src/Resources/views/storefront/component/address/address-personal.html.twig
{% sw_extends '@Storefront/storefront/component/address/address-personal.html.twig' %}

{% block component_address_personal_fields %}
    {{ parent() }}

	{# custom field #}
	<div class="form-group col-sm-6">
		<label class="form-label" for="customFields[custom_field_name]">
			{{ "customFields.custom_field_name"|trans|sw_sanitize}}*
		</label>
		<input type="text" class="form-control" name="customFields[custom_field_name]" value="{{context.customer.customFields['custom_field_name'] }}" id="customFields[custom_field_name]" required="required">
	</div>
{% endblock %}
```

---

---
url: /docs/v6.5/guides/plugins/plugins/storefront/using-custom-fields-storefront.md
---

# Add Custom Field in the Storefront

## Overview

This guide will show you how to use custom fields, e.g., labels in the Storefront.

## Prerequisites

You won't learn to create a plugin in this guide, head over to our [Plugin base guide](../plugin-base-guide) to create a plugin first, if you don't know how it's done yet.

Needless to say, you need a custom field itself to add to the Storefront via your own plugin. Head over to the guide on [adding custom fields to Shopware](../framework/custom-field/add-custom-field) to be able to prepare your own custom field.

## Use snippets of custom fields

First, if you add a custom field via API or Administration, automatically snippets for all languages are created. The naming of the snippet is like the following template: `customFields.` as prefix and then the name of the custom field. For example, if the name of the created custom field is `my_test_field`, then the created snippet name will be `customFields.my_test_field`.

::: info
In the snippet settings in the Administration you're able to edit and translate the snippet.
:::

## Storefront usage of custom fields

Adding custom fields in the Storefront is quite simple. You basically use Twig this way:

```twig
{{ "customFields.my_test_field"|trans|sw_sanitize }}: {{ page.product.translated.customFields.my_test_field }}
```

::: info
Did you notice the Twig function `sw_sanitize`? It's a Twig function we wrote, customized for Shopware's needs. It filters tags and attributes from a given string optimized for Shopware usage.
:::

Imagine you want to add a text field to the product description. If you want to use the snippet in the Storefront, you have to extend a template file first. Let's say we want to add our custom field to the product description's text. The block of this element is `page_product_detail_description_content_text`, so we'll use it in our example. As we want to add our custom field in there, we use `parent` Twig function to keep the original template:

```twig
// <plugin root>/src/Resources/views/storefront/page/product-detail/description.html.twig
{% sw_extends '@Storefront/storefront/page/product-detail/description.html.twig' %}

{% block page_product_detail_description_content_text %}
    {{ parent() }}
{% endblock %}
```

Now, we finally add our custom field as explained before:

```twig
// <plugin root>/src/Resources/views/storefront/page/product-detail/description.html.twig
{% sw_extends '@Storefront/storefront/page/product-detail/description.html.twig' %}

{% block page_product_detail_description_content_text %}
    {{ parent() }}

    {# Insert your custom field here, as seen below: #}
    {{ "customFields.my_test_field"|trans|sw_sanitize }}: {{ page.product.translated.customFields.my_test_field }}
{% endblock %}
```

## Custom fields in forms

Let's say you have a custom field for the customer entity through the administration; now, you want the customer to input data into it through a field in the customer register form. This can be done without the need for a subscriber or listener; simply add a field to the form using the correct custom field name.

```twig
// <plugin root>/src/Resources/views/storefront/component/address/address-personal.html.twig
{% sw_extends '@Storefront/storefront/component/address/address-personal.html.twig' %}

{% block component_address_personal_fields %}
    {{ parent() }}

	{# custom field #}
	<div class="form-group col-sm-6">
		<label class="form-label" for="customFields[custom_field_name]">
			{{ "customFields.custom_field_name"|trans|sanitize}}*
		</label>
		<input type="text" class="form-control" name="customFields[custom_field_name]" value="{{context.customer.customFields['custom_field_name'] }}" id="customFields[custom_field_name]" required="required">
	</div>
{% endblock %}
```

---

---
url: /docs/v6.6/guides/plugins/plugins/storefront/using-custom-fields-storefront.md
---

# Add Custom Field in the Storefront

## Overview

This guide will show you how to use custom fields, e.g., labels in the Storefront.

## Prerequisites

You won't learn to create a plugin in this guide, head over to our [Plugin base guide](../plugin-base-guide) to create a plugin first, if you don't know how it's done yet.

Needless to say, you need a custom field itself to add to the Storefront via your own plugin. Head over to the guide on [adding custom fields to Shopware](../framework/custom-field/add-custom-field) to be able to prepare your own custom field.

## Use snippets of custom fields

First, if you add a custom field via API or Administration, automatically snippets for all languages are created. The naming of the snippet is like the following template: `customFields.` as prefix and then the name of the custom field. For example, if the name of the created custom field is `my_test_field`, then the created snippet name will be `customFields.my_test_field`.

::: info
In the snippet settings in the Administration you're able to edit and translate the snippet.
:::

## Storefront usage of custom fields

Adding custom fields in the Storefront is quite simple. You basically use Twig this way:

```twig
{{ "customFields.my_test_field"|trans|sw_sanitize }}: {{ page.product.translated.customFields.my_test_field }}
```

::: info
Did you notice the Twig function `sw_sanitize`? It's a Twig function we wrote, customized for Shopware's needs. It filters tags and attributes from a given string optimized for Shopware usage.
:::

Imagine you want to add a text field to the product description. If you want to use the snippet in the Storefront, you have to extend a template file first. Let's say we want to add our custom field to the product description's text. The block of this element is `page_product_detail_description_content_text`, so we'll use it in our example. As we want to add our custom field in there, we use `parent` Twig function to keep the original template:

```twig
// <plugin root>/src/Resources/views/storefront/page/product-detail/description.html.twig
{% sw_extends '@Storefront/storefront/page/product-detail/description.html.twig' %}

{% block page_product_detail_description_content_text %}
    {{ parent() }}
{% endblock %}
```

Now, we finally add our custom field as explained before:

```twig
// <plugin root>/src/Resources/views/storefront/page/product-detail/description.html.twig
{% sw_extends '@Storefront/storefront/page/product-detail/description.html.twig' %}

{% block page_product_detail_description_content_text %}
    {{ parent() }}

    {# Insert your custom field here, as seen below: #}
    {{ "customFields.my_test_field"|trans|sw_sanitize }}: {{ page.product.translated.customFields.my_test_field }}
{% endblock %}
```

## Custom fields in forms

Let's say you have a custom field for the customer entity through the administration; now, you want the customer to input data into it through a field in the customer register form. This can be done without the need for a subscriber or listener; simply add a field to the form using the correct custom field name.

```twig
// <plugin root>/src/Resources/views/storefront/component/address/address-personal.html.twig
{% sw_extends '@Storefront/storefront/component/address/address-personal.html.twig' %}

{% block component_address_personal_fields %}
    {{ parent() }}

	{# custom field #}
	<div class="form-group col-sm-6">
		<label class="form-label" for="customFields[custom_field_name]">
			{{ "customFields.custom_field_name"|trans|sw_sanitize}}*
		</label>
		<input type="text" class="form-control" name="customFields[custom_field_name]" value="{{context.customer.customFields['custom_field_name'] }}" id="customFields[custom_field_name]" required="required">
	</div>
{% endblock %}
```

---

---
url: /docs/v6.5/guides/plugins/plugins/framework/flow/add-flow-builder-action.md
---

# Add custom flow Action

## Overview

In this guide, you'll learn how to create custom flow action in Shopware. The flow builder uses actions to perform business tasks. This example will introduce a new custom action called `create tags`.

## Prerequisites

In order to add your own custom flow action for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide.](../../plugin-base-guide)

You also should be familiar with the [Dependency Injection container](../../plugin-fundamentals/dependency-injection) as this is used to register your custom flow action and [Listening to events](../../plugin-fundamentals/listening-to-events#creating-your-own-subscriber) to create a subscriber class.

It might be helpful to gather some general understanding about the [concept of Flow Builder](../../../../../concepts/framework/flow-concept) as well.

## Existing triggers and actions

You can refer to the [Flow reference](../../../../../resources/references/core-reference/flow-reference) to read triggers and actions detail.

## Create custom flow action

To create a custom flow action, firstly you have to make a plugin and install it. Refer to the [Plugin Base Guide](../../plugin-base-guide.md) to do it. For instance, lets create a plugin named `CreateTagAction`. You must implement both backend (PHP) code and a user interface in the Administration to manage it. Let's start with the PHP part first, which handles the main logic of our action. After that, there will be an example to show your new actions in the Administration.

## Creating flow action in PHP

### Create new Aware interface

First of all, we need to define an aware interface for your own action. I intended to create the `CreateTagAction`, so I need to create a related aware named `TagAware`, will be placed in directory `<plugin root>/src/Core/Framework/Event`. Our new interface has to extend from interfaces `Shopware\Core\Framework\Event\FLowEventAware`:

```php
// <plugin root>/src/Core/Framework/Event/TagAware.php
<?php declare(strict_types=1);
namespace Swag\ExamplePlugin\Core\Framework\Event;
use Shopware\Core\Framework\Event\FlowEventAware;

interface TagAware extends FlowEventAware
{
    ...

    public const TAG = 'tag';

    public const TAG_ID = 'tagId';

    public function getTag();

    ...
}
```

### Create new action

In this example, we will name it `CreateTagAction`. It will be placed in the directory `<plugin root>/src/Core/Content/Flow/Dispatching/Action`. Below you can find an example implementation:

```php
// <plugin root>/src/Core/Content/Flow/Dispatching/Action/CreateTagAction.php
<?php declare(strict_types=1);

namespace Swag\CreateTagAction\Core\Content\Flow\Dispatching\Action;

use Shopware\Core\Content\Flow\Dispatching\Action\FlowAction;
use Shopware\Core\Content\Flow\Dispatching\StorableFlow;
use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\Uuid\Uuid;
use Swag\CreateTagAction\Core\Framework\Event\TagAware;

class CreateTagAction extends FlowAction
{
    private EntityRepository $tagRepository;

    public function __construct(EntityRepository $tagRepository)
    {
        // you would need this repository to create a tag
        $this->tagRepository = $tagRepository;
    }

    public static function getName(): string
    {
        // your own action name
        return 'action.create.tag';
    }

    public function requirements(): array
    {
        return [TagAware::class];
    }

    public function handleFlow(StorableFlow $flow): void
    {
        // config is the config data when created a flow sequence
        $config = $flow->getConfig();

        // make sure your tags data exists
        if (!\array_key_exists('tags', $config)) {
            return;
        }

        $tags = $config['tags'];

        // just a step to make sure you're dispatching correct action
        if (!$flow->hasStore(TagAware::TAG_ID) || empty($tags)) {
            return;
        }

        // get tag id
        $tagId = $flow->getStore(TagAware::TAG_ID);

        // get tag
        $tag = $flow->getData(TagAware::TAG);

        $tagData = [];
        foreach ($tags as $tag) {
            $tagData[] = [
                'id' => Uuid::randomHex(),
                'name' => $tag,
            ];
        }

        // simply create tags
        $this->tagRepository->create($tagData, $flow->getContext());
    }
}
```

As you can see, several methods are already implemented:

* `__constructor`: This only defines the default expected value. This is overwritten at runtime with the actual value, that the shop owner set in the Administration.
* `getName`: Returns a unique technical name for your action.
* `requirements`: This defines which interfaces the action belongs to.
* `handleFlow`: Use this method to handle your action stuff.
  * Use `$flow->getStore($key)` if you want to get the data from aware interfaces. E.g: `tag_id` in `TagAware`, `customer_id` from `CustomerAware` and so on.
  * Use `$flow->getData($key)` if you want to get the data from original events or additional data. E.g: `tag`, `customer`, `contactFormData` and so on.

You also need to register this action in the container as a service. Make sure to define a tag `<tag name="flow.action" priority="600">` at `<plugin root>/src/Resources/config/services.xml`. This tag will ensure that your action is included in the response of the *`/api/_info/flow-actions.json`* API. The priority attribute will determine the order of the action in the API response.

```XML
// <plugin root>/src/Resources/config/services.xml
<service id="Swag\CreateTagAction\Core\Content\Flow\Dispatching\Action\CreateTagAction">
    <argument type="service" id="tag.repository" />
    <tag name="flow.action" priority="600" key="action.create.tag"/>
</service>
```

Great, your own action is created completely. Let's go to the next step.

### Define action scope

In this step, you will know how to define your action scope for `CreateTagAction`.
There are three scopes for the `CreateTagAction`:

* Available for all *already Events*.
* Available for only one or multiple *already Events.*
* Available for new event (new event from this plugin).

#### `CreateTagAction` available for all *already Events*

* Just define the empty array in `CreateTagAction::requirements`

```PHP
    // plugin root>/src/Core/Content/Flow/Dispatching/Action/CreateTagAction.php
    ...

    public function requirements(): array
    {
        return [];
    }

    ...
```

That means when you define the requirements like the code above, all triggers in the flow builder can define the action `CreateTagAction` for the next progress.

![Flow Builder trigger](../../../../../assets/flow-builder-action-available-all-events.png)

Here, the action name is empty as the action name snippet is not yet defined.

#### `CreateTagAction` available for only one or multiple *already Events*

Make the `CreateTagAction` available for all events related to Order and Customer.

```PHP
    // <plugin root>/src/Core/Content/Flow/Dispatching/Action/CreateTagAction.php
    ...

    public function requirements(): array
    {
        return [OrderAware::class, CustomerAware::class];
    }

    ...
```

#### `CreateTagAction` available for new event

* For this case, you can define a new event and make the `CreateTagAction` available for this event.

* Event must implement the `TagAware`

```PHP
// <plugin root>/src/Core/Content/Flow/Subscriber/BusinessEventCollectorSubscriber.php
<?php declare(strict_types=1);

namespace Swag\CreateTagAction\Core\Content\Event;

use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\Event\EventData\EntityType;
use Shopware\Core\Framework\Event\EventData\EventDataCollection;
use Shopware\Core\System\Tag\TagDefinition;
use Shopware\Core\System\Tag\TagEntity;
use Swag\CreateTagAction\Core\Framework\Event\TagAware;
use Symfony\Contracts\EventDispatcher\Event;

class BasicExampleEvent extends Event implements TagAware
{
    public const EVENT_NAME = 'example.event';

    private TagEntity $tag;

    private Context $context;

    public function __construct(Context $context, TagEntity $tag)
    {
        $this->tag = $tag;
        $this->context = $context;
    }

    public function getName(): string
    {
        return self::EVENT_NAME;
    }

    public static function getAvailableData(): EventDataCollection
    {
        return (new EventDataCollection())
            ->add('tag', new EntityType(TagDefinition::class));
    }

    public function getContext(): Context
    {
        return $this->context;
    }

    public function getTag(): TagEntity
    {
        return $this->tag;
    }
}
```

* Define the `TagAware` in `CreateTagAction::requirements`

```PHP
    // <plugin root>/src/Core/Content/Flow/Dispatching/Action/CreateTagAction.php
    ...

    public function requirements(): array
    {
        return [TagAware::class];
    }

    ...
```

* To show the new event in Flow Builder Triggers list

```php
// <plugin root>/src/Core/Content/Subscriber/BusinessEventCollectorSubscriber.php
<?php declare(strict_types=1);
namespace Swag\CreateTagAction\Core\Content\Subscriber;

use Shopware\Core\Framework\Event\BusinessEventCollector;
use Shopware\Core\Framework\Event\BusinessEventCollectorEvent;
use Swag\CreateTagAction\Core\Content\Event\BasicExampleEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class BusinessEventCollectorSubscriber implements EventSubscriberInterface
{
    private BusinessEventCollector $businessEventCollector;

    public function __construct(BusinessEventCollector $businessEventCollector)
    {
        $this->businessEventCollector = $businessEventCollector;
    }

    public static function getSubscribedEvents()
    {
        return [
            BusinessEventCollectorEvent::NAME => 'onAddExampleEvent',
        ];
    }

    public function onAddExampleEvent(BusinessEventCollectorEvent $event): void
    {
        $collection = $event->getCollection();

        $definition = $this->businessEventCollector->define(BasicExampleEvent::class);

        if (!$definition) {
            return;
        }

        $collection->set($definition->getName(), $definition);
    }
}
```

And don't forget to register your subscriber to the container at `<plugin root>/src/Resources/config/services.xml`.

```xml
<service id="Swag\CreateTagAction\Core\Content\Subscriber\BusinessEventCollectorSubscriber">
    <argument type="service" id="Shopware\Core\Framework\Event\BusinessEventCollector"/>
    <tag name="kernel.event_subscriber"/>
</service>
```

* Define the Event snippet

```json
// <plugin root>/src/Resources/app/administration/src/module/sw-flow/snippet/en-GB.json
{
  "sw-flow": {
    "triggers": {
      "example": "Example",
      "event": "Event"
    }
  }
}
```

![Flow Builder trigger](../../../../../assets/flow-builder-triggers-list.png)

Well, you have successfully created your custom action in Backend in PHP.

## Add custom action in Administration

After we are done with the PHP code, `action.create.tag` is received from the response of `/api/_info/flow-actions.json`. However, the custom action displays in the action list without label. These further steps in Administration will help you show the action label and add configuration for it.

To see the action list, we select a Trigger, for example \[example\event], from the Trigger drop-down in the Flow tab. After that, we choose option `ACTION (THEN)`. An action component appears with an action list.

![Flow Builder trigger](../../../../../assets/flow-builder-trigger-drop.png)

![Flow Builder action then](../../../../../assets/flow-builder-action-then.png)

![Flow Builder trigger](../../../../../assets/flow-builder-action-no-label.png)

### Step 1: Show action label in action list

First, we need to define information like `constants`, `snippets` to show on the action list. To be consistent with the custom action defined in our PHP code, create an action name called `CREATE_TAG` to represent `action.create.tag`, which gets from the response of `/api/_info/flow-actions.json`.

![Flow Builder action services list](../../../../../assets/flow-builder-action-sevices-list.png)

```JS
// <plugin root>src/Resources/app/administration/src/constant/create-tag-action.constant.js
export const ACTION = Object.freeze({
    CREATE_TAG: 'action.create.tag',
});

export const GROUP = 'customer'

export default {
    ACTION, GROUP
};
```

And then add snippets for labels:

```JS
// src/Resources/app/administration/src/snippet/en-GB.json
{
    "create-tag-action": {
        "titleCreateTag": "Create tag",
        "labelTags": "Tags",
        "placeholderTags": "Enter tags",
        "buttonSaveAction": "Save action",
        "buttonAddAction": "Add action",
        "descriptionTags": "Tags: {tags}"
    }
}
```

Do it as the same with `de-DE.json` file for translation of DE language.

After that, we also need to override the `sw-flow-sequence-action` component in the core:

```JS
// <plugin root>/src/Resources/app/administration/src/extension/sw-flow-sequence-action/index.js
import { ACTION, GROUP } from '../../constant/create-tag-action.constant';

const { Component } = Shopware;

Component.override('sw-flow-sequence-action', {
    computed: {
        // Not necessary if you use an existing group
        // Push the `groups` method in computed if you are defining a new group
        groups() {
            this.actionGroups.unshift(GROUP);

            return this.$super('groups');
        },

        modalName() {
            if (this.selectedAction === ACTION.CREATE_TAG) {
                return 'sw-flow-create-tag-modal';
            }

            return this.$super('modalName');
        },

        actionDescription() {
            const actionDescriptionList = this.$super('actionDescription');

            return {
                ...actionDescriptionList,
                [ACTION.CREATE_TAG] : (config) => this.getCreateTagDescription(config),
            };
        },
    },

    methods: {
        getCreateTagDescription(config) {
            const tags = config.tags.join(', ');

            return this.$tc('create-tag-action.descriptionTags', 0, {
                tags
            });
        },

        getActionTitle(actionName) {
            if (actionName === ACTION.CREATE_TAG) {
                return {
                    value: actionName,
                    icon: 'regular-tag',
                    label: this.$tc('create-tag-action.titleCreateTag'),
                    group: GROUP,
                }
            }

            return this.$super('getActionTitle', actionName);
        },
    },
});

```

Do not forget to import the file to the entry file `main.js`:

```JS
// <plugin root>/src/Resources/app/administration/src/main.js
import './extension/sw-flow-sequence-action';
```

**Grouping Actions**

As you can see, we already defined the constant for the group in `create-tag-action.constant.js`

```JS
export const GROUP = 'customer'
```

The new action `action.create.tag` will be shown on the Customer group.

![Choose a Flow Builder Action](../../../../../assets/flow-builder-action-customer-group.png)

It will default on the General group if it is not defined.

Here is a list of group names you should take a look at:

| Group Name | Group Headline |
| :--- | :--- |
| general | General|
| tag | Tag |
| customer | Customer |
| order | Order |

### Step 2: Add configuration for action

If you click the Create tag action, the below error will be shown on the console. That means we're going the right way.

![Choose a Flow Builder Action](../../../../../assets/flow-builder-action-error.png)

Because in `sw-flow-sequence-action`, we expect that the new modal has the name `sw-flow-create-tag-modal`.

```JS
modalName() {
    if (this.selectedAction === ACTION.CREATE_TAG) {
        return 'sw-flow-create-tag-modal';
    }

    return this.$super('modalName');
},
```

To define the modal, just create a new folder `sw-flow-create-tag-modal` in `src/Resources/app/administration/src/component` and create some files following:

#### JavaScript file

```JS
// <plugin root>/src/Resources/app/administration/src/component/sw-flow-create-tag-modal/index.js
import template from './sw-flow-create-tag-modal.html.twig';

const { Data: { Criteria, EntityCollection } } = Shopware;
const { Component, Context } = Shopware;

Component.register('sw-flow-create-tag-modal', {
    template,

    inject: [
        'repositoryFactory',
    ],

    props: {
        sequence: {
            type: Object,
            required: true,
        },
    },

    data() {
        return {
            tagCollection: [],
        };
    },

    computed: {
        tagRepository() {
            return this.repositoryFactory.create('tag');
        },

        tagCriteria() {
            const criteria = new Criteria(1, 25);
            const { config } = this.sequence;
            const tagIds = Object.keys(config.tagIds);
            if (tagIds.length) {
                criteria.addFilter(Criteria.equalsAny('id', tagIds));
            }

            return criteria;
        },
    },

    created() {
        this.createdComponent();
    },

    methods: {
        createdComponent() {
            this.tagCollection = this.createTagCollection();

            const { config } = this.sequence;
            if (this.sequence.id && config?.tagIds) {
                this.getTagCollection();
            }
        },

        getTagCollection() {
            return this.tagRepository.search(this.tagCriteria)
                .then(tags => {
                    this.tagCollection = tags;
                })
                .catch(() => {
                    this.tagCollection = [];
                });
        },

        createTagCollection() {
            return new EntityCollection(
                this.tagRepository.route,
                this.tagRepository.entityName,
                Context.api,
            );
        },

        onClose() {
            this.$emit('modal-close');
        },

        onAddTag(data) {
            this.tagCollection.add(data);
        },

        onRemoveTag(data) {
            this.tagCollection.remove(data);
        },

        getConfig() {
            const tagIds = {};
            this.tagCollection.forEach(tag => {
                Object.assign(tagIds, {
                    [tag.id]: tag.name,
                });
            });

            return {
                tagIds,
            };
        },

        onAddAction() {
            const config = this.getConfig();
            const data = {
                ...this.sequence,
                config,
            };

            this.$emit('process-finish', data);
        },
    },
});
```

#### Twig template file

```twig
// <plugin root>/src/Resources/app/administration/src/component/sw-flow-create-tag-modal/sw-flow-create-tag-modal.html.twig
{% block create_tag_action_modal %}
<sw-modal
    class="create-tag-action-modal"
    :title="$tc('create-tag-action.titleCreateTag')"
    @modal-close="onClose"
>
    {% block create_tag_action_modal_content %}
        <sw-entity-tag-select
            v-model="tagCollection"
            class="sw-flow-create-tag-modal__tags-field"
            required
            :label="$tc('create-tag-action.labelTags')"
            :placeholder="$tc('create-tag-action.placeholderTags')"
            @item-add="onAddTag"
            @item-remove="onRemoveTag"
        />
    {% endblock %}

    {% block create_tag_action_modall_footer %}
        <template #modal-footer>
            {% block create_tag_action_modal_footer_cancel_button %}
                <sw-button
                    class="create-tag-action-modal__cancel-button"
                    size="small"
                    @click="onClose"
                >
                    {{ $tc('global.default.cancel') }}
                </sw-button>
            {% endblock %}

            {% block create_tag_action_modal_footer_save_button %}
                <sw-button
                    class="create-tag-action-modal__save-button"
                    variant="primary"
                    size="small"
                    @click="onAddAction"
                >
                    {{ $tc('create-tag-action.buttonSaveAction') }}
                </sw-button>
            {% endblock %}
        </template>
    {% endblock %}
</sw-modal>
{% endblock %}
```

Please update the file `main.js` like this:

```JS
// <plugin root>/src/Resources/app/administration/src/main.js
import './extension/sw-flow-sequence-action';
import './component/sw-flow-create-tag-modal';
```

Here is the final result

![Flow Builder create tag](../../../../../assets/flow-builder-tag.png)

Click on \[Save action] and we will get the result as below screenshot.

![Flow Builder create tag result](../../../../../assets/flow-builder-tag-result.png)

#### Custom configuration for action without the modal

You don't need a modal for the configuration. It can be added automatically.

Imagine, your action is already in the action list after [the first step](#step-1-show-action-label-in-action-list)

![Choose a Flow Builder Action](../../../../../assets/flow-builder-trigger-action.png)

First, override the `openDynamicModal` method in the plugin to check if the value matches the desired action. Then, call the `onSaveActionSuccess` directly with the configuration. After the check, call `return`.

#### JavaScript

```JS
// <plugin root>/src/Resources/app/administration/src/extension/sw-flow-sequence-action/index.js
import template from './sw-flow-sequence-action.html.twig';
const { Component } = Shopware;

Component.register('sw-flow-sequence-action', {
    methods: {
        openDynamicModal(value) {
            if (!value) {
                return;
            }

            const actionName = this.flowBuilderService.getActionName('CREATE_TAG');

            if (value === actionName) {
                this.selectedAction = actionName;
                const config = {
                    tagIds: {
                        'tag_id_1': 'Vip',
                        'tag_id_2': 'New Customer',
                    },
                };

                // Config can be a result from an API.
                this.onSaveActionSuccess({ config });
                return;
            }

            // handle for the rest of actions.
        },
    },
});
```

Now, after you click on the action, the new sequence will automatically be added to the action list like this:

![Flow Builder create tag result](../../../../../assets/flow-builder-tag-result.png)

### Demo

You can view the whole demo for this custom Flow Builder trigger and action below:

![Flow Builder demo](../../../../../assets/flow-builder-demo.gif)

---

---
url: /docs/v6.6/guides/plugins/plugins/framework/flow/add-flow-builder-action.md
---

# Add custom flow Action

## Overview

In this guide, you'll learn how to create custom flow action in Shopware. The flow builder uses actions to perform business tasks. This example will introduce a new custom action called `create tags`.

## Prerequisites

In order to add your own custom flow action for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide.](../../plugin-base-guide)

You also should be familiar with the [Dependency Injection container](../../plugin-fundamentals/dependency-injection) as this is used to register your custom flow action and [Listening to events](../../plugin-fundamentals/listening-to-events#creating-your-own-subscriber) to create a subscriber class.

It might be helpful to gather some general understanding about the [concept of Flow Builder](../../../../../concepts/framework/flow-concept) as well.

## Existing triggers and actions

You can refer to the [Flow reference](../../../../../resources/references/core-reference/flow-reference) to read triggers and actions detail.

## Create custom flow action

To create a custom flow action, firstly you have to make a plugin and install it. Refer to the [Plugin Base Guide](../../plugin-base-guide.md) to do it. For instance, lets create a plugin named `CreateTagAction`. You must implement both backend (PHP) code and a user interface in the Administration to manage it. Let's start with the PHP part first, which handles the main logic of our action. After that, there will be an example to show your new actions in the Administration.

## Creating flow action in PHP

### Create new Aware interface

First of all, we need to define an aware interface for your own action. I intended to create the `CreateTagAction`, so I need to create a related aware named `TagAware`, will be placed in directory `<plugin root>/src/Core/Framework/Event`. Our new interface has to extend from interfaces `Shopware\Core\Framework\Event\FLowEventAware`:

```php
// <plugin root>/src/Core/Framework/Event/TagAware.php
<?php declare(strict_types=1);
namespace Swag\ExamplePlugin\Core\Framework\Event;
use Shopware\Core\Framework\Event\FlowEventAware;
use Shopware\Core\Framework\Event\IsFlowEventAware;

#[IsFlowEventAware]
interface TagAware extends FlowEventAware
{
    ...

    public const TAG = 'tag';

    public const TAG_ID = 'tagId';

    public function getTag();

    ...
}
```

### Create new action

In this example, we will name it `CreateTagAction`. It will be placed in the directory `<plugin root>/src/Core/Content/Flow/Dispatching/Action`. Below you can find an example implementation:

```php
// <plugin root>/src/Core/Content/Flow/Dispatching/Action/CreateTagAction.php
<?php declare(strict_types=1);

namespace Swag\CreateTagAction\Core\Content\Flow\Dispatching\Action;

use Shopware\Core\Content\Flow\Dispatching\Action\FlowAction;
use Shopware\Core\Content\Flow\Dispatching\StorableFlow;
use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\Uuid\Uuid;
use Swag\CreateTagAction\Core\Framework\Event\TagAware;

class CreateTagAction extends FlowAction
{
    private EntityRepository $tagRepository;

    public function __construct(EntityRepository $tagRepository)
    {
        // you would need this repository to create a tag
        $this->tagRepository = $tagRepository;
    }

    public static function getName(): string
    {
        // your own action name
        return 'action.create.tag';
    }

    public function requirements(): array
    {
        return [TagAware::class];
    }

    public function handleFlow(StorableFlow $flow): void
    {
        // config is the config data when created a flow sequence
        $config = $flow->getConfig();

        // make sure your tags data exists
        if (!\array_key_exists('tags', $config)) {
            return;
        }

        $tags = $config['tags'];

        // just a step to make sure you're dispatching correct action
        if (!$flow->hasStore(TagAware::TAG_ID) || empty($tags)) {
            return;
        }

        // get tag id
        $tagId = $flow->getStore(TagAware::TAG_ID);

        // get tag
        $tag = $flow->getData(TagAware::TAG);

        $tagData = [];
        foreach ($tags as $tag) {
            $tagData[] = [
                'id' => Uuid::randomHex(),
                'name' => $tag,
            ];
        }

        // simply create tags
        $this->tagRepository->create($tagData, $flow->getContext());
    }
}
```

As you can see, several methods are already implemented:

* `__constructor`: This only defines the default expected value. This is overwritten at runtime with the actual value, that the shop owner set in the Administration.
* `getName`: Returns a unique technical name for your action.
* `requirements`: This defines which interfaces the action belongs to.
* `handleFlow`: Use this method to handle your action stuff.
  * Use `$flow->getStore($key)` if you want to get the data from aware interfaces. E.g: `tag_id` in `TagAware`, `customer_id` from `CustomerAware` and so on.
  * Use `$flow->getData($key)` if you want to get the data from original events or additional data. E.g: `tag`, `customer`, `contactFormData` and so on.

You also need to register this action in the container as a service. Make sure to define a tag `<tag name="flow.action" priority="600">` at `<plugin root>/src/Resources/config/services.xml`. This tag will ensure that your action is included in the response of the *`/api/_info/flow-actions.json`* API. The priority attribute will determine the order of the action in the API response.

```XML
// <plugin root>/src/Resources/config/services.xml
<service id="Swag\CreateTagAction\Core\Content\Flow\Dispatching\Action\CreateTagAction">
    <argument type="service" id="tag.repository" />
    <tag name="flow.action" priority="600" key="action.create.tag"/>
</service>
```

Great, your own action is created completely. Let's go to the next step.

### Define action scope

In this step, you will know how to define your action scope for `CreateTagAction`.
There are three scopes for the `CreateTagAction`:

* Available for all *already Events*.
* Available for only one or multiple *already Events.*
* Available for new event (new event from this plugin).

#### `CreateTagAction` available for all *already Events*

* Just define the empty array in `CreateTagAction::requirements`

```php
    // plugin root>/src/Core/Content/Flow/Dispatching/Action/CreateTagAction.php
    ...

    public function requirements(): array
    {
        return [];
    }

    ...
```

That means when you define the requirements like the code above, all triggers in the flow builder can define the action `CreateTagAction` for the next progress.

![Flow Builder trigger](../../../../../assets/flow-builder-action-available-all-events.png)

Here, the action name is empty as the action name snippet is not yet defined.

#### `CreateTagAction` available for only one or multiple *already Events*

Make the `CreateTagAction` available for all events related to Order and Customer.

```php
    // <plugin root>/src/Core/Content/Flow/Dispatching/Action/CreateTagAction.php
    ...

    public function requirements(): array
    {
        return [OrderAware::class, CustomerAware::class];
    }

    ...
```

#### `CreateTagAction` available for new event

* For this case, you can define a new event and make the `CreateTagAction` available for this event.

* Event must implement the `TagAware`

```php
// <plugin root>/src/Core/Content/Flow/Subscriber/BusinessEventCollectorSubscriber.php
<?php declare(strict_types=1);

namespace Swag\CreateTagAction\Core\Content\Event;

use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\Event\EventData\EntityType;
use Shopware\Core\Framework\Event\EventData\EventDataCollection;
use Shopware\Core\System\Tag\TagDefinition;
use Shopware\Core\System\Tag\TagEntity;
use Swag\CreateTagAction\Core\Framework\Event\TagAware;
use Symfony\Contracts\EventDispatcher\Event;

class BasicExampleEvent extends Event implements TagAware
{
    public const EVENT_NAME = 'example.event';

    private TagEntity $tag;

    private Context $context;

    public function __construct(Context $context, TagEntity $tag)
    {
        $this->tag = $tag;
        $this->context = $context;
    }

    public function getName(): string
    {
        return self::EVENT_NAME;
    }

    public static function getAvailableData(): EventDataCollection
    {
        return (new EventDataCollection())
            ->add('tag', new EntityType(TagDefinition::class));
    }

    public function getContext(): Context
    {
        return $this->context;
    }

    public function getTag(): TagEntity
    {
        return $this->tag;
    }
}
```

* Define the `TagAware` in `CreateTagAction::requirements`

```php
    // <plugin root>/src/Core/Content/Flow/Dispatching/Action/CreateTagAction.php
    ...

    public function requirements(): array
    {
        return [TagAware::class];
    }

    ...
```

* To show the new event in Flow Builder Triggers list

```php
// <plugin root>/src/Core/Content/Subscriber/BusinessEventCollectorSubscriber.php
<?php declare(strict_types=1);
namespace Swag\CreateTagAction\Core\Content\Subscriber;

use Shopware\Core\Framework\Event\BusinessEventCollector;
use Shopware\Core\Framework\Event\BusinessEventCollectorEvent;
use Swag\CreateTagAction\Core\Content\Event\BasicExampleEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class BusinessEventCollectorSubscriber implements EventSubscriberInterface
{
    private BusinessEventCollector $businessEventCollector;

    public function __construct(BusinessEventCollector $businessEventCollector)
    {
        $this->businessEventCollector = $businessEventCollector;
    }

    public static function getSubscribedEvents()
    {
        return [
            BusinessEventCollectorEvent::NAME => 'onAddExampleEvent',
        ];
    }

    public function onAddExampleEvent(BusinessEventCollectorEvent $event): void
    {
        $collection = $event->getCollection();

        $definition = $this->businessEventCollector->define(BasicExampleEvent::class);

        if (!$definition) {
            return;
        }

        $collection->set($definition->getName(), $definition);
    }
}
```

And don't forget to register your subscriber to the container at `<plugin root>/src/Resources/config/services.xml`.

```xml
<service id="Swag\CreateTagAction\Core\Content\Subscriber\BusinessEventCollectorSubscriber">
    <argument type="service" id="Shopware\Core\Framework\Event\BusinessEventCollector"/>
    <tag name="kernel.event_subscriber"/>
</service>
```

* Define the Event snippet

```json
// <plugin root>/src/Resources/app/administration/src/module/sw-flow/snippet/en-GB.json
{
  "sw-flow": {
    "triggers": {
      "example": "Example",
      "event": "Event"
    }
  }
}
```

![Flow Builder trigger](../../../../../assets/flow-builder-triggers-list.png)

Well, you have successfully created your custom action in Backend in PHP.

## Add custom action in Administration

After we are done with the PHP code, `action.create.tag` is received from the response of `/api/_info/flow-actions.json`. However, the custom action displays in the action list without label. These further steps in Administration will help you show the action label and add configuration for it.

To see the action list, we select a Trigger, for example \[example\event], from the Trigger drop-down in the Flow tab. After that, we choose option `ACTION (THEN)`. An action component appears with an action list.

![Flow Builder trigger](../../../../../assets/flow-builder-trigger-drop.png)

![Flow Builder action then](../../../../../assets/flow-builder-action-then.png)

![Flow Builder trigger](../../../../../assets/flow-builder-action-no-label.png)

### Step 1: Show action label in action list

First, we need to define information like `constants`, `snippets` to show on the action list. To be consistent with the custom action defined in our PHP code, create an action name called `CREATE_TAG` to represent `action.create.tag`, which gets from the response of `/api/_info/flow-actions.json`.

![Flow Builder action services list](../../../../../assets/flow-builder-action-sevices-list.png)

```JS
// <plugin root>src/Resources/app/administration/src/constant/create-tag-action.constant.js
export const ACTION = Object.freeze({
    CREATE_TAG: 'action.create.tag',
});

export const GROUP = 'customer'

export default {
    ACTION, GROUP
};
```

And then add snippets for labels:

```JS
// src/Resources/app/administration/src/snippet/en-GB.json
{
    "create-tag-action": {
        "titleCreateTag": "Create tag",
        "labelTags": "Tags",
        "placeholderTags": "Enter tags",
        "buttonSaveAction": "Save action",
        "buttonAddAction": "Add action",
        "descriptionTags": "Tags: {tags}"
    }
}
```

Do it as the same with `de-DE.json` file for translation of DE language.

After that, we also need to override the `sw-flow-sequence-action` component in the core:

```JS
// <plugin root>/src/Resources/app/administration/src/extension/sw-flow-sequence-action/index.js
import { ACTION, GROUP } from '../../constant/create-tag-action.constant';

const { Component } = Shopware;

Component.override('sw-flow-sequence-action', {
    computed: {
        // Not necessary if you use an existing group
        // Push the `groups` method in computed if you are defining a new group
        groups() {
            this.actionGroups.unshift(GROUP);

            return this.$super('groups');
        },

        modalName() {
            if (this.selectedAction === ACTION.CREATE_TAG) {
                return 'sw-flow-create-tag-modal';
            }

            return this.$super('modalName');
        },
    },

    methods: {
        getActionDescriptions(sequence) {
            if(sequence.actionName === ACTION.CREATE_TAG){
                return this.getCreateTagDescription(sequence.config)
            }
            return this.$super('getActionDescriptions', sequence)
        },
        
        getCreateTagDescription(config) {
            const tags = config.tags.join(', ');

            return this.$tc('create-tag-action.descriptionTags', 0, {
                tags
            });
        },

        getActionTitle(actionName) {
            if (actionName === ACTION.CREATE_TAG) {
                return {
                    value: actionName,
                    icon: 'regular-tag',
                    label: this.$tc('create-tag-action.titleCreateTag'),
                    group: GROUP,
                }
            }

            return this.$super('getActionTitle', actionName);
        },
    },
});

```

Do not forget to import the file to the entry file `main.js`:

```JS
// <plugin root>/src/Resources/app/administration/src/main.js
import './extension/sw-flow-sequence-action';
```

**Grouping Actions**

As you can see, we already defined the constant for the group in `create-tag-action.constant.js`

```JS
export const GROUP = 'customer'
```

The new action `action.create.tag` will be shown on the Customer group.

![Choose a Flow Builder Action](../../../../../assets/flow-builder-action-customer-group.png)

It will default on the General group if it is not defined.

Here is a list of group names you should take a look at:

| Group Name | Group Headline |
| :--- | :--- |
| general | General|
| tag | Tag |
| customer | Customer |
| order | Order |

### Step 2: Add configuration for action

If you click the Create tag action, the below error will be shown on the console. That means we're going the right way.

![Choose a Flow Builder Action](../../../../../assets/flow-builder-action-error.png)

Because in `sw-flow-sequence-action`, we expect that the new modal has the name `sw-flow-create-tag-modal`.

```JS
modalName() {
    if (this.selectedAction === ACTION.CREATE_TAG) {
        return 'sw-flow-create-tag-modal';
    }

    return this.$super('modalName');
},
```

To define the modal, just create a new folder `sw-flow-create-tag-modal` in `src/Resources/app/administration/src/component` and create some files following:

#### JavaScript file

```JS
// <plugin root>/src/Resources/app/administration/src/component/sw-flow-create-tag-modal/index.js
import template from './sw-flow-create-tag-modal.html.twig';

const { Data: { Criteria, EntityCollection } } = Shopware;
const { Component, Context } = Shopware;

Component.register('sw-flow-create-tag-modal', {
    template,

    inject: [
        'repositoryFactory',
    ],

    props: {
        sequence: {
            type: Object,
            required: true,
        },
    },

    data() {
        return {
            tagCollection: [],
        };
    },

    computed: {
        tagRepository() {
            return this.repositoryFactory.create('tag');
        },

        tagCriteria() {
            const criteria = new Criteria(1, 25);
            const { config } = this.sequence;
            const tagIds = Object.keys(config.tagIds);
            if (tagIds.length) {
                criteria.addFilter(Criteria.equalsAny('id', tagIds));
            }

            return criteria;
        },
    },

    created() {
        this.createdComponent();
    },

    methods: {
        createdComponent() {
            this.tagCollection = this.createTagCollection();

            const { config } = this.sequence;
            if (this.sequence.id && config?.tagIds) {
                this.getTagCollection();
            }
        },

        getTagCollection() {
            return this.tagRepository.search(this.tagCriteria)
                .then(tags => {
                    this.tagCollection = tags;
                })
                .catch(() => {
                    this.tagCollection = [];
                });
        },

        createTagCollection() {
            return new EntityCollection(
                this.tagRepository.route,
                this.tagRepository.entityName,
                Context.api,
            );
        },

        onClose() {
            this.$emit('modal-close');
        },

        onAddTag(data) {
            this.tagCollection.add(data);
        },

        onRemoveTag(data) {
            this.tagCollection.remove(data);
        },

        getConfig() {
            const tagIds = {};
            this.tagCollection.forEach(tag => {
                Object.assign(tagIds, {
                    [tag.id]: tag.name,
                });
            });

            return {
                tagIds,
            };
        },

        onAddAction() {
            const config = this.getConfig();
            const data = {
                ...this.sequence,
                config,
            };

            this.$emit('process-finish', data);
        },
    },
});
```

#### Twig template file

```twig
// <plugin root>/src/Resources/app/administration/src/component/sw-flow-create-tag-modal/sw-flow-create-tag-modal.html.twig
{% block create_tag_action_modal %}
<sw-modal
    class="create-tag-action-modal"
    :title="$tc('create-tag-action.titleCreateTag')"
    @modal-close="onClose"
>
    {% block create_tag_action_modal_content %}
        <sw-entity-tag-select
            v-model="tagCollection"
            class="sw-flow-create-tag-modal__tags-field"
            required
            :label="$tc('create-tag-action.labelTags')"
            :placeholder="$tc('create-tag-action.placeholderTags')"
            @item-add="onAddTag"
            @item-remove="onRemoveTag"
        />
    {% endblock %}

    {% block create_tag_action_modall_footer %}
        <template #modal-footer>
            {% block create_tag_action_modal_footer_cancel_button %}
                <sw-button
                    class="create-tag-action-modal__cancel-button"
                    size="small"
                    @click="onClose"
                >
                    {{ $tc('global.default.cancel') }}
                </sw-button>
            {% endblock %}

            {% block create_tag_action_modal_footer_save_button %}
                <sw-button
                    class="create-tag-action-modal__save-button"
                    variant="primary"
                    size="small"
                    @click="onAddAction"
                >
                    {{ $tc('create-tag-action.buttonSaveAction') }}
                </sw-button>
            {% endblock %}
        </template>
    {% endblock %}
</sw-modal>
{% endblock %}
```

Please update the file `main.js` like this:

```JS
// <plugin root>/src/Resources/app/administration/src/main.js
import './extension/sw-flow-sequence-action';
import './component/sw-flow-create-tag-modal';
```

Here is the final result

![Flow Builder create tag](../../../../../assets/flow-builder-tag.png)

Click on \[Save action] and we will get the result as below screenshot.

![Flow Builder create tag result](../../../../../assets/flow-builder-tag-result.png)

#### Custom configuration for action without the modal

You don't need a modal for the configuration. It can be added automatically.

Imagine, your action is already in the action list after [the first step](#step-1-show-action-label-in-action-list)

![Choose a Flow Builder Action](../../../../../assets/flow-builder-trigger-action.png)

First, override the `openDynamicModal` method in the plugin to check if the value matches the desired action. Then, call the `onSaveActionSuccess` directly with the configuration. After the check, call `return`.

#### JavaScript

```JS
// <plugin root>/src/Resources/app/administration/src/extension/sw-flow-sequence-action/index.js
const { Component } = Shopware;

Component.register('sw-flow-sequence-action', {
    methods: {
        openDynamicModal(value) {
            if (!value) {
                return;
            }

            const actionName = this.flowBuilderService.getActionName('CREATE_TAG');

            if (value === actionName) {
                this.selectedAction = actionName;
                const config = {
                    tagIds: {
                        'tag_id_1': 'Vip',
                        'tag_id_2': 'New Customer',
                    },
                };

                // Config can be a result from an API.
                this.onSaveActionSuccess({ config });
                return;
            }

            // handle for the rest of actions.
        },
    },
});
```

Now, after you click on the action, the new sequence will automatically be added to the action list like this:

![Flow Builder create tag result](../../../../../assets/flow-builder-tag-result.png)

### Demo

You can view the whole demo for this custom Flow Builder trigger and action below:

![Flow Builder demo](../../../../../assets/flow-builder-demo.gif)

---

---
url: >-
  /docs/v6.5/guides/plugins/apps/flow-builder/add-custom-flow-actions-from-app-system.md
---

# Add custom flow actions

::: info
Custom flow actions in Shopware Apps are available starting with Shopware 6.4.10.0 and are not supported in previous versions.
:::

Besides the default actions, developers can add custom, predefined, and configurable web hook actions to the flow builder.

![Custom flow action in Administration](../../../../assets/flow-builder-app-action-preview.png)

After reading, you will be able to

* Create the basic setup of an app
* Create custom actions for the flow builder
* Use custom actions to interact with third-party services

## Prerequisites

Please make sure you already have a working Shopware 6 store running (either cloud or self-hosted). Prior knowledge about the Flow Builder feature of Shopware 6 is useful.

Please see the [Flow Builder Concept](../../../../concepts/framework/flow-concept) for more information.

## Create the app wrapper

To get started with your app, create an `apps` folder inside the `custom` folder of your Shopware dev installation. In there, create another directory for your application and provide a `manifest.xml` file, following the structure below:

```text
└── custom
    ├── apps
    │   └── FlowBuilderActionApp
    │       └── Resources
    │           └── flow-action.xml
    │           └── app-icon.png
    │           └── slack-icon.png
    │       └── manifest.xml
    └── plugins
```

::: info
From 6.5.2.0, you can define the flow action in `flow.xml`. The `flow-action.xml` will be removed from 6.6.0.0.
:::

| File name | Description |
| :--- | :--- |
| FlowBuilderActionApp | Your app's technical name |
| app-icon.png | The app's icon |
| slack-icon.png | Your action icon will be defined for each action in the `flow-action.xml` file. (optional, icons will default to a fallback) |
| flow-action.xml | Place to define your new actions |
| manifest.xml | Base information about your app |

### Manifest file

The manifest file is the central point of your app. It defines the interface between your app and the Shopware instance. It provides all the information concerning your app, as seen in the minimal version below:

```xml
// manifest.xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        <name>FlowBuilderActionApp</name>
        <label>Flow Builder Action App</label>
        <label lang="de-DE">Flow Builder Aktions-App</label>
        <description>This is the example description for app</description>
        <description lang="de-DE">Dies ist die Beispielbeschreibung für app</description>
        <author>shopware AG</author>
        <copyright>(c) shopware AG</copyright>
        <version>4.14.0</version>
        <icon>Resources/app-icon.png</icon>
        <license>MIT</license>
    </meta>
</manifest>
```

::: warning
The name of your app that you provide in the manifest file needs to match the folder name of your app.
:::

## Define the flow action

To create a flow action, you need to define a `<flow-action>` block within a file called `flow-action.xml`. Each `<flow-action>` represents one action and you can define an arbitrary number of actions.

```xml
// Resources/flow-action.xml
<flow-actions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/6.5.x/src/Core/Framework/App/FlowAction/Schema/flow-action-1.0.xsd">
    <flow-action>
        ... # The first action
    </flow-action>
    <flow-action>
        ... # The second action
    </flow-action>
    <flow-action>
        ... # The third action
    </flow-action>
    ...
</flow-actions>
```

From 6.5.2.0, to create a flow action, you must define a `<flow-actions>` block within a file called `flow.xml`. Each `<flow-action>` in `<flow-actions>` represents one action, and you can define an arbitrary number of actions.

```xml
<flow-extensions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Flow/Schema/flow-1.0.xsd">
    <flow-actions>
        <flow-action>
            ... # The first action
        </flow-action>
        <flow-action>
            ... # The second action
        </flow-action>
        <flow-action>
            ... # The third action
        </flow-action>
    </flow-actions>
    ...
</flow-extensions>
```

A single flow action would look like this:

```xml
<flow-action>
    <meta>
        <name>slackmessage</name>
        <label>Send slack message</label>
        <label lang="de-DE">Slack-Nachricht senden</label>
        <badge>Slack</badge>
        <description>Slack send message description</description>
        <description lang="de-DE">Dies ist die Beispielbeschreibung für app</description>
        <url>https://hooks.slack.com/services/{id}</url>
        <sw-icon>default-communication-speech-bubbles</sw-icon>
        <icon>slack.png</icon>
        <requirements>orderAware</requirements>
        <requirements>customerAware</requirements>
    </meta>
    ...
</flow-action>
```

| Key | Required | Description |
| :--- | :--- | :--- |
| name | yes | The technical name of your action, unique for all actions |
| label | yes | A name to be shown for your action in the actions list or action modal title |
| badge | no | An attached badge shown behind the label in the action modal title |
| description | yes | Detailed information for your action |
| sw-icon | no | An icon component name from the [icon library](https://component-library.shopware.com/icons/) |
| icon | no | Alternatively, a path to your action icon. In the case you define both `<sw-icon>` and `<icon>`, the `<icon>` will be take precedence in this case. |
| requirements | yes | Available action triggers, read more below |
| url | yes | External webhook location. Shopware will call this URL when the action is executed |

**requirements**

Requirements will decide for which trigger events your action is available.
Example: The `checkout.order.placed` has an `orderAware` requirements - indicating that your action is allow to use be used in the `checkout.order.placed` event. It is defined using `<requirements>orderAware</requirements>` in your app action definition.

For each value when you define, it'll represent one of the `aware` interfaces from the `core`.

To fulfill the requirements, refer to a subset of action triggers aware:

| Value | Interface |
| :--- | :--- |
| customerAware | Shopware\Core\Framework\Event\CustomerAware |
| customerGroupAware | Shopware\Core\Framework\Event\CustomerGroupAware |
| delayAware | Shopware\Core\Framework\Event\DelayAware |
| mailAware | Shopware\Core\Framework\Event\MailAware |
| orderAware | Shopware\Core\Framework\Event\OrderAware |
| salesChannelAware | Shopware\Core\Framework\Event\SalesChannelAware |
| userAware | Shopware\Core\Framework\Event\UserAware |

### Header parameters

```xml
<flow-action>
    <meta>
        ...
    </meta>
    <headers>
        <parameter type="string" name="content-type" value="application/json"/>
    </headers>
    ...
</flow-action>
```

| Key | Description |
| :--- | :--- |
| type | Parameter type - currently only `string` supported |
| name | The header key |
| value | The header value |

### Parameters

```xml
<flow-action>
    <meta>
        ...
    </meta>
    <headers>
        ...
    </headers>
    <parameters>
        <parameter type="string" name="text" value="{{ message }} \n Order Number: {{ order.orderNumber }}"/>
    </parameters>
    ...
</flow-action>
```

Define the `parameter` for the URL body based on your URL webhook services.

| Key | Description |
| :--- | :--- |
| type | Type of parameter, only support `string` type. |
| name | The body key for your URL. |
| value | The content message for your URL; free to design your content message here. |
| {{ message }} | The variable from your `<input-field>` defined in `flow-action.xml`. |
| {{ order.orderNumber }} | For each trigger event, the action will have the variables suitable. [Read more variables here](../../../../resources/references/app-reference/flow-action-reference). |

With the parameters configured like described above, an exemplary call of your Webhook Action could look like this:

```text
    POST https://hooks.slack.com/services/{id} {
        headers:
            content-type: application/json
        body:
            text: {{ message }} \n Order Number: {{ order.orderNumber }}
    }
```

### Action configuration

You can make your flow action configurable in the Administration by adding input fields. Based on your configuration - similar to the [app configurations](../../plugins/plugin-fundamentals/add-plugin-configuration) - you can later on use these configuration values within flow parameters.

```xml
<flow-action>
    <meta>
        ...
    </meta>
    <headers>
        ...
    </headers>
    <parameters>
        ...
    </parameters>
    <config>
        <input-field type="text">
            <name>message</name>
            <label>Message</label>
            <label lang="de-DE">Gegenstand</label>
            <place-holder>Placeholder</place-holder>
            <place-holder lang="de-DE">Platzhalter</place-holder>
            <required>true</required>
            <helpText>Help Text</helpText>
            <helpText lang="de-DE">Hilfstext</helpText>
        </input-field>
    </config>
</flow-action>
```

Available input field attributes:

| Key | Required |
| :--- | :--- |
| name | Yes |
| label | Yes |
| place-holder | No |
| required | No |
| helpText | No |

You assemble your configuration from a variety of input fields.

::: info
To get more information on how to create configuration forms, see [Plugin Configurations](../../plugins/plugin-fundamentals/add-plugin-configuration#the-different-types-of-input-field).
:::

| Type | Shopware component |
| :--- | :--- |
| text | `<sw-text-field/>` |
| textarea | `<sw-textarea-field/>` |
| text-editor | `<sw-text-editor/>` |
| url | `<sw-url-field/>` |
| password | `<sw-password-field/>` |
| int | `<sw-number-field/>` |
| float | `<sw-number-field/>`  |
| bool | `<sw-switch-field/>`  |
| checkbox | `<sw-checkbox-field/>`  |
| datetime | `<sw-datepicker/>`  |
| date | `<sw-datepicker/>` |
| time | `<sw-datepicker/>` |
| colorpicker | `<sw-colorpicker/>` |
| single-select | `<sw-single-select/>` |
| multi-select | `<sw-multi-select/>` |

## Install the App

The app can now be installed by running the following command:

```bash
bin/console app:install --activate FlowBuilderActionApp
```

## Further steps

* [Flow action example configuration](../../../../resources/references/app-reference/flow-action-reference) page
* [Schema definition for flow actions (GitHub)](https://github.com/shopware/shopware/blob/6.5.x/src/Core/Framework/App/FlowAction/Schema/flow-action-1.0.xsd)\`

---

---
url: >-
  /docs/v6.6/guides/plugins/apps/flow-builder/add-custom-flow-actions-from-app-system.md
---

# Add custom flow actions

::: info
Custom flow actions in Shopware Apps are available starting with Shopware 6.4.10.0 and are not supported in previous versions.
:::

Besides the default actions, developers can add custom, predefined, and configurable web hook actions to the flow builder.

![Custom flow action in Administration](../../../../assets/flow-builder-app-action-preview.png)

After reading, you will be able to

* Create the basic setup of an app
* Create custom actions for the flow builder
* Use custom actions to interact with third-party services

## Prerequisites

Please make sure you already have a working Shopware 6 store running (either cloud or self-hosted). Prior knowledge about the Flow Builder feature of Shopware 6 is useful.

Please see the [Flow Builder Concept](../../../../concepts/framework/flow-concept) for more information.

## Create the app wrapper

To get started with your app, create an `apps` folder inside the `custom` folder of your Shopware dev installation. In there, create another directory for your application and provide a `manifest.xml` file, following the structure below:

```text
└── custom
    ├── apps
    │   └── FlowBuilderActionApp
    │       └── Resources
    │           └── flow-action.xml
    │           └── app-icon.png
    │           └── slack-icon.png
    │       └── manifest.xml
    └── plugins
```

::: info
From 6.5.2.0, you can define the flow action in `flow.xml`. The `flow-action.xml` will be removed from 6.6.0.0.
:::

| File name | Description |
| :--- | :--- |
| FlowBuilderActionApp | Your app's technical name |
| app-icon.png | The app's icon |
| slack-icon.png | Your action icon will be defined for each action in the `flow-action.xml` file. (optional, icons will default to a fallback) |
| flow-action.xml | Place to define your new actions |
| manifest.xml | Base information about your app |

### Manifest file

The manifest file is the central point of your app. It defines the interface between your app and the Shopware instance. It provides all the information concerning your app, as seen in the minimal version below:

::: code-group

```xml [manifest.xml]
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        <name>FlowBuilderActionApp</name>
        <label>Flow Builder Action App</label>
        <label lang="de-DE">Flow Builder Aktions-App</label>
        <description>This is the example description for app</description>
        <description lang="de-DE">Dies ist die Beispielbeschreibung für app</description>
        <author>shopware AG</author>
        <copyright>(c) shopware AG</copyright>
        <version>4.14.0</version>
        <icon>Resources/app-icon.png</icon>
        <license>MIT</license>
    </meta>
</manifest>
```

:::

::: warning
The name of your app that you provide in the manifest file needs to match the folder name of your app.
:::

## Define the flow action

To create a flow action, you need to define a `<flow-action>` block within a file called `flow-action.xml`. Each `<flow-action>` represents one action and you can define an arbitrary number of actions.

```xml
// Resources/flow-action.xml
<flow-actions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Flow/Schema/flow-1.0.xsd">
    <flow-action>
        ... # The first action
    </flow-action>
    <flow-action>
        ... # The second action
    </flow-action>
    <flow-action>
        ... # The third action
    </flow-action>
    ...
</flow-actions>
```

From 6.5.2.0, to create a flow action, you must define a `<flow-actions>` block within a file called `flow.xml`. Each `<flow-action>` in `<flow-actions>` represents one action, and you can define an arbitrary number of actions.

```xml
<flow-extensions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Flow/Schema/flow-1.0.xsd">
    <flow-actions>
        <flow-action>
            ... # The first action
        </flow-action>
        <flow-action>
            ... # The second action
        </flow-action>
        <flow-action>
            ... # The third action
        </flow-action>
    </flow-actions>
    ...
</flow-extensions>
```

A single flow action would look like this:

```xml
<flow-action>
    <meta>
        <name>slackmessage</name>
        <label>Send slack message</label>
        <label lang="de-DE">Slack-Nachricht senden</label>
        <badge>Slack</badge>
        <description>Slack send message description</description>
        <description lang="de-DE">Dies ist die Beispielbeschreibung für app</description>
        <url>https://hooks.slack.com/services/{id}</url>
        <sw-icon>default-communication-speech-bubbles</sw-icon>
        <icon>slack.png</icon>
        <requirements>orderAware</requirements>
        <requirements>customerAware</requirements>
    </meta>
    ...
</flow-action>
```

| Key | Required | Description |
| :--- | :--- | :--- |
| name | yes | The technical name of your action, unique for all actions |
| label | yes | A name to be shown for your action in the actions list or action modal title |
| badge | no | An attached badge shown behind the label in the action modal title |
| description | yes | Detailed information for your action |
| sw-icon | no | An icon component name from the [icon library](https://component-library.shopware.com/icons/) |
| icon | no | Alternatively, a path to your action icon. In the case you define both `<sw-icon>` and `<icon>`, the `<icon>` will be take precedence in this case. |
| requirements | yes | Available action triggers, read more below |
| url | yes | External webhook location. Shopware will call this URL when the action is executed |

**requirements**

Requirements will decide for which trigger events your action is available.
Example: The `checkout.order.placed` has an `orderAware` requirements - indicating that your action is allow to use be used in the `checkout.order.placed` event. It is defined using `<requirements>orderAware</requirements>` in your app action definition.

For each value when you define, it'll represent one of the `aware` interfaces from the `core`.

To fulfill the requirements, refer to a subset of action triggers aware:

| Value | Interface |
| :--- | :--- |
| customerAware | Shopware\Core\Framework\Event\CustomerAware |
| customerGroupAware | Shopware\Core\Framework\Event\CustomerGroupAware |
| delayAware | Shopware\Core\Framework\Event\DelayAware |
| mailAware | Shopware\Core\Framework\Event\MailAware |
| orderAware | Shopware\Core\Framework\Event\OrderAware |
| salesChannelAware | Shopware\Core\Framework\Event\SalesChannelAware |
| userAware | Shopware\Core\Framework\Event\UserAware |

### Header parameters

```xml
<flow-action>
    <meta>
        ...
    </meta>
    <headers>
        <parameter type="string" name="content-type" value="application/json"/>
    </headers>
    ...
</flow-action>
```

| Key | Description |
| :--- | :--- |
| type | Parameter type - currently only `string` supported |
| name | The header key |
| value | The header value |

### Parameters

```xml
<flow-action>
    <meta>
        ...
    </meta>
    <headers>
        ...
    </headers>
    <parameters>
        <parameter type="string" name="text" value="{{ message }} \n Order Number: {{ order.orderNumber }}"/>
    </parameters>
    ...
</flow-action>
```

Define the `parameter` for the URL body based on your URL webhook services.

| Key | Description |
| :--- | :--- |
| type | Type of parameter, only support `string` type. |
| name | The body key for your URL. |
| value | The content message for your URL; free to design your content message here. |
| {{ message }} | The variable from your `<input-field>` defined in `flow-action.xml`. |
| {{ order.orderNumber }} | For each trigger event, the action will have the variables suitable. [Read more variables here](../../../../resources/references/app-reference/flow-action-reference). |

With the parameters configured like described above, an exemplary call of your Webhook Action could look like this:

```text
    POST https://hooks.slack.com/services/{id} {
        headers:
            content-type: application/json
        body:
            text: {{ message }} \n Order Number: {{ order.orderNumber }}
    }
```

### Action configuration

You can make your flow action configurable in the Administration by adding input fields. Based on your configuration - similar to the [app configurations](../../plugins/plugin-fundamentals/add-plugin-configuration) - you can later on use these configuration values within flow parameters.

```xml
<flow-action>
    <meta>
        ...
    </meta>
    <headers>
        ...
    </headers>
    <parameters>
        ...
    </parameters>
    <config>
        <input-field type="text">
            <name>message</name>
            <label>Message</label>
            <label lang="de-DE">Gegenstand</label>
            <place-holder>Placeholder</place-holder>
            <place-holder lang="de-DE">Platzhalter</place-holder>
            <required>true</required>
            <helpText>Help Text</helpText>
            <helpText lang="de-DE">Hilfstext</helpText>
        </input-field>
    </config>
</flow-action>
```

Available input field attributes:

| Key | Required |
| :--- | :--- |
| name | Yes |
| label | Yes |
| place-holder | No |
| required | No |
| helpText | No |

You assemble your configuration from a variety of input fields.

::: info
To get more information on how to create configuration forms, see [Plugin Configurations](../../plugins/plugin-fundamentals/add-plugin-configuration#the-different-types-of-input-field).
:::

| Type | Shopware component |
| :--- | :--- |
| text | `<sw-text-field/>` |
| textarea | `<sw-textarea-field/>` |
| text-editor | `<sw-text-editor/>` |
| url | `<sw-url-field/>` |
| password | `<sw-password-field/>` |
| int | `<sw-number-field/>` |
| float | `<sw-number-field/>`  |
| bool | `<sw-switch-field/>`  |
| checkbox | `<sw-checkbox-field/>`  |
| datetime | `<sw-datepicker/>`  |
| date | `<sw-datepicker/>` |
| time | `<sw-datepicker/>` |
| colorpicker | `<sw-colorpicker/>` |
| single-select | `<sw-single-select/>` |
| multi-select | `<sw-multi-select/>` |

## Install the App

The app can now be installed by running the following command:

```bash
bin/console app:install --activate FlowBuilderActionApp
```

## Further steps

* [Flow action example configuration](../../../../resources/references/app-reference/flow-action-reference) page
* [Schema definition for flow actions (GitHub)](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/App/Flow/Schema/flow-1.0.xsd)\`

---

---
url: >-
  /docs/guides/plugins/apps/flow-builder/add-custom-flow-actions-from-app-system.md
---

# Add Custom Flow Actions

::: info
Custom flow actions in Shopware Apps are available starting with Shopware 6.4.10.0 and are not supported in previous versions.
:::

## Overview

Besides the default actions, developers can add custom, predefined, and configurable web hook actions to the flow builder.

![Custom flow action in Administration](../../../../assets/flow-builder-app-action-preview.png)

After reading, you will be able to

* Create the basic setup of an app
* Create custom actions for the flow builder
* Use custom actions to interact with third-party services

## Prerequisites

Please make sure you already have a working Shopware 6 store running (either cloud or self-hosted). Prior knowledge about the Flow Builder feature of Shopware 6 is useful.

Please see the [Flow Builder Concept](../../../../concepts/framework/flow-concept.md) for more information.

## Create the app wrapper

To get started with your app, create an `apps` folder inside the `custom` folder of your Shopware dev installation. In there, create another directory for your application and provide a `manifest.xml` file, following the structure below:

```text
└── custom
    ├── apps
    │   └── FlowBuilderActionApp
    │       └── Resources
    │           └── flow.xml
    │           └── app-icon.png
    │           └── discord-icon.png
    │       └── manifest.xml
    └── plugins
```

| File name            | Description                                                                                                            |
|:---------------------|:-----------------------------------------------------------------------------------------------------------------------|
| FlowBuilderActionApp | Your app's technical name                                                                                              |
| app-icon.png         | The app's icon                                                                                                         |
| slack-icon.png       | Your action icon will be defined for each action in the `flow.xml` file. (optional, icons will default to a fallback)  |
| flow.xml             | Place to define your new actions                                                                                       |
| manifest.xml         | Base information about your app                                                                                        |

### Manifest file

The manifest file is the central point of your app. It defines the interface between your app and the Shopware instance. It provides all the information concerning your app, as seen in the minimal version below:

::: code-group

```xml [manifest.xml]
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        <name>FlowBuilderActionApp</name>
        <label>Flow Builder Action App</label>
        <label lang="de-DE">Flow Builder Aktions-App</label>
        <description>This is the example description for app</description>
        <description lang="de-DE">Dies ist die Beispielbeschreibung für app</description>
        <author>shopware AG</author>
        <copyright>(c) shopware AG</copyright>
        <version>4.14.0</version>
        <icon>Resources/app-icon.png</icon>
        <license>MIT</license>
    </meta>
</manifest>
```

:::

::: warning
The name of your app that you provide in the manifest file needs to match the folder name of your app.
:::

## Define the flow action

To create a flow action, you must define a `<flow-actions>` block within a file called `flow.xml`. Each `<flow-action>` in `<flow-actions>` represents one action, and you can define an arbitrary number of actions.

::: code-group

```xml [Resources/flow.xml]
<flow-extensions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Flow/Schema/flow-1.0.xsd">
    <flow-actions>
        <flow-action>
            ... # The first action
        </flow-action>
        <flow-action>
            ... # The second action
        </flow-action>
        <flow-action>
            ... # The third action
        </flow-action>
    </flow-actions>
    ...
</flow-extensions>
```

:::

A single flow action would look like this:

```xml
<flow-action>
    <meta>
        <name>slackmessage</name>
        <label>Send slack message</label>
        <label lang="de-DE">Slack-Nachricht senden</label>
        <badge>Slack</badge>
        <description>Slack send message description</description>
        <description lang="de-DE">Dies ist die Beispielbeschreibung für app</description>
        <url>https://hooks.slack.com/services/{id}</url>
        <sw-icon>default-communication-speech-bubbles</sw-icon>
        <icon>slack.png</icon>
        <requirements>orderAware</requirements>
        <requirements>customerAware</requirements>
    </meta>
    ...
</flow-action>
```

| Key          | Required | Description                                                                                                                                         |
|:-------------|:---------|:----------------------------------------------------------------------------------------------------------------------------------------------------|
| name         | yes      | The technical name of your action, unique for all actions                                                                                           |
| label        | yes      | A name to be shown for your action in the actions list or action modal title                                                                        |
| badge        | no       | An attached badge shown behind the label in the action modal title                                                                                  |
| description  | yes      | Detailed information for your action                                                                                                                |
| sw-icon      | no       | An icon component name from the [icon library](https://shopware.design/icons/)                                                                      |
| icon         | no       | Alternatively, a path to your action icon. In the case you define both `<sw-icon>` and `<icon>`, the `<icon>` will be take precedence in this case. |
| requirements | yes      | Available action triggers, read more below                                                                                                          |
| url          | yes      | External webhook location. Shopware will call this URL when the action is executed                                                                  |

**requirements**

Requirements will decide for which trigger events your action is available.
Example: The `checkout.order.placed` trigger has an `orderAware` requirement, indicating that your action is allowed to be used in the `checkout.order.placed` event. It is defined using `<requirements>orderAware</requirements>` in your app action definition.

For each value when you define, it'll represent one of the `aware` interfaces from the `core`.

To fulfill the requirements, refer to a subset of action triggers aware:

| Value              | Interface                                        |
|:-------------------|:-------------------------------------------------|
| customerAware      | Shopware\Core\Framework\Event\CustomerAware      |
| customerGroupAware | Shopware\Core\Framework\Event\CustomerGroupAware |
| delayAware         | Shopware\Core\Framework\Event\DelayAware         |
| mailAware          | Shopware\Core\Framework\Event\MailAware          |
| orderAware         | Shopware\Core\Framework\Event\OrderAware         |
| salesChannelAware  | Shopware\Core\Framework\Event\SalesChannelAware  |
| userAware          | Shopware\Core\Framework\Event\UserAware          |

### Header parameters

```xml
<flow-action>
    <meta>
        ...
    </meta>
    <headers>
        <parameter type="string" name="content-type" value="application/json"/>
    </headers>
    ...
</flow-action>
```

| Key   | Description                                        |
|:------|:---------------------------------------------------|
| type  | Parameter type - currently only `string` supported |
| name  | The header key                                     |
| value | The header value                                   |

### Parameters

```xml
<flow-action>
    <meta>
        ...
    </meta>
    <headers>
        ...
    </headers>
    <parameters>
        <parameter type="string" name="text" value="{{ message }} \n Order Number: {{ order.orderNumber }}"/>
    </parameters>
    ...
</flow-action>
```

Define the `parameter` for the URL body based on your URL webhook services.

| Key                                        | Description                                                                                                                                                            |
|:-------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| type                                       | Type of parameter, only support `string` type.                                                                                                                         |
| name                                       | The body key for your URL.                                                                                                                                             |
| value                                      | The content message for your URL; free to design your content message here.                                                                                            |
| {{ message }}           | The variable from your `<input-field>` defined in `flow.xml`.                                                                                                          |
| {{ order.orderNumber }} | For each trigger event, the action will have the variables suitable. [Read more variables here](../../../../resources/references/app-reference/flow-action-reference). |

With the parameters configured as described above, an exemplary call of your Webhook Action could look like this:

```text
    POST https://hooks.slack.com/services/{id} {
        headers:
            content-type: application/json
        body:
            text: {{ message }} \n Order Number: {{ order.orderNumber }}
    }
```

### Action configuration

You can make your flow action configurable in the Administration by adding input fields. Based on your configuration - similar to the [app configurations](../../plugins/plugin-fundamentals/add-plugin-configuration) - you can later on use these configuration values within flow parameters.

```xml
<flow-action>
    <meta>
        ...
    </meta>
    <headers>
        ...
    </headers>
    <parameters>
        ...
    </parameters>
    <config>
        <input-field type="text">
            <name>message</name>
            <label>Message</label>
            <label lang="de-DE">Gegenstand</label>
            <place-holder>Placeholder</place-holder>
            <place-holder lang="de-DE">Platzhalter</place-holder>
            <required>true</required>
            <helpText>Help Text</helpText>
            <helpText lang="de-DE">Hilfstext</helpText>
        </input-field>
    </config>
</flow-action>
```

Available input field attributes:

| Key          | Required |
|:-------------|:---------|
| name         | Yes      |
| label        | Yes      |
| place-holder | No       |
| required     | No       |
| helpText     | No       |

You assemble your configuration from a variety of input fields.

::: info
To get more information on how to create configuration forms, see [Plugin Configurations](../../plugins/plugin-fundamentals/add-plugin-configuration.md#the-different-types-of-input-field).
:::

| Type          | Shopware component     |
|:--------------|:-----------------------|
| text          | `<sw-text-field/>`     |
| textarea      | `<sw-textarea-field/>` |
| text-editor   | `<sw-text-editor/>`    |
| url           | `<sw-url-field/>`      |
| password      | `<sw-password-field/>` |
| int           | `<sw-number-field/>`   |
| float         | `<sw-number-field/>`   |
| bool          | `<sw-switch-field/>`   |
| checkbox      | `<sw-checkbox-field/>` |
| datetime      | `<sw-datepicker/>`     |
| date          | `<sw-datepicker/>`     |
| time          | `<sw-datepicker/>`     |
| colorpicker   | `<sw-colorpicker/>`    |
| single-select | `<sw-single-select/>`  |
| multi-select  | `<sw-multi-select/>`   |

## Install the App

The app can now be installed by running the following command:

```bash
bin/console app:install --activate FlowBuilderActionApp
```

## Further steps

* [Flow action example configuration](../../../../resources/references/app-reference/flow-action-reference.md) page
* [Schema definition for flow actions (GitHub)](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/App/Flow/Schema/flow-1.0.xsd)\`

---

---
url: >-
  /docs/guides/plugins/apps/flow-builder/add-custom-flow-triggers-from-app-system.md
---

# Add custom flow trigger

::: info
The Shopware app custom flow triggers are only accessible from 6.5.3.0 and later versions.
:::

## Overview

In addition to the default triggers, you have the option to incorporate custom, pre-defined, and adjustable triggers into the flow builder.

![Custom flow trigger in Administration](../../../../assets/flow-builder-custom-trigger-preview.png)

After reading, you will be able to :

* Create the basic setup of an app.
* Create custom triggers for the flow builder.
* Use an API to interact with custom triggers.

## Prerequisites

Please ensure you have a working Shopware 6 store (either cloud or self-hosted). Prior knowledge about the Flow Builder feature of Shopware 6 is useful.

Please see the [Flow Builder Concept](../../../../concepts/framework//flow-concept.md) for more information.

## Create the app wrapper

To get started with your app, create an `apps` folder inside the `custom` folder of your Shopware dev installation. Next, create another directory inside for your application and provide a `manifest.xml` file following the structure below:

```text
└── custom
    ├── apps
    │   └── FlowBuilderTriggerApp
    │       └── Resources
    │           └── app
    │               └── administration
    │                   └── snippet
    │                       └── de-DE.json
    │                       └── en-GB.json
    │           └── flow.xml
    │       └── manifest.xml
    └── plugins
```

| File name             | Description                                        |
|:----------------------|:---------------------------------------------------|
| FlowBuilderTriggerApp | Your app's technical name                          |
| flow.xml              | Place to define your new triggers                  |
| de-DE.json            | Snippet to translate your trigger name for Deutsch |
| en-GB.json            | Snippet to translate your trigger name for English |
| manifest.xml          | Base information about your app                    |

### Manifest file

The manifest file is the central point of your app. It defines the interface between your app and the Shopware instance. It provides all the information concerning your app, as seen in the minimal version below:

::: code-group

```xml [manifest.xml]
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        <name>FlowBuilderTriggerApp</name>
        <label>Flow Builder Trigger App</label>
        <label lang="de-DE">Flow Builder Abzug-App</label>
        <description>This is the example description for app</description>
        <description lang="de-DE">Dies ist die Beispielbeschreibung für app</description>
        <author>shopware AG</author>
        <copyright>(c) shopware AG</copyright>
        <version>4.14.0</version>
        <icon>Resources/app-icon.png</icon>
        <license>MIT</license>
    </meta>
</manifest>
```

:::

::: warning
The name of your app that you provide in the manifest file needs to match the folder name of your app.
:::

## Define the flow trigger

To create a flow trigger, you need to define a `<flow-event>` block within a file called `flow.xml`. Each `<flow-event>` represents one trigger, and you can define an arbitrary number of events.

::: code-group

```xml [Resources/flow.xml]
<flow-extensions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Flow/Schema/flow-1.0.xsd">
    <flow-events>
        <flow-event>
            ... # The first trigger
        </flow-event>
        <flow-event>
            ... # The second trigger
        </flow-event>
    </flow-events>
    ...
</flow-extensions>
```

:::

A single flow trigger would look like this:

```xml
<flow-event>
    <name>swag.before.open_the_doors</name>
    <aware>orderAware</aware>
</flow-event>
```

| Key          | Required | Description                                                 |
|:-------------|:---------|:------------------------------------------------------------|
| name         | yes      | The technical name of your trigger, unique for all actions. |
| aware        | no       | Filter actions for your trigger, read more below.           |

**aware**

The `aware` will decide which actions are available for your trigger.

***Example***

If you define the `orderAware` in your trigger config `<aware>orderAware</aware>`, the actions related to the Order will be available when the trigger is selected.

* action.add.order.tag,
* action.remove.order.tag,
* action.generate.document,
* action.grant.download.access,
* action.set.order.state,
* action.add.order.affiliate.and.campaign.code,
* action.set.order.custom.field,
* action.stop.flow

If you define the `customerAware` in your trigger config `<aware>orderAware</aware>`, the actions related to Customer will be available when the trigger is selected.

* action.add.customer.tag
* action.remove.customer.tag
* action.change.customer.group
* action.change.customer.status
* action.set.customer.custom.field
* action.add.customer.affiliate.and.campaign.code
* action.stop.flow

Each value defined, it represents one of the `aware` interfaces from the `core`.

To fulfill the `aware`, refer to a subset of action triggers aware:

| Value              | Interface                                        |
|:-------------------|:-------------------------------------------------|
| customerAware      | Shopware\Core\Framework\Event\CustomerAware      |
| customerGroupAware | Shopware\Core\Framework\Event\CustomerGroupAware |
| delayAware         | Shopware\Core\Framework\Event\DelayAware         |
| mailAware          | Shopware\Core\Framework\Event\MailAware          |
| orderAware         | Shopware\Core\Framework\Event\OrderAware         |
| salesChannelAware  | Shopware\Core\Framework\Event\SalesChannelAware  |
| userAware          | Shopware\Core\Framework\Event\UserAware          |

Please refer to the [Schema definition for flow events (GitHub)](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/App/Flow/Schema/flow-1.0.xsd) for more information.

## Trigger API

We provided an API with the endpoint `POST: /api/_action/trigger-event/{eventName}` to dispatch the custom trigger when you call the API.
The app calls the API to trigger the custom event and can provide the data. The API will create a CustomAppEvent object and dispatch it with the data provided.
The data given will be saved through `StorableFlow`. This can be utilized for actions or email templates.

Here is an example to define data from the API:

```json
    {
        "customerId": "d20e4d60e35e4afdb795c767eee08fec",
        "salesChannelId": "55cb094fd1794d489c63975a6b4b5b90",
        "shopName": "Shopware's Shop",
        "url": "https://shopware.com" 
    }
```

Flow actions can retrieve the data from FlowStorer.

```php
    $salesChanelId = $flow->getData(MailAware::SALES_CHANNEL_ID));
    $customer = $flow->getData(CustomerAware::CUSTOMER_ID));
```

Or we can use the data when defining the email template.

```html
    <h3>Welcome to {{ shopName }}</h3>
    <h1>Visit us at: {{ url }} </h1>
```

Please see the [StorableFlow Concept](../../../../resources/references/adr/2022-07-21-adding-the-storable-flow-to-implement-delay-action-in-flow-builder.md) for more information.

## Snippet for translation

You can define snippets to translate your custom trigger to show the trigger tree and flow list. Refer to the [Adding snippets](../../plugins/administration/templates-styling/adding-snippets.md) guide for more information.

Snippet keys should be defined based on your trigger name defined at `<name>` in your `flow.xml`.

| Fixed key            | Description                                                          |
|:---------------------|:---------------------------------------------------------------------|
| sw-flow-custom-event | All the keys related to the custom trigger will be defined inside    |
| event-tree           | All the keys used to trigger the tree will be defined inside         |
| flow-list            | All the keys used to flow list will be defined inside                |

***Example***

```xml
// Resources/flow.xml
<flow-extensions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Flow/Schema/flow-1.0.xsd">
    <flow-events>
        <flow-event>
            <name>swag.before.open_the_doors</name>
            ...
        </flow-event>
    </flow-events>
</flow-extensions>
```

```javascript
// custom/apps/FlowBuilderTriggerApp/Resources/app/administration/snippet/en-GB.json
{
  "sw-flow-custom-event": {
    "event-tree": {
      "swag": "Swag",
      "before": "Before",
      "openTheDoors": "Open the doors"
    },
    "flow-list": {
      "swag_before_open_the_doors": "Before open the doors"
    }
  }
}
```

## Install the App

The app can now be installed by running the following command:

```bash
bin/console app:install --activate FlowBuilderTriggerApp
```

---

---
url: >-
  /docs/v6.5/guides/plugins/apps/flow-builder/add-custom-flow-triggers-from-app-system.md
---

# Add custom flow trigger

::: info
The Shopware app custom flow triggers are only accessible from 6.5.3.0 and later versions.
:::

In addition to the default triggers, you have the option to incorporate custom, pre-defined, and adjustable triggers into the flow builder.

![Custom flow trigger in Administration](../../../../assets/flow-builder-custom-trigger-preview.png)

After reading, you will be able to :

* Create the basic setup of an app.
* Create custom triggers for the flow builder.
* Use an API to interact with custom triggers.

## Prerequisites

Please ensure you have a working Shopware 6 store (either cloud or self-hosted). Prior knowledge about the Flow Builder feature of Shopware 6 is useful.

Please see the [Flow Builder Concept](../../../../concepts/framework/flow-concept) for more information.

## Create the app wrapper

To get started with your app, create an `apps` folder inside the `custom` folder of your Shopware dev installation. Next, create another directory inside for your application and provide a `manifest.xml` file following the structure below:

```text
└── custom
    ├── apps
    │   └── FlowBuilderTriggerApp
    │       └── Resources
    │           └── app
    │               └── administration
    │                   └── snippet
    │                       └── de-DE.json
    │                       └── en-GB.json
    │           └── flow.xml
    │       └── manifest.xml
    └── plugins
```

| File name             | Description                                        |
|:----------------------|:---------------------------------------------------|
| FlowBuilderTriggerApp | Your app's technical name                          |
| flow.xml              | Place to define your new triggers                  |
| de-DE.json            | Snippet to translate your trigger name for Deutsch |
| en-GB.json            | Snippet to translate your trigger name for English |
| manifest.xml          | Base information about your app                    |

### Manifest file

The manifest file is the central point of your app. It defines the interface between your app and the Shopware instance. It provides all the information concerning your app, as seen in the minimal version below:

```xml
// manifest.xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        <name>FlowBuilderTriggerApp</name>
        <label>Flow Builder Trigger App</label>
        <label lang="de-DE">Flow Builder Abzug-App</label>
        <description>This is the example description for app</description>
        <description lang="de-DE">Dies ist die Beispielbeschreibung für app</description>
        <author>shopware AG</author>
        <copyright>(c) shopware AG</copyright>
        <version>4.14.0</version>
        <icon>Resources/app-icon.png</icon>
        <license>MIT</license>
    </meta>
</manifest>
```

::: warning
The name of your app that you provide in the manifest file needs to match the folder name of your app.
:::

## Define the flow trigger

To create a flow trigger, you need to define a `<flow-event>` block within a file called `flow.xml`. Each `<flow-event>` represents one trigger, and you can define an arbitrary number of events.

```xml
// Resources/flow.xml
<flow-extensions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Flow/Schema/flow-1.0.xsd">
    <flow-events>
        <flow-event>
            ... # The first trigger
        </flow-event>
        <flow-event>
            ... # The second trigger
        </flow-event>
    </flow-events>
    ...
</flow-extensions>
```

A single flow trigger would look like this:

```xml
<flow-event>
    <name>swag.before.open_the_doors</name>
    <aware>orderAware</aware>
</flow-event>
```

| Key          | Required | Description                                                 |
|:-------------|:---------|:------------------------------------------------------------|
| name         | yes      | The technical name of your trigger, unique for all actions. |
| aware        | no       | Filter actions for your trigger, read more below.           |

**aware**

The `aware` will decide which actions are available for your trigger.

***Example***

If you define the `orderAware` in your trigger config `<aware>orderAware</aware>`, the actions related to the Order will be available when the trigger is selected.

* action.add.order.tag,
* action.remove.order.tag,
* action.generate.document,
* action.grant.download.access,
* action.set.order.state,
* action.add.order.affiliate.and.campaign.code,
* action.set.order.custom.field,
* action.stop.flow

If you define the `customerAware` in your trigger config `<aware>orderAware</aware>`, the actions related to Customer will be available when the trigger is selected.

* action.add.customer.tag
* action.remove.customer.tag
* action.change.customer.group
* action.change.customer.status
* action.set.customer.custom.field
* action.add.customer.affiliate.and.campaign.code
* action.stop.flow

Each value defined, it represents one of the `aware` interfaces from the `core`.

To fulfill the `aware`, refer to a subset of action triggers aware:

| Value              | Interface                                        |
|:-------------------|:-------------------------------------------------|
| customerAware      | Shopware\Core\Framework\Event\CustomerAware      |
| customerGroupAware | Shopware\Core\Framework\Event\CustomerGroupAware |
| delayAware         | Shopware\Core\Framework\Event\DelayAware         |
| mailAware          | Shopware\Core\Framework\Event\MailAware          |
| orderAware         | Shopware\Core\Framework\Event\OrderAware         |
| salesChannelAware  | Shopware\Core\Framework\Event\SalesChannelAware  |
| userAware          | Shopware\Core\Framework\Event\UserAware          |

Please refer to the [Schema definition for flow events (GitHub)](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/App/Flow/Schema/flow-1.0.xsd) for more information.

## Trigger API

We provided an API with the endpoint `POST: /api/_action/trigger-event/{eventName}` to dispatch the custom trigger when you call the API.
The app calls the API to trigger the custom event and can provide the data. The API will create a CustomAppEvent object and dispatch it with the data provided.
The data given will be saved through `StorableFlow`. This can be utilized for actions or email templates.

Here is an example to define data from the API:

```json
    {
        "customerId": "d20e4d60e35e4afdb795c767eee08fec",
        "salesChannelId": "55cb094fd1794d489c63975a6b4b5b90",
        "shopName": "Shopware's Shop",
        "url": "https://shopware.com" 
    }
```

Flow actions can retrieve the data from FlowStorer.

```php
    $salesChanelId = $flow->getData(MailAware::SALES_CHANNEL_ID));
    $customer = $flow->getData(CustomerAware::CUSTOMER_ID));
```

Or we can use the data when defining the email template.

```html
    <h3>Welcome to {{ shopName }}</h3>
    <h1>Visit us at: {{ url }} </h1>
```

Please see the [StorableFlow Concept](../../../../resources/references/adr/2022-07-21-adding-the-storable-flow-to-implement-delay-action-in-flow-builder) for more information.

## Snippet for translation

You can define snippets to translate your custom trigger to show the trigger tree and flow list. Refer to the [Adding snippets](../../plugins/administration/adding-snippets) guide for more information.

Snippet keys should be defined based on your trigger name defined at `<name>` in your `flow.xml`.

| Fixed key            | Description                                                          |
|:---------------------|:---------------------------------------------------------------------|
| sw-flow-custom-event | All the keys related to the custom trigger will be defined inside    |
| event-tree           | All the keys used to trigger the tree will be defined inside         |
| flow-list            | All the keys used to flow list will be defined inside                |

***Example***

```xml
// Resources/flow.xml
<flow-extensions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Flow/Schema/flow-1.0.xsd">
    <flow-events>
        <flow-event>
            <name>swag.before.open_the_doors</name>
            ...
        </flow-event>
    </flow-events>
</flow-extensions>
```

```js
// custom/apps/FlowBuilderTriggerApp/Resources/app/administration/snippet/en-GB.json
{
  "sw-flow-custom-event": {
    "event-tree": {
      "swag": "Swag",
      "before": "Before",
      "openTheDoors": "Open the doors"
    },
    "flow-list": {
      "swag_before_open_the_doors": "Before open the doors"
    }
  }
}
```

## Install the App

The app can now be installed by running the following command:

```bash
bin/console app:install --activate FlowBuilderTriggerApp
```

---

---
url: /docs/v6.5/guides/plugins/plugins/framework/flow/add-flow-builder-trigger.md
---

# Add custom flow trigger

::: info
This functionality is available starting with Shopware 6.4.6.0
:::

## Overview

In this guide, you'll learn how to create a custom flow trigger in Shopware. Triggers are used by the flow builder. This example will introduce a new custom trigger. The shop owner is then able to define what to do with the new trigger.

## Prerequisites

In order to add your own custom flow trigger for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../../plugin-base-guide).

You also should be familiar with [Add custom event](../event/add-custom-event) to know how to create an event. Please refer to the [Flow Builder concept](../../../../../concepts/framework/flow-concept)
for better integration later.

## Existing triggers and actions

You can refer to the [Flow reference](../../../../../resources/references/core-reference/flow-reference) to read triggers and actions detail.

## Event interfaces and classes

Any event that implements one of these interfaces will be available in the trigger list of the Flow Builder module in Administration. Besides, the event will have the ability to execute the action that belongs to the interface.

* `MailAware`: This interface provides `MailRecipientStruct` and `salesChannelId`.

* `OrderAware`: This interface provides `orderId`, which is used to add tags, sendmail or generate documents, etc...

* `CustomerAware`: This interface same as `OrderAware` but for customer, which provide `customerId`, used to add tags, remove tags, sendmail, etc...

* `UserAware`: This interface provides `userId` for all actions related to the user.

* `SalesChannelAware`: This interface simply provides `salesChannelId`.

## Create custom flow trigger

To create a custom flow trigger, firstly you have to create a plugin and install it, you can refer to the [Plugin Base Guide](../../plugin-base-guide) to do it. I will create a plugin named `ExamplePlugin`. There will be an example to actually show your new trigger in the Administration.

### Create a new trigger (event)

In this example, we will name it ExampleEvent to some actions related to customers when dispatching this event. It will be placed in the directory `<plugin root>/src/Core/Checkout/Customer/Event`. Our new event has to implement Shopware\Core\Framework\Event\CustomerAware interface to enable actions requiring this Aware.

Currently, you will need to also implement `Shopware\Core\Framework\Event\BusinessEventInterface;` in case the feature flag `FEATURE_NEXT_17858` is inactive. Please take note that this interface will be removed in `v6.5` .

Below you can find an example implementation:

```php
// <plugin root>/src/Core/Checkout/Customer/Event/ExampleEvent.php
<?php declare(strict_types=1);

namespace Swag\ExamplePlugin\Core\Checkout\Customer\Event;

use Shopware\Core\Checkout\Customer\CustomerDefinition;
use Shopware\Core\Checkout\Customer\CustomerEntity;
use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\Event\CustomerAware;
use Shopware\Core\Framework\Event\BusinessEventInterface;
use Shopware\Core\Framework\Event\EventData\EntityType;
use Shopware\Core\Framework\Event\EventData\EventDataCollection;
use Symfony\Contracts\EventDispatcher\Event;

class ExampleEvent extends Event implements CustomerAware, BusinessEventInterface
{
    public const EVENT_NAME = 'example.event';

    private CustomerEntity $customer;

    private Context $context;

    public function __construct(Context $context, CustomerEntity $customer)
    {
        $this->customer = $customer;
        $this->context = $context;
    }

    public function getName(): string
    {
        return self::EVENT_NAME;
    }

    public function getCustomer(): CustomerEntity
    {
        return $this->customer;
    }

    public function getCustomerId(): string
    {
        return $this->customer->getId();
    }

    public static function getAvailableData(): EventDataCollection
    {
        return (new EventDataCollection())
            ->add('customer', new EntityType(CustomerDefinition::class));
    }

    public function getContext(): Context
    {
        return $this->context;
    }
}
```

::: info
Available starting with Shopware 6.5.0.0
:::

From 6.5, in Flow Builder, the original event will be deprecated and we will only use a class `StorableFlow`. All event data will be stored in the `StorableFlow`, hence the `getAvailableData` function can no more be used to get data from the Flow Builder.

We have created many Aware interfaces. These Aware are the conditions to restore event data in Flow Builder via `FlowStorer` respective.

| Aware interface | Storer respective |
| :--- | :--- |
| Shopware\Core\Content\Flow\Dispatching\Aware\ScalarValuesAware | Shopware\Core\Content\Flow\Dispatching\Storer\ScalarValuesStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\ConfirmUrlAware | Shopware\Core\Content\Flow\Dispatching\Storer\ConfirmUrlStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\ContactFormDataAware | Shopware\Core\Content\Flow\Dispatching\Storer\ContactFormDataStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\ContentsAware | Shopware\Core\Content\Flow\Dispatching\Storer\ContentsStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\ContextTokenAware | Shopware\Core\Content\Flow\Dispatching\Storer\ContextTokenStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\CustomerGroupAware | Shopware\Core\Content\Flow\Dispatching\Storer\CustomerGroupStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\CustomerRecoveryAware | Shopware\Core\Content\Flow\Dispatching\Storer\CustomerRecoveryStorer |
| Shopware\Core\Framework\Event\CustomerAware | Shopware\Core\Content\Flow\Dispatching\Storer\CustomerStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\DataAware | Shopware\Core\Content\Flow\Dispatching\Storer\DataStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\EmailAware | Shopware\Core\Content\Flow\Dispatching\Storer\EmailStorer |
| Shopware\Core\Framework\Event\MailAware | Shopware\Core\Content\Flow\Dispatching\Storer\MailStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\MessageAware | Shopware\Core\Content\Flow\Dispatching\Storer\MessageStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\NameAware | Shopware\Core\Content\Flow\Dispatching\Storer\NameStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\NewsletterRecipientAware | Shopware\Core\Content\Flow\Dispatching\Storer\NewsletterRecipientStorer |
| Shopware\Core\Framework\Event\OrderAware | Shopware\Core\Content\Flow\Dispatching\Storer\OrderStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\OrderTransactionAware | Shopware\Core\Content\Flow\Dispatching\Storer\OrderTransactionStorer |
| Shopware\Core\Framework\Event\ProductAware | Shopware\Core\Content\Flow\Dispatching\Storer\ProductStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\RecipientsAware | Shopware\Core\Content\Flow\Dispatching\Storer\RecipientsStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\ResetUrlAware | Shopware\Core\Content\Flow\Dispatching\Storer\ResetUrlStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\ReviewFormDataAware | Shopware\Core\Content\Flow\Dispatching\Storer\ReviewFormDataStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\ShopNameAware | Shopware\Core\Content\Flow\Dispatching\Storer\ShopNameStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\SubjectAware | Shopware\Core\Content\Flow\Dispatching\Storer\SubjectStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\TemplateDataAware | Shopware\Core\Content\Flow\Dispatching\Storer\TemplateDataStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\UrlAware | Shopware\Core\Content\Flow\Dispatching\Storer\UrlStorer |
| Shopware\Core\Framework\Event\UserAware | Shopware\Core\Content\Flow\Dispatching\Storer\UserStorer |

```php
<?php declare(strict_types=1);

namespace Swag\ExamplePlugin\Core\Checkout\Customer\Event;

use Shopware\Core\Checkout\Customer\CustomerEntity;
use Shopware\Core\Framework\Event\CustomerAware;
use Shopware\Core\Framework\Event\ShopNameAware;
use Shopware\Core\Framework\Event\EventData\EventDataCollection;
use Symfony\Contracts\EventDispatcher\Event;

class ExampleEvent extends Event implements CustomerAware, ShopNameAware
{
    public const EVENT_NAME = 'example.event';

    private CustomerEntity $customer;

    public function __construct(CustomerEntity $customer, string $shopName)
    {
        $this->customer = $customer;
        $this->shopName = $shopName;
    }

    public function getName(): string
    {
        return self::EVENT_NAME;
    }

    public function getCustomerId(): string
    {
        return $this->customer->getId();
    }

    public static function getAvailableData(): EventDataCollection
    {
        return (new EventDataCollection());
    }

    public function getShopName(): string
    {
        return $this->shopName;
    }
}
```

In the example above, to get the `customerId` and `shopName` data events, you need to store these data via `CustomerStorer` and `ShopNameStorer`.

```php
class CustomerStorer extends FlowStorer
{
	public function store(FlowEventAware $event, array $stored): array
	{
    		if (!$event instanceof CustomerAware || isset($stored['customerId'])) {
        		return $stored;
    		}

    		$stored['customerId'] = $event->getCustomerId();

    		return $stored;
	}

	public function restore(StorableFlow $storable): void
	{
    		if (!$storable->hasStore('customerId')) {
        		return;
    		}

   		$storable->setData('customer', $this->getCustomer($storable->getStore('customerId')));
	}

	private function getCustomer(string $customerId): Customer
	{
		// load customer via $customerId
		
		return $customer;
	}
}
```

```php
class ShopNameStorer extends FlowStorer
{
    public function store(FlowEventAware $event, array $stored): array
    {
        if (!$event instanceof ShopNameAware || isset($stored['shopName'])) {
            return $stored;
        }

        $stored['shopName'] = $event->getShopName();

        return $stored;
    }

    public function restore(StorableFlow $storable): void
    {
        if (!$storable->hasStore('shopName')) {
            return;
        }

        $storable->setData('shopName', $storable->getStore('shopName'));
    }
}
```

We already have Aware interfaces, but if you want to use the custom data that is not available, you can define a new Aware interface and a Storer respectively.

```php
<?php declare(strict_types=1);

namespace Swag\ExamplePlugin\Core\Checkout\Customer\Event;

use Shopware\Core\Framework\Event\CustomExampleDataAware;
use Shopware\Core\Framework\Event\EventData\EventDataCollection;
use Symfony\Contracts\EventDispatcher\Event;

class ExampleEvent extends Event implements CustomExampleDataAware
{
    public const EVENT_NAME = 'example.event';

    private string $customExampleData;

    public function __construct(string $customExampleData)
    {
        $this->customExampleData = $customExampleData;
    }

    public function getName(): string
    {
        return self::EVENT_NAME;
    }

    public function getCustomExampleData(): string
    {
        return $this->customExampleData;
    }

    public static function getAvailableData(): EventDataCollection
    {
        return (new EventDataCollection());
    }
}
```

Aware:

```php
interface CustomExampleDataAware extends FlowEventAware
{
    public const CUSTOM_EXAMPLE_DATA = 'customExampleData';

    public function getCustomExampleData(): string;
}
```

Storer respective:

```php
class CustomExampleDataStorer extends FlowStorer
{
    public function store(FlowEventAware $event, array $stored): array
    {
        if (!$event instanceof CustomExampleDataAware || isset($stored[CustomExampleDataAware::CUSTOM_EXAMPLE_DATA])) {
            return $stored;
        }

        $stored[CustomExampleDataAware::CUSTOM_EXAMPLE_DATA] = $event->getCustomExampleData();

        return $stored;
    }

    public function restore(StorableFlow $storable): void
    {
        if (!$storable->hasStore(CustomExampleDataAware::CUSTOM_EXAMPLE_DATA)) {
            return;
        }

        $storable->setData(CustomExampleDataAware::CUSTOM_EXAMPLE_DATA, $storable->getStore(CustomExampleDataAware::CUSTOM_EXAMPLE_DATA));
    }
}
```

In Flow Actions, you can get the data easily via `getStore` and `getData`.

```php
class SendMailAction
{
	public function handleFlow(StorableFlow $flow)
	{
		$shopName = $flow->getStore('shopName');
		$customer = $flow->getData('customer');
		$customExampleData = $flow->getData('customExampleData');
	}
}
```

You also need to register this action as a service in the container. Make sure to define a tag `<tag name="flow.storer" priority="600">` at `<plugin root>/src/Resources/config/services.xml`. This tag will ensure that your storer is included in the flow trigger process.

```xml
// <plugin root>/src/Resources/config/services.xml
<service id="Swag\ExamplePlugin\Core\Content\Flow\Dispatching\Storer\CustomExampleDataStorer">
    <argument type="service" id="tag.repository" />
    <tag name="flow.storer"/>
</service>
```

Take a look at the [Add Flow Builder Action](../../../../../guides/plugins/plugins/framework/flow/add-flow-builder-action.md) section of the guide for how to use data in Flow Actions.

### Add your new event to the flow trigger list

At this step, you need to add your new event to the flow trigger list, let us see the code below:

```php
// <plugin root>/src/Core/Checkout/Customer/Subscriber/BusinessEventCollectorSubscriber.php
<?php declare(strict_types=1);

namespace Swag\ExamplePlugin\Core\Checkout\Customer\Subscriber;

use Shopware\Core\Framework\Event\BusinessEventCollector;
use Shopware\Core\Framework\Event\BusinessEventCollectorEvent;
use Swag\ExamplePlugin\Core\Checkout\Customer\Event\ExampleEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class BusinessEventCollectorSubscriber implements EventSubscriberInterface
{
    private BusinessEventCollector $businessEventCollector;

    public function __construct(BusinessEventCollector $businessEventCollector) {
        $this->businessEventCollector = $businessEventCollector;
    }

    public static function getSubscribedEvents()
    {
        return [
            BusinessEventCollectorEvent::NAME => ['onAddExampleEvent', 1000],
        ];
    }

    public function onAddExampleEvent(BusinessEventCollectorEvent $event): void
    {
        $collection = $event->getCollection();

        $definition = $this->businessEventCollector->define(ExampleEvent::class);

        if (!$definition) {
            return;
        }

        $collection->set($definition->getName(), $definition);
    }
}
```

Please note that your subscriber has to have a higher priority point to ensure your event is added before any subscriber `BusinessEventCollectorEvent` to prevent missing awareness or action. I set 1000 for `onAddExampleEvent` action:

```php
// <plugin root>/src/Core/Checkout/Customer/Subscriber/BusinessEventCollectorSubscriber.php
public static function getSubscribedEvents()
{
   return [
      BusinessEventCollectorEvent::NAME => ['onAddExampleEvent', 1000],
   ];
}
```

And remember to register your subscriber to the container at `<plugin root>/src/Resources/config/services.xml`

```xml
// <plugin root>/src/Resources/config/services.xml
<service id="Swag\ExamplePlugin\Core\Checkout\Customer\Subscriber\BusinessEventCollectorSubscriber">
    <argument type="service" id="Shopware\Core\Framework\Event\BusinessEventCollector"/>
    <tag name="kernel.event_subscriber"/>
</service>
```

Well done, you have successfully created your own flow trigger.

### Let's check the result

Go to Administration page -> Settings -> Flow Builder, then click Add flow to create a new flow, search for Example Event. You could see your event is available and having actions related to the Customer likes to Add tag, Remove tag, etc...

![Flow Builder Action Example](../../../../../assets/flow-builder-action.png)

---

---
url: >-
  /docs/v6.6/guides/plugins/apps/flow-builder/add-custom-flow-triggers-from-app-system.md
---

# Add custom flow trigger

::: info
The Shopware app custom flow triggers are only accessible from 6.5.3.0 and later versions.
:::

In addition to the default triggers, you have the option to incorporate custom, pre-defined, and adjustable triggers into the flow builder.

![Custom flow trigger in Administration](../../../../assets/flow-builder-custom-trigger-preview.png)

After reading, you will be able to :

* Create the basic setup of an app.
* Create custom triggers for the flow builder.
* Use an API to interact with custom triggers.

## Prerequisites

Please ensure you have a working Shopware 6 store (either cloud or self-hosted). Prior knowledge about the Flow Builder feature of Shopware 6 is useful.

Please see the [Flow Builder Concept](../../../../concepts/framework/flow-concept) for more information.

## Create the app wrapper

To get started with your app, create an `apps` folder inside the `custom` folder of your Shopware dev installation. Next, create another directory inside for your application and provide a `manifest.xml` file following the structure below:

```text
└── custom
    ├── apps
    │   └── FlowBuilderTriggerApp
    │       └── Resources
    │           └── app
    │               └── administration
    │                   └── snippet
    │                       └── de-DE.json
    │                       └── en-GB.json
    │           └── flow.xml
    │       └── manifest.xml
    └── plugins
```

| File name             | Description                                        |
|:----------------------|:---------------------------------------------------|
| FlowBuilderTriggerApp | Your app's technical name                          |
| flow.xml              | Place to define your new triggers                  |
| de-DE.json            | Snippet to translate your trigger name for Deutsch |
| en-GB.json            | Snippet to translate your trigger name for English |
| manifest.xml          | Base information about your app                    |

### Manifest file

The manifest file is the central point of your app. It defines the interface between your app and the Shopware instance. It provides all the information concerning your app, as seen in the minimal version below:

::: code-group

```xml [manifest.xml]
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        <name>FlowBuilderTriggerApp</name>
        <label>Flow Builder Trigger App</label>
        <label lang="de-DE">Flow Builder Abzug-App</label>
        <description>This is the example description for app</description>
        <description lang="de-DE">Dies ist die Beispielbeschreibung für app</description>
        <author>shopware AG</author>
        <copyright>(c) shopware AG</copyright>
        <version>4.14.0</version>
        <icon>Resources/app-icon.png</icon>
        <license>MIT</license>
    </meta>
</manifest>
```

:::

::: warning
The name of your app that you provide in the manifest file needs to match the folder name of your app.
:::

## Define the flow trigger

To create a flow trigger, you need to define a `<flow-event>` block within a file called `flow.xml`. Each `<flow-event>` represents one trigger, and you can define an arbitrary number of events.

::: code-group

```xml [Resources/flow.xml]
<flow-extensions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Flow/Schema/flow-1.0.xsd">
    <flow-events>
        <flow-event>
            ... # The first trigger
        </flow-event>
        <flow-event>
            ... # The second trigger
        </flow-event>
    </flow-events>
    ...
</flow-extensions>
```

:::

A single flow trigger would look like this:

```xml
<flow-event>
    <name>swag.before.open_the_doors</name>
    <aware>orderAware</aware>
</flow-event>
```

| Key          | Required | Description                                                 |
|:-------------|:---------|:------------------------------------------------------------|
| name         | yes      | The technical name of your trigger, unique for all actions. |
| aware        | no       | Filter actions for your trigger, read more below.           |

**aware**

The `aware` will decide which actions are available for your trigger.

***Example***

If you define the `orderAware` in your trigger config `<aware>orderAware</aware>`, the actions related to the Order will be available when the trigger is selected.

* action.add.order.tag,
* action.remove.order.tag,
* action.generate.document,
* action.grant.download.access,
* action.set.order.state,
* action.add.order.affiliate.and.campaign.code,
* action.set.order.custom.field,
* action.stop.flow

If you define the `customerAware` in your trigger config `<aware>orderAware</aware>`, the actions related to Customer will be available when the trigger is selected.

* action.add.customer.tag
* action.remove.customer.tag
* action.change.customer.group
* action.change.customer.status
* action.set.customer.custom.field
* action.add.customer.affiliate.and.campaign.code
* action.stop.flow

Each value defined, it represents one of the `aware` interfaces from the `core`.

To fulfill the `aware`, refer to a subset of action triggers aware:

| Value              | Interface                                        |
|:-------------------|:-------------------------------------------------|
| customerAware      | Shopware\Core\Framework\Event\CustomerAware      |
| customerGroupAware | Shopware\Core\Framework\Event\CustomerGroupAware |
| delayAware         | Shopware\Core\Framework\Event\DelayAware         |
| mailAware          | Shopware\Core\Framework\Event\MailAware          |
| orderAware         | Shopware\Core\Framework\Event\OrderAware         |
| salesChannelAware  | Shopware\Core\Framework\Event\SalesChannelAware  |
| userAware          | Shopware\Core\Framework\Event\UserAware          |

Please refer to the [Schema definition for flow events (GitHub)](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/App/Flow/Schema/flow-1.0.xsd) for more information.

## Trigger API

We provided an API with the endpoint `POST: /api/_action/trigger-event/{eventName}` to dispatch the custom trigger when you call the API.
The app calls the API to trigger the custom event and can provide the data. The API will create a CustomAppEvent object and dispatch it with the data provided.
The data given will be saved through `StorableFlow`. This can be utilized for actions or email templates.

Here is an example to define data from the API:

```json
    {
        "customerId": "d20e4d60e35e4afdb795c767eee08fec",
        "salesChannelId": "55cb094fd1794d489c63975a6b4b5b90",
        "shopName": "Shopware's Shop",
        "url": "https://shopware.com" 
    }
```

Flow actions can retrieve the data from FlowStorer.

```php
    $salesChanelId = $flow->getData(MailAware::SALES_CHANNEL_ID));
    $customer = $flow->getData(CustomerAware::CUSTOMER_ID));
```

Or we can use the data when defining the email template.

```html
    <h3>Welcome to {{ shopName }}</h3>
    <h1>Visit us at: {{ url }} </h1>
```

Please see the [StorableFlow Concept](../../../../resources/references/adr/2022-07-21-adding-the-storable-flow-to-implement-delay-action-in-flow-builder) for more information.

## Snippet for translation

You can define snippets to translate your custom trigger to show the trigger tree and flow list. Refer to the [Adding snippets](../../plugins/administration/adding-snippets) guide for more information.

Snippet keys should be defined based on your trigger name defined at `<name>` in your `flow.xml`.

| Fixed key            | Description                                                          |
|:---------------------|:---------------------------------------------------------------------|
| sw-flow-custom-event | All the keys related to the custom trigger will be defined inside    |
| event-tree           | All the keys used to trigger the tree will be defined inside         |
| flow-list            | All the keys used to flow list will be defined inside                |

***Example***

```xml
// Resources/flow.xml
<flow-extensions xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Flow/Schema/flow-1.0.xsd">
    <flow-events>
        <flow-event>
            <name>swag.before.open_the_doors</name>
            ...
        </flow-event>
    </flow-events>
</flow-extensions>
```

```javascript
// custom/apps/FlowBuilderTriggerApp/Resources/app/administration/snippet/en-GB.json
{
  "sw-flow-custom-event": {
    "event-tree": {
      "swag": "Swag",
      "before": "Before",
      "openTheDoors": "Open the doors"
    },
    "flow-list": {
      "swag_before_open_the_doors": "Before open the doors"
    }
  }
}
```

## Install the App

The app can now be installed by running the following command:

```bash
bin/console app:install --activate FlowBuilderTriggerApp
```

---

---
url: /docs/v6.6/guides/plugins/plugins/framework/flow/add-flow-builder-trigger.md
---

# Add custom flow trigger

::: info
This functionality is available starting with Shopware 6.4.6.0
:::

## Overview

In this guide, you'll learn how to create a custom flow trigger in Shopware. Triggers are used by the flow builder. This example will introduce a new custom trigger. The shop owner is then able to define what to do with the new trigger.

## Prerequisites

In order to add your own custom flow trigger for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../../plugin-base-guide).

You also should be familiar with [Add custom event](../event/add-custom-event) to know how to create an event. Please refer to the [Flow Builder concept](../../../../../concepts/framework/flow-concept)
for better integration later.

## Existing triggers and actions

You can refer to the [Flow reference](../../../../../resources/references/core-reference/flow-reference) to read triggers and actions detail.

## Event interfaces and classes

Any event that implements one of these interfaces will be available in the trigger list of the Flow Builder module in Administration. Besides, the event will have the ability to execute the action that belongs to the interface.

* `FlowEventAware`: This interface is the base for every flow builder trigger. It provides the `availableData` and `name` of the event.

* `MailAware`: This interface provides `MailRecipientStruct` and `salesChannelId`.

* `OrderAware`: This interface provides `orderId`, which is used to add tags, sendmail or generate documents, etc...

* `CustomerAware`: This interface same as `OrderAware` but for customer, which provide `customerId`, used to add tags, remove tags, sendmail, etc...

* `UserAware`: This interface provides `userId` for all actions related to the user.

* `SalesChannelAware`: This interface simply provides `salesChannelId`.

## Create custom flow trigger

To create a custom flow trigger, firstly you have to create a plugin and install it, you can refer to the [Plugin Base Guide](../../plugin-base-guide) to do it. I will create a plugin named `ExamplePlugin`. There will be an example to actually show your new trigger in the Administration.

### Create a new trigger (event)

In this example, we will name it ExampleEvent to some actions related to customers when dispatching this event. It will be placed in the directory `<plugin root>/src/Core/Checkout/Customer/Event`. Our new event has to implement Shopware\Core\Framework\Event\CustomerAware interface to enable actions requiring this Aware.

Below you can find an example implementation:

```php
// <plugin root>/src/Core/Checkout/Customer/Event/ExampleEvent.php
<?php declare(strict_types=1);

namespace Swag\ExamplePlugin\Core\Checkout\Customer\Event;

use Shopware\Core\Checkout\Customer\CustomerDefinition;
use Shopware\Core\Checkout\Customer\CustomerEntity;
use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\Event\CustomerAware;
use Shopware\Core\Framework\Event\FlowEventAware;
use Shopware\Core\Framework\Event\EventData\EntityType;
use Shopware\Core\Framework\Event\EventData\EventDataCollection;
use Symfony\Contracts\EventDispatcher\Event;

class ExampleEvent extends Event implements CustomerAware, FlowEventAware
{
    public const EVENT_NAME = 'example.event';

    private CustomerEntity $customer;

    private Context $context;

    public function __construct(Context $context, CustomerEntity $customer)
    {
        $this->customer = $customer;
        $this->context = $context;
    }

    public function getName(): string
    {
        return self::EVENT_NAME;
    }

    public function getCustomer(): CustomerEntity
    {
        return $this->customer;
    }

    public function getCustomerId(): string
    {
        return $this->customer->getId();
    }

    public static function getAvailableData(): EventDataCollection
    {
        return (new EventDataCollection())
            ->add('customer', new EntityType(CustomerDefinition::class));
    }

    public function getContext(): Context
    {
        return $this->context;
    }
}
```

::: info
Available starting with Shopware 6.5.0.0
:::

From 6.5, in Flow Builder, the original event will be deprecated and we will only use a class `StorableFlow`. All event data will be stored in the `StorableFlow`, hence the `getAvailableData` function can no more be used to get data from the Flow Builder.

We have created many Aware interfaces. These Aware are the conditions to restore event data in Flow Builder via `FlowStorer` respective.

| Aware interface | Storer respective |
| :--- | :--- |
| Shopware\Core\Content\Flow\Dispatching\Aware\ScalarValuesAware | Shopware\Core\Content\Flow\Dispatching\Storer\ScalarValuesStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\ConfirmUrlAware | Shopware\Core\Content\Flow\Dispatching\Storer\ConfirmUrlStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\ContactFormDataAware | Shopware\Core\Content\Flow\Dispatching\Storer\ContactFormDataStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\ContentsAware | Shopware\Core\Content\Flow\Dispatching\Storer\ContentsStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\ContextTokenAware | Shopware\Core\Content\Flow\Dispatching\Storer\ContextTokenStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\CustomerGroupAware | Shopware\Core\Content\Flow\Dispatching\Storer\CustomerGroupStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\CustomerRecoveryAware | Shopware\Core\Content\Flow\Dispatching\Storer\CustomerRecoveryStorer |
| Shopware\Core\Framework\Event\CustomerAware | Shopware\Core\Content\Flow\Dispatching\Storer\CustomerStorer |
| Shopware\Core\Framework\Event\MailAware | Shopware\Core\Content\Flow\Dispatching\Storer\MailStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\MessageAware | Shopware\Core\Content\Flow\Dispatching\Storer\MessageStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\NewsletterRecipientAware | Shopware\Core\Content\Flow\Dispatching\Storer\NewsletterRecipientStorer |
| Shopware\Core\Framework\Event\OrderAware | Shopware\Core\Content\Flow\Dispatching\Storer\OrderStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\OrderTransactionAware | Shopware\Core\Content\Flow\Dispatching\Storer\OrderTransactionStorer |
| Shopware\Core\Framework\Event\ProductAware | Shopware\Core\Content\Flow\Dispatching\Storer\ProductStorer |
| Shopware\Core\Framework\Event\UserAware | Shopware\Core\Content\Flow\Dispatching\Storer\UserStorer |

```php
<?php declare(strict_types=1);

namespace Swag\ExamplePlugin\Core\Checkout\Customer\Event;

use Shopware\Core\Checkout\Customer\CustomerEntity;
use Shopware\Core\Framework\Event\CustomerAware;
use Shopware\Core\Framework\Event\ShopNameAware;
use Shopware\Core\Framework\Event\EventData\EventDataCollection;
use Symfony\Contracts\EventDispatcher\Event;

class ExampleEvent extends Event implements CustomerAware, ShopNameAware
{
    public const EVENT_NAME = 'example.event';

    private CustomerEntity $customer;

    public function __construct(CustomerEntity $customer, string $shopName)
    {
        $this->customer = $customer;
        $this->shopName = $shopName;
    }

    public function getName(): string
    {
        return self::EVENT_NAME;
    }

    public function getCustomerId(): string
    {
        return $this->customer->getId();
    }

    public static function getAvailableData(): EventDataCollection
    {
        return (new EventDataCollection());
    }

    public function getShopName(): string
    {
        return $this->shopName;
    }
}
```

In the example above, to get the `customerId` and `shopName` data events, you need to store these data via `CustomerStorer` and `ShopNameStorer`.

```php
class CustomerStorer extends FlowStorer
{
	public function store(FlowEventAware $event, array $stored): array
	{
    		if (!$event instanceof CustomerAware || isset($stored['customerId'])) {
        		return $stored;
    		}

    		$stored['customerId'] = $event->getCustomerId();

    		return $stored;
	}

	public function restore(StorableFlow $storable): void
	{
    		if (!$storable->hasStore('customerId')) {
        		return;
    		}

   		$storable->setData('customer', $this->getCustomer($storable->getStore('customerId')));
	}

	private function getCustomer(string $customerId): Customer
	{
		// load customer via $customerId
		
		return $customer;
	}
}
```

```php
class ShopNameStorer extends FlowStorer
{
    public function store(FlowEventAware $event, array $stored): array
    {
        if (!$event instanceof ShopNameAware || isset($stored['shopName'])) {
            return $stored;
        }

        $stored['shopName'] = $event->getShopName();

        return $stored;
    }

    public function restore(StorableFlow $storable): void
    {
        if (!$storable->hasStore('shopName')) {
            return;
        }

        $storable->setData('shopName', $storable->getStore('shopName'));
    }
}
```

We already have Aware interfaces, but if you want to use the custom data that is not available, you can define a new Aware interface and a Storer respectively.

```php
<?php declare(strict_types=1);

namespace Swag\ExamplePlugin\Core\Checkout\Customer\Event;

use Shopware\Core\Framework\Event\CustomExampleDataAware;
use Shopware\Core\Framework\Event\EventData\EventDataCollection;
use Symfony\Contracts\EventDispatcher\Event;

class ExampleEvent extends Event implements CustomExampleDataAware
{
    public const EVENT_NAME = 'example.event';

    private string $customExampleData;

    public function __construct(string $customExampleData)
    {
        $this->customExampleData = $customExampleData;
    }

    public function getName(): string
    {
        return self::EVENT_NAME;
    }

    public function getCustomExampleData(): string
    {
        return $this->customExampleData;
    }

    public static function getAvailableData(): EventDataCollection
    {
        return (new EventDataCollection());
    }
}
```

Aware:

```php
#[IsFlowEventAware]
interface CustomExampleDataAware extends FlowEventAware
{
    public const CUSTOM_EXAMPLE_DATA = 'customExampleData';

    public function getCustomExampleData(): string;
}
```

Storer respective:

```php
class CustomExampleDataStorer extends FlowStorer
{
    public function store(FlowEventAware $event, array $stored): array
    {
        if (!$event instanceof CustomExampleDataAware || isset($stored[CustomExampleDataAware::CUSTOM_EXAMPLE_DATA])) {
            return $stored;
        }

        $stored[CustomExampleDataAware::CUSTOM_EXAMPLE_DATA] = $event->getCustomExampleData();

        return $stored;
    }

    public function restore(StorableFlow $storable): void
    {
        if (!$storable->hasStore(CustomExampleDataAware::CUSTOM_EXAMPLE_DATA)) {
            return;
        }

        $storable->setData(CustomExampleDataAware::CUSTOM_EXAMPLE_DATA, $storable->getStore(CustomExampleDataAware::CUSTOM_EXAMPLE_DATA));
    }
}
```

In Flow Actions, you can get the data easily via `getStore` and `getData`.

```php
class SendMailAction
{
	public function handleFlow(StorableFlow $flow)
	{
		$shopName = $flow->getStore('shopName');
		$customer = $flow->getData('customer');
		$customExampleData = $flow->getData('customExampleData');
	}
}
```

Take a look at the [Add Flow Builder Action](../../../../../guides/plugins/plugins/framework/flow/add-flow-builder-action.md) section of the guide for how to use data in Flow Actions.

### Add your new event to the flow trigger list

At this step, you need to add your new event to the flow trigger list, let us see the code below:

```php
// <plugin root>/src/Core/Checkout/Customer/Subscriber/BusinessEventCollectorSubscriber.php
<?php declare(strict_types=1);

namespace Swag\ExamplePlugin\Core\Checkout\Customer\Subscriber;

use Shopware\Core\Framework\Event\BusinessEventCollector;
use Shopware\Core\Framework\Event\BusinessEventCollectorEvent;
use Swag\ExamplePlugin\Core\Checkout\Customer\Event\ExampleEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class BusinessEventCollectorSubscriber implements EventSubscriberInterface
{
    private BusinessEventCollector $businessEventCollector;

    public function __construct(BusinessEventCollector $businessEventCollector) {
        $this->businessEventCollector = $businessEventCollector;
    }

    public static function getSubscribedEvents()
    {
        return [
            BusinessEventCollectorEvent::NAME => ['onAddExampleEvent', 1000],
        ];
    }

    public function onAddExampleEvent(BusinessEventCollectorEvent $event): void
    {
        $collection = $event->getCollection();

        $definition = $this->businessEventCollector->define(ExampleEvent::class);

        if (!$definition) {
            return;
        }

        $collection->set($definition->getName(), $definition);
    }
}
```

Please note that your subscriber has to have a higher priority point to ensure your event is added before any subscriber `BusinessEventCollectorEvent` to prevent missing awareness or action. I set 1000 for `onAddExampleEvent` action:

```php
// <plugin root>/src/Core/Checkout/Customer/Subscriber/BusinessEventCollectorSubscriber.php
public static function getSubscribedEvents()
{
   return [
      BusinessEventCollectorEvent::NAME => ['onAddExampleEvent', 1000],
   ];
}
```

And remember to register your subscriber to the container at `<plugin root>/src/Resources/config/services.xml`

```xml
// <plugin root>/src/Resources/config/services.xml
<service id="Swag\ExamplePlugin\Core\Checkout\Customer\Subscriber\BusinessEventCollectorSubscriber">
    <argument type="service" id="Shopware\Core\Framework\Event\BusinessEventCollector"/>
    <tag name="kernel.event_subscriber"/>
</service>
```

Well done, you have successfully created your own flow trigger.

### Let's check the result

Go to Administration page -> Settings -> Flow Builder, then click Add flow to create a new flow, search for Example Event. You could see your event is available and having actions related to the Customer likes to Add tag, Remove tag, etc...

![Flow Builder Action Example](../../../../../assets/flow-builder-action.png)

---

---
url: /docs/guides/plugins/plugins/framework/flow/add-flow-builder-trigger.md
---

# Add Custom Flow Trigger

::: info
This functionality is available starting with Shopware 6.4.6.0
:::

## Overview

In this guide, you'll learn how to create a custom flow trigger in Shopware. Triggers are used by the flow builder. This example will introduce a new custom trigger. The shop owner is then able to define what to do with the new trigger.

## Prerequisites

In order to add your own custom flow trigger for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../../plugin-base-guide.md).

You also should be familiar with [Add custom event](../event/add-custom-event.md) to know how to create an event. Please refer to the [Flow Builder concept](../../../../../concepts/framework/flow-concept.md) for better integration later.

## Existing triggers and actions

Refer to the [Flow reference](../../../../development/troubleshooting/flow-reference.md) to read triggers and actions details.

## Event interfaces and classes

Any event that implements one of these interfaces will be available in the trigger list of the Flow Builder module in Administration. Besides, the event will have the ability to execute the action that belongs to the interface.

* `FlowEventAware`: This interface is the base for every flow builder trigger. It provides the `availableData` and `name` of the event.

* `MailAware`: This interface provides `MailRecipientStruct` and `salesChannelId`.

* `OrderAware`: This interface provides `orderId`, which is used to add tags, sendmail or generate documents, etc...

* `CustomerAware`: This interface same as `OrderAware` but for customer, which provide `customerId`, used to add tags, remove tags, sendmail, etc...

* `UserAware`: This interface provides `userId` for all actions related to the user.

* `SalesChannelAware`: This interface simply provides `salesChannelId`.

## Create custom flow trigger

To create a custom flow trigger, firstly you have to create a plugin and install it, you can refer to the [Plugin Base Guide](../../plugin-base-guide.md) to do it. I will create a plugin named `ExamplePlugin`. There will be an example to actually show your new trigger in the Administration.

### Create a new trigger (event)

In this example, we will name it ExampleEvent to some actions related to customers when dispatching this event. It will be placed in the directory `<plugin root>/src/Core/Checkout/Customer/Event`. Our new event has to implement Shopware\Core\Framework\Event\CustomerAware interface to enable actions requiring this Aware.

Below you can find an example implementation:

```php
// <plugin root>/src/Core/Checkout/Customer/Event/ExampleEvent.php
<?php declare(strict_types=1);

namespace Swag\ExamplePlugin\Core\Checkout\Customer\Event;

use Shopware\Core\Checkout\Customer\CustomerDefinition;
use Shopware\Core\Checkout\Customer\CustomerEntity;
use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\Event\CustomerAware;
use Shopware\Core\Framework\Event\FlowEventAware;
use Shopware\Core\Framework\Event\EventData\EntityType;
use Shopware\Core\Framework\Event\EventData\EventDataCollection;
use Symfony\Contracts\EventDispatcher\Event;

class ExampleEvent extends Event implements CustomerAware, FlowEventAware
{
    public const EVENT_NAME = 'example.event';

    private CustomerEntity $customer;

    private Context $context;

    public function __construct(Context $context, CustomerEntity $customer)
    {
        $this->customer = $customer;
        $this->context = $context;
    }

    public function getName(): string
    {
        return self::EVENT_NAME;
    }

    public function getCustomer(): CustomerEntity
    {
        return $this->customer;
    }

    public function getCustomerId(): string
    {
        return $this->customer->getId();
    }

    public static function getAvailableData(): EventDataCollection
    {
        return (new EventDataCollection())
            ->add('customer', new EntityType(CustomerDefinition::class));
    }

    public function getContext(): Context
    {
        return $this->context;
    }
}
```

::: info
Available starting with Shopware 6.5.0.0
:::

From 6.5, in Flow Builder, the original event will be deprecated and we will only use a class `StorableFlow`. All event data will be stored in the `StorableFlow`, hence the `getAvailableData` function can no more be used to get data from the Flow Builder.

We have created many Aware interfaces. These Aware are the conditions to restore event data in Flow Builder via `FlowStorer` respective.

You could read here more about the [Storer](../../../../../concepts/framework/flow-concept.md#storer-concept) concept.

| Aware interface | Storer respective |
| :--- | :--- |
| Shopware\Core\Content\Flow\Dispatching\Aware\ScalarValuesAware | Shopware\Core\Content\Flow\Dispatching\Storer\ScalarValuesStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\ConfirmUrlAware | Shopware\Core\Content\Flow\Dispatching\Storer\ConfirmUrlStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\ContactFormDataAware | Shopware\Core\Content\Flow\Dispatching\Storer\ContactFormDataStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\ContentsAware | Shopware\Core\Content\Flow\Dispatching\Storer\ContentsStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\ContextTokenAware | Shopware\Core\Content\Flow\Dispatching\Storer\ContextTokenStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\CustomerGroupAware | Shopware\Core\Content\Flow\Dispatching\Storer\CustomerGroupStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\CustomerRecoveryAware | Shopware\Core\Content\Flow\Dispatching\Storer\CustomerRecoveryStorer |
| Shopware\Core\Framework\Event\CustomerAware | Shopware\Core\Content\Flow\Dispatching\Storer\CustomerStorer |
| Shopware\Core\Framework\Event\MailAware | Shopware\Core\Content\Flow\Dispatching\Storer\MailStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\MessageAware | Shopware\Core\Content\Flow\Dispatching\Storer\MessageStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\NewsletterRecipientAware | Shopware\Core\Content\Flow\Dispatching\Storer\NewsletterRecipientStorer |
| Shopware\Core\Framework\Event\OrderAware | Shopware\Core\Content\Flow\Dispatching\Storer\OrderStorer |
| Shopware\Core\Content\Flow\Dispatching\Aware\OrderTransactionAware | Shopware\Core\Content\Flow\Dispatching\Storer\OrderTransactionStorer |
| Shopware\Core\Framework\Event\ProductAware | Shopware\Core\Content\Flow\Dispatching\Storer\ProductStorer |
| Shopware\Core\Framework\Event\UserAware | Shopware\Core\Content\Flow\Dispatching\Storer\UserStorer |

```php
<?php declare(strict_types=1);

namespace Swag\ExamplePlugin\Core\Checkout\Customer\Event;

use Shopware\Core\Checkout\Customer\CustomerEntity;
use Shopware\Core\Framework\Event\CustomerAware;
use Shopware\Core\Framework\Event\ShopNameAware;
use Shopware\Core\Framework\Event\EventData\EventDataCollection;
use Symfony\Contracts\EventDispatcher\Event;

class ExampleEvent extends Event implements CustomerAware, ShopNameAware
{
    public const EVENT_NAME = 'example.event';

    private CustomerEntity $customer;

    public function __construct(CustomerEntity $customer, string $shopName)
    {
        $this->customer = $customer;
        $this->shopName = $shopName;
    }

    public function getName(): string
    {
        return self::EVENT_NAME;
    }

    public function getCustomerId(): string
    {
        return $this->customer->getId();
    }

    public static function getAvailableData(): EventDataCollection
    {
        return (new EventDataCollection());
    }

    public function getShopName(): string
    {
        return $this->shopName;
    }
}
```

In the example above, to get the `customerId` and `shopName` data events, you need to store these data via `CustomerStorer` and `ShopNameStorer`.

```php
class CustomerStorer extends FlowStorer
{
	public function store(FlowEventAware $event, array $stored): array
	{
    		if (!$event instanceof CustomerAware || isset($stored['customerId'])) {
        		return $stored;
    		}

    		$stored['customerId'] = $event->getCustomerId();

    		return $stored;
	}

	public function restore(StorableFlow $storable): void
	{
    		if (!$storable->hasStore('customerId')) {
        		return;
    		}

   		$storable->setData('customer', $this->getCustomer($storable->getStore('customerId')));
	}

	private function getCustomer(string $customerId): Customer
	{
		// load customer via $customerId

		return $customer;
	}
}
```

```php
class ShopNameStorer extends FlowStorer
{
    public function store(FlowEventAware $event, array $stored): array
    {
        if (!$event instanceof ShopNameAware || isset($stored['shopName'])) {
            return $stored;
        }

        $stored['shopName'] = $event->getShopName();

        return $stored;
    }

    public function restore(StorableFlow $storable): void
    {
        if (!$storable->hasStore('shopName')) {
            return;
        }

        $storable->setData('shopName', $storable->getStore('shopName'));
    }
}
```

We already have Aware interfaces, but if you want to use the custom data that is not available, you can define a new Aware interface and a Storer respectively.

```php
<?php declare(strict_types=1);

namespace Swag\ExamplePlugin\Core\Checkout\Customer\Event;

use Shopware\Core\Framework\Event\CustomExampleDataAware;
use Shopware\Core\Framework\Event\EventData\EventDataCollection;
use Symfony\Contracts\EventDispatcher\Event;

class ExampleEvent extends Event implements CustomExampleDataAware
{
    public const EVENT_NAME = 'example.event';

    private string $customExampleData;

    public function __construct(string $customExampleData)
    {
        $this->customExampleData = $customExampleData;
    }

    public function getName(): string
    {
        return self::EVENT_NAME;
    }

    public function getCustomExampleData(): string
    {
        return $this->customExampleData;
    }

    public static function getAvailableData(): EventDataCollection
    {
        return (new EventDataCollection());
    }
}
```

Aware:

```php
#[IsFlowEventAware]
interface CustomExampleDataAware extends FlowEventAware
{
    public const CUSTOM_EXAMPLE_DATA = 'customExampleData';

    public function getCustomExampleData(): string;
}
```

Storer respective:

```php
class CustomExampleDataStorer extends FlowStorer
{
    public function store(FlowEventAware $event, array $stored): array
    {
        if (!$event instanceof CustomExampleDataAware || isset($stored[CustomExampleDataAware::CUSTOM_EXAMPLE_DATA])) {
            return $stored;
        }

        $stored[CustomExampleDataAware::CUSTOM_EXAMPLE_DATA] = $event->getCustomExampleData();

        return $stored;
    }

    public function restore(StorableFlow $storable): void
    {
        if (!$storable->hasStore(CustomExampleDataAware::CUSTOM_EXAMPLE_DATA)) {
            return;
        }

        $storable->setData(CustomExampleDataAware::CUSTOM_EXAMPLE_DATA, $storable->getStore(CustomExampleDataAware::CUSTOM_EXAMPLE_DATA));
    }
}
```

In Flow Actions, you can get the data easily via `getStore` and `getData`.

```php
class SendMailAction
{
	public function handleFlow(StorableFlow $flow)
	{
		$shopName = $flow->getStore('shopName');
		$customer = $flow->getData('customer');
		$customExampleData = $flow->getData('customExampleData');
	}
}
```

Take a look at the [Add Flow Builder Action](../../../../../guides/plugins/plugins/framework/flow/add-flow-builder-action.md) section of the guide for how to use data in Flow Actions.

### Add your new event to the flow trigger list

At this step, you need to add your new event to the flow trigger list, let us see the code below:

```php
// <plugin root>/src/Core/Checkout/Customer/Subscriber/BusinessEventCollectorSubscriber.php
<?php declare(strict_types=1);

namespace Swag\ExamplePlugin\Core\Checkout\Customer\Subscriber;

use Shopware\Core\Framework\Event\BusinessEventCollector;
use Shopware\Core\Framework\Event\BusinessEventCollectorEvent;
use Swag\ExamplePlugin\Core\Checkout\Customer\Event\ExampleEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class BusinessEventCollectorSubscriber implements EventSubscriberInterface
{
    private BusinessEventCollector $businessEventCollector;

    public function __construct(BusinessEventCollector $businessEventCollector) {
        $this->businessEventCollector = $businessEventCollector;
    }

    public static function getSubscribedEvents()
    {
        return [
            BusinessEventCollectorEvent::NAME => ['onAddExampleEvent', 1000],
        ];
    }

    public function onAddExampleEvent(BusinessEventCollectorEvent $event): void
    {
        $collection = $event->getCollection();

        $definition = $this->businessEventCollector->define(ExampleEvent::class);

        if (!$definition) {
            return;
        }

        $collection->set($definition->getName(), $definition);
    }
}
```

Please note that your subscriber has to have a higher priority point to ensure your event is added before any subscriber `BusinessEventCollectorEvent` to prevent missing awareness or action. I set 1000 for `onAddExampleEvent` action:

```php
// <plugin root>/src/Core/Checkout/Customer/Subscriber/BusinessEventCollectorSubscriber.php
public static function getSubscribedEvents()
{
   return [
      BusinessEventCollectorEvent::NAME => ['onAddExampleEvent', 1000],
   ];
}
```

And remember to register your subscriber to the container at `<plugin root>/src/Resources/config/services.php`

```php
// <plugin root>/src/Resources/config/services.php
$services->set(Swag\ExamplePlugin\Core\Checkout\Customer\Subscriber\BusinessEventCollectorSubscriber::class)
    ->args([service(Shopware\Core\Framework\Event\BusinessEventCollector::class)])
    ->tag('kernel.event_subscriber');
```

Well done, you have successfully created your own flow trigger.

### Let's check the result

Go to Administration page -> Settings -> Flow Builder, then click Add flow to create a new flow, search for Example Event. You could see your event is available and having actions related to the Customer likes to Add tag, Remove tag, etc...

![Flow Builder Action Example](../../../../../assets/flow-builder-action.png)

---

---
url: /docs/guides/plugins/plugins/storefront/styling/add-icons.md
---

# Add Custom Icons

## Overview

In this guide you will learn how to use the icon renderer component as well as adding custom icons.

::: info
This guide also applies to [themes](../../../themes/index.md).
:::

## Prerequisites

In order to follow this guide easily, you first need to have a functioning plugin installed. Head over to our [Plugin base guide](../../plugin-base-guide.md) to create a plugin, if you don't know how it's done yet. Also knowing and understanding SCSS will be quite mandatory to fully understand what's going on here. Furthermore, it might be helpful to read the guide on how to [handle own assets](../styling/add-custom-assets.md) in your plugin before you start with this one.

## Adding icon

In order to add any icons to the Storefront, you use our `sw_icon` twig action. This way, an icon of choice is displayed in the Storefront.

Needless to say, the first step is saving your image somewhere in your plugin where Shopware can find it. The default path for icons is the following:

```text
<YourPlugin>/src/Resources/app/storefront/dist/assets/icon/default
```

You can also provide "solid" icons or any other custom pack names which can be configured later with the `pack` parameter. You can do that by creating a folder with the pack name:

```text
<YourPlugin>/src/Resources/app/storefront/dist/assets/icon/<pack-name>
```

By default, Shopware looks inside the "default" folder.

```twig
{% sw_icon 'done-outline-24px' style {
    'namespace': 'TestPlugin'
} %}
```

::: info
When you want to see all icons available to the Storefront by default, see [here](https://github.com/shopware/shopware/tree/trunk/src/Storefront/Resources/app/storefront/dist/assets/icon). They are available as `default` and `solid` icon pack.
:::

Imagine you want to use the default `checkmark` icon from the `solid` pack. In this case,

You surely want to add your own custom icons. In this case, the `namespace` parameter is the most important one to configure. In there, you need to set the name of the theme in which the icon is searched for by its name.

::: warning
If you configure no deviating namespace, Shopware will display the Storefront's default icons.
:::

However, these are not all of your possibilities of configuration. As you see, you're able to configure even more things. Let's take a look at the `style` object's possible parameters:

| Configuration | Description | Remarks |
| :--- | :--- | :--- |
| `size` | Sets the size of the icon | --- |
| `namespace` | Selection of the namespace of the icon, you can compare it with the source of it | Important configuration if you want to use custom icons. |
| `pack` | Selects the pack of different icons | --- |
| `color` | Sets the color of the icon | --- |
| `class` | Defines a class of the icon | --- |

A simple but fully functional example could look like below:

```twig
{% sw_extends '@Storefront/storefront/base.html.twig' %}

{% block base_body %}

    {# We want to set our own icon here #}
    <h1>Custom icon:</h1>
    {% sw_icon 'done-outline-24px' style {
        'size': 'lg',
        'namespace': 'TestPlugin',
        'pack': 'solid'
    } %}
    {{ parent() }}

{% endblock %}
```

::: danger
Icons or other custom assets are not included in the theme inheritance.
:::

Inside your theme, you cannot put an icon in a directory corresponding the core folder structure and expect the core one to be automatically overwritten by it, as you are used to with themes in general.

---

---
url: /docs/guides/plugins/themes/assets/add-icons.md
---

# Add Custom Icons

## Overview

In this guide, you will learn how to use the icon renderer component as well as adding custom icons.

::: info
Even if this is originally a plugin guide, everything will work perfectly in a theme as well. Actually, a theme even is a kind of plugin. So don't get confused by us talking about plugins here.
:::

## Prerequisites

To follow this guide easily, you first need to have a functioning plugin installed. Head over to our [Plugin base guide](../../plugins/plugin-base-guide.md) to create a plugin, if you don't know how it's done yet. Also, knowing and understanding SCSS will be quite mandatory to fully understand what's going on here. Furthermore, it might be helpful to read the guide on how to [handle own assets](../../plugins/storefront/styling/add-custom-assets.md) in your plugin before you start with this one.

## Adding icon

To add any icons to the Storefront, you use our `sw_icon` twig action. This way, an icon of choice is displayed in the Storefront.

Needless to say, the first step is saving your image somewhere in your plugin where Shopware can find it. The default path for icons is the following:

```text
<YourPlugin>/src/Resources/app/storefront/dist/assets/icon/default
```

You can also provide "solid" icons or any other custom pack names that can be configured later with the `pack` parameter. You can do that by creating a folder with the pack name:

```text
<YourPlugin>/src/Resources/app/storefront/dist/assets/icon/<pack-name>
```

By default, Shopware looks inside the "default" folder.

```twig
{% sw_icon 'done-outline-24px' style {
    'namespace': 'TestPlugin'
} %}
```

::: info
When you want to see all icons available to the storefront by default, see [here](https://github.com/shopware/shopware/tree/trunk/src/Storefront/Resources/app/storefront/dist/assets/icon). They are available as `default` and `solid` icon pack.
:::

Imagine you want to use the default `checkmark` icon from the `solid` pack. In this case,

You surely want to add your own custom icons. In this case, the `namespace` parameter is the most important one to configure. In there, you need to set the name of the theme in which the icon is searched for by its name.

::: warning
If you configure no deviating namespace, Shopware will display the Storefront's default icons.
:::

However, these are not all of your possibilities of configuration. As you see, you're able to configure even more things. Let's take a look at the `style` object's possible parameters:

| Configuration | Description | Remarks |
| :--- | :--- | :--- |
| `size` | Sets the size of the icon | --- |
| `namespace` | Selection of the namespace of the icon, you can compare it with the source of it | Important configuration if you want to use custom icons. |
| `pack` | Selects the pack of different icons | --- |
| `color` | Sets the color of the icon | You can either use pre-defined variants similar to bootstrap (eg: primary , danger etc) or manually style the icon with any color with CSS. |
| `class` | Defines a class of the icon | --- |

A simple but fully functional example could look like below:

```twig
{% sw_extends '@Storefront/storefront/base.html.twig' %}

{% block base_body %}

    {# We want to set our own icon here #}
    <h1>Custom icon:</h1>
    {% sw_icon 'done-outline-24px' style {
        'size': 'lg',
        'namespace': 'TestPlugin',
        'pack': 'solid'
    } %}
    {{ parent() }}

{% endblock %}
```

::: danger
Icons or other custom assets are not included in the theme inheritance.
:::

Inside your theme, you cannot put an icon in a directory corresponding to the core folder structure and expect the core one to be automatically overwritten by it, as you're used to with themes in general.

## Load icons from custom locations

Since Shopware 6.4.1.0 it is possible to define custom locations of your custom icons inside your theme.json file.
You can define the name of the icon pack and the path to those icons under the `iconSets`-key:

```json
{
  /* ... */
  "iconSets": {
    "custom-icons": "app/storefront/src/assets/icon-pack/custom-icons"
  }
}
```

You can use your custom icons by specifying your icon pack:

```twig
{% sw_icon 'done-outline-24px' style {
    'pack': 'custom-icons'
} %}
```

::: warning
This setup is mandatory if you ship your Theme as an App, because otherwise your custom icons can't be loaded.
:::

---

---
url: /docs/v6.5/guides/plugins/plugins/storefront/add-icons.md
---

# Add Custom Icons

## Overview

In this guide you will learn how to use the icon renderer component as well as adding custom icons.

::: info
Even if this is originally a plugin guide, everything will work perfectly in a theme as well. Actually, a theme even is a kind of plugin. So don't get confused by us talking about plugins here.
:::

## Prerequisites

In order to follow this guide easily, you first need to have a functioning plugin installed. Head over to our [Plugin base guide](../plugin-base-guide) to create a plugin, if you don't know how it's done yet. Also knowing and understanding SCSS will be quite mandatory to fully understand what's going on here. Furthermore, it might be helpful to read the guide on how to [handle own assets](add-custom-assets) in your plugin before you start with this one.

## Adding icon

In order to add any icons to the Storefront, you use our `sw_icon` twig action. This way, an icon of choice is displayed in the Storefront.

Needless to say, the first step is saving your image somewhere in your plugin where Shopware can find it. The default path for icons is the following:

```text
<YourPlugin>/src/Resources/app/storefront/dist/assets/icon/default
`
```

You can also provide "solid" icons or any other custom pack names which can be configured later with the `pack` parameter. You can do that by creating a folder with the pack name:

```text
<YourPlugin>/src/Resources/app/storefront/dist/assets/icon/<pack-name>
```

By default, Shopware looks inside the "default" folder.

```twig
{% sw_icon 'done-outline-24px' style {
    'namespace': 'TestPlugin'
} %}
```

::: info
When you want to see all icons available to the Storefront by default, see [here](https://github.com/shopware/shopware/tree/trunk/src/Storefront/Resources/app/storefront/dist/assets/icon). They are available as `default` and `solid` icon pack.
:::

Imagine you want to use the default `checkmark` icon from the `solid` pack. In this case,

You surely want to add your own custom icons. In this case, the `namespace` parameter is the most important one to configure. In there, you need to set the name of the theme in which the icon is searched for by its name.

::: warning
If you configure no deviating namespace, Shopware will display the Storefront's default icons.
:::

However, these are not all of your possibilities of configuration. As you see, you're able to configure even more things. Let's take a look at the `style` object's possible parameters:

| Configuration | Description | Remarks |
| :--- | :--- | :--- |
| `size` | Sets the size of the icon | --- |
| `namespace` | Selection of the namespace of the icon, you can compare it with the source of it | Important configuration if you want to use custom icons. |
| `pack` | Selects the pack of different icons | --- |
| `color` | Sets the color of the icon | --- |
| `class` | Defines a class of the icon | --- |

A simple but fully functional example could look like below:

```twig
{% sw_extends '@Storefront/storefront/base.html.twig' %}

{% block base_body %}

    {# We want to set our own icon here #}
    <h1>Custom icon:</h1>
    {% sw_icon 'done-outline-24px' style {
        'size': 'lg',
        'namespace': 'TestPlugin',
        'pack': 'solid'
    } %}
    {{ parent() }}

{% endblock %}
```

::: danger
Icons or other custom assets are not included in the theme inheritance.
:::

Inside your theme, you cannot put an icon in a directory corresponding the core folder structure and expect the core one to be automatically overwritten by it, as you are used to with themes in general.

---

---
url: /docs/v6.5/guides/plugins/themes/add-icons.md
---

# Add Custom Icons

## Overview

In this guide, you will learn how to use the icon renderer component as well as adding custom icons.

::: info
Even if this is originally a plugin guide, everything will work perfectly in a theme as well. Actually, a theme even is a kind of plugin. So don't get confused by us talking about plugins here.
:::

## Prerequisites

To follow this guide easily, you first need to have a functioning plugin installed. Head over to our [Plugin base guide](../plugins/plugin-base-guide) to create a plugin, if you don't know how it's done yet. Also, knowing and understanding SCSS will be quite mandatory to fully understand what's going on here. Furthermore, it might be helpful to read the guide on how to [handle own assets](../plugins/storefront/add-custom-assets) in your plugin before you start with this one.

## Adding icon

To add any icons to the Storefront, you use our `sw_icon` twig action. This way, an icon of choice is displayed in the Storefront.

Needless to say, the first step is saving your image somewhere in your plugin where Shopware can find it. The default path for icons is the following:

```text
<YourPlugin>/src/Resources/app/storefront/dist/assets/icon/default
`
```

You can also provide "solid" icons or any other custom pack names that can be configured later with the `pack` parameter. You can do that by creating a folder with the pack name:

```text
<YourPlugin>/src/Resources/app/storefront/dist/assets/icon/<pack-name>
```

By default, Shopware looks inside the "default" folder.

```twig
{% sw_icon 'done-outline-24px' style {
    'namespace': 'TestPlugin'
} %}
```

::: info
When you want to see all icons available to the storefront by default, see [here](https://github.com/shopware/shopware/tree/trunk/src/Storefront/Resources/app/storefront/dist/assets/icon). They are available as `default` and `solid` icon pack.
:::

Imagine you want to use the default `checkmark` icon from the `solid` pack. In this case,

You surely want to add your own custom icons. In this case, the `namespace` parameter is the most important one to configure. In there, you need to set the name of the theme in which the icon is searched for by its name.

::: warning
If you configure no deviating namespace, Shopware will display the Storefront's default icons.
:::

However, these are not all of your possibilities of configuration. As you see, you're able to configure even more things. Let's take a look at the `style` object's possible parameters:

| Configuration | Description | Remarks |
| :--- | :--- | :--- |
| `size` | Sets the size of the icon | --- |
| `namespace` | Selection of the namespace of the icon, you can compare it with the source of it | Important configuration if you want to use custom icons. |
| `pack` | Selects the pack of different icons | --- |
| `color` | Sets the color of the icon | You can either use pre-defined variants similar to bootstrap (eg: primary , danger etc) or manually style the icon with any color with CSS. |
| `class` | Defines a class of the icon | --- |

A simple but fully functional example could look like below:

```twig
{% sw_extends '@Storefront/storefront/base.html.twig' %}

{% block base_body %}

    {# We want to set our own icon here #}
    <h1>Custom icon:</h1>
    {% sw_icon 'done-outline-24px' style {
        'size': 'lg',
        'namespace': 'TestPlugin',
        'pack': 'solid'
    } %}
    {{ parent() }}

{% endblock %}
```

::: danger
Icons or other custom assets are not included in the theme inheritance.
:::

Inside your theme, you cannot put an icon in a directory corresponding to the core folder structure and expect the core one to be automatically overwritten by it, as you're used to with themes in general.

## Load icons from custom locations

Since Shopware 6.4.1.0 it is possible to define custom locations of your custom icons inside your theme.json file.
You can define the name of the icon pack and the path to those icons under the `iconSets`-key:

```json
{
  /* ... */
  "iconSets": {
    "custom-icons": "app/storefront/src/assets/icon-pack/custom-icons"
  }
}
```

You can use your custom icons by specifying your icon pack:

```twig
{% sw_icon 'done-outline-24px' style {
    'pack': 'custom-icons'
} %}
```

::: warning
This setup is mandatory if you ship your Theme as an App, because otherwise your custom icons can't be loaded.
:::

---

---
url: /docs/v6.6/guides/plugins/plugins/storefront/add-icons.md
---

# Add Custom Icons

## Overview

In this guide you will learn how to use the icon renderer component as well as adding custom icons.

::: info
Even if this is originally a plugin guide, everything will work perfectly in a theme as well. Actually, a theme even is a kind of plugin. So don't get confused by us talking about plugins here.
:::

## Prerequisites

In order to follow this guide easily, you first need to have a functioning plugin installed. Head over to our [Plugin base guide](../plugin-base-guide) to create a plugin, if you don't know how it's done yet. Also knowing and understanding SCSS will be quite mandatory to fully understand what's going on here. Furthermore, it might be helpful to read the guide on how to [handle own assets](add-custom-assets) in your plugin before you start with this one.

## Adding icon

In order to add any icons to the Storefront, you use our `sw_icon` twig action. This way, an icon of choice is displayed in the Storefront.

Needless to say, the first step is saving your image somewhere in your plugin where Shopware can find it. The default path for icons is the following:

```text
<YourPlugin>/src/Resources/app/storefront/dist/assets/icon/default
`
```

You can also provide "solid" icons or any other custom pack names which can be configured later with the `pack` parameter. You can do that by creating a folder with the pack name:

```text
<YourPlugin>/src/Resources/app/storefront/dist/assets/icon/<pack-name>
```

By default, Shopware looks inside the "default" folder.

```twig
{% sw_icon 'done-outline-24px' style {
    'namespace': 'TestPlugin'
} %}
```

::: info
When you want to see all icons available to the Storefront by default, see [here](https://github.com/shopware/shopware/tree/trunk/src/Storefront/Resources/app/storefront/dist/assets/icon). They are available as `default` and `solid` icon pack.
:::

Imagine you want to use the default `checkmark` icon from the `solid` pack. In this case,

You surely want to add your own custom icons. In this case, the `namespace` parameter is the most important one to configure. In there, you need to set the name of the theme in which the icon is searched for by its name.

::: warning
If you configure no deviating namespace, Shopware will display the Storefront's default icons.
:::

However, these are not all of your possibilities of configuration. As you see, you're able to configure even more things. Let's take a look at the `style` object's possible parameters:

| Configuration | Description | Remarks |
| :--- | :--- | :--- |
| `size` | Sets the size of the icon | --- |
| `namespace` | Selection of the namespace of the icon, you can compare it with the source of it | Important configuration if you want to use custom icons. |
| `pack` | Selects the pack of different icons | --- |
| `color` | Sets the color of the icon | --- |
| `class` | Defines a class of the icon | --- |

A simple but fully functional example could look like below:

```twig
{% sw_extends '@Storefront/storefront/base.html.twig' %}

{% block base_body %}

    {# We want to set our own icon here #}
    <h1>Custom icon:</h1>
    {% sw_icon 'done-outline-24px' style {
        'size': 'lg',
        'namespace': 'TestPlugin',
        'pack': 'solid'
    } %}
    {{ parent() }}

{% endblock %}
```

::: danger
Icons or other custom assets are not included in the theme inheritance.
:::

Inside your theme, you cannot put an icon in a directory corresponding the core folder structure and expect the core one to be automatically overwritten by it, as you are used to with themes in general.

---

---
url: /docs/v6.6/guides/plugins/themes/add-icons.md
---

# Add Custom Icons

## Overview

In this guide, you will learn how to use the icon renderer component as well as adding custom icons.

::: info
Even if this is originally a plugin guide, everything will work perfectly in a theme as well. Actually, a theme even is a kind of plugin. So don't get confused by us talking about plugins here.
:::

## Prerequisites

To follow this guide easily, you first need to have a functioning plugin installed. Head over to our [Plugin base guide](../plugins/plugin-base-guide) to create a plugin, if you don't know how it's done yet. Also, knowing and understanding SCSS will be quite mandatory to fully understand what's going on here. Furthermore, it might be helpful to read the guide on how to [handle own assets](../plugins/storefront/add-custom-assets) in your plugin before you start with this one.

## Adding icon

To add any icons to the Storefront, you use our `sw_icon` twig action. This way, an icon of choice is displayed in the Storefront.

Needless to say, the first step is saving your image somewhere in your plugin where Shopware can find it. The default path for icons is the following:

```text
<YourPlugin>/src/Resources/app/storefront/dist/assets/icon/default
`
```

You can also provide "solid" icons or any other custom pack names that can be configured later with the `pack` parameter. You can do that by creating a folder with the pack name:

```text
<YourPlugin>/src/Resources/app/storefront/dist/assets/icon/<pack-name>
```

By default, Shopware looks inside the "default" folder.

```twig
{% sw_icon 'done-outline-24px' style {
    'namespace': 'TestPlugin'
} %}
```

::: info
When you want to see all icons available to the storefront by default, see [here](https://github.com/shopware/shopware/tree/trunk/src/Storefront/Resources/app/storefront/dist/assets/icon). They are available as `default` and `solid` icon pack.
:::

Imagine you want to use the default `checkmark` icon from the `solid` pack. In this case,

You surely want to add your own custom icons. In this case, the `namespace` parameter is the most important one to configure. In there, you need to set the name of the theme in which the icon is searched for by its name.

::: warning
If you configure no deviating namespace, Shopware will display the Storefront's default icons.
:::

However, these are not all of your possibilities of configuration. As you see, you're able to configure even more things. Let's take a look at the `style` object's possible parameters:

| Configuration | Description | Remarks |
| :--- | :--- | :--- |
| `size` | Sets the size of the icon | --- |
| `namespace` | Selection of the namespace of the icon, you can compare it with the source of it | Important configuration if you want to use custom icons. |
| `pack` | Selects the pack of different icons | --- |
| `color` | Sets the color of the icon | You can either use pre-defined variants similar to bootstrap (eg: primary , danger etc) or manually style the icon with any color with CSS. |
| `class` | Defines a class of the icon | --- |

A simple but fully functional example could look like below:

```twig
{% sw_extends '@Storefront/storefront/base.html.twig' %}

{% block base_body %}

    {# We want to set our own icon here #}
    <h1>Custom icon:</h1>
    {% sw_icon 'done-outline-24px' style {
        'size': 'lg',
        'namespace': 'TestPlugin',
        'pack': 'solid'
    } %}
    {{ parent() }}

{% endblock %}
```

::: danger
Icons or other custom assets are not included in the theme inheritance.
:::

Inside your theme, you cannot put an icon in a directory corresponding to the core folder structure and expect the core one to be automatically overwritten by it, as you're used to with themes in general.

## Load icons from custom locations

Since Shopware 6.4.1.0 it is possible to define custom locations of your custom icons inside your theme.json file.
You can define the name of the icon pack and the path to those icons under the `iconSets`-key:

```json
{
  /* ... */
  "iconSets": {
    "custom-icons": "app/storefront/src/assets/icon-pack/custom-icons"
  }
}
```

You can use your custom icons by specifying your icon pack:

```twig
{% sw_icon 'done-outline-24px' style {
    'pack': 'custom-icons'
} %}
```

::: warning
This setup is mandatory if you ship your Theme as an App, because otherwise your custom icons can't be loaded.
:::

---

---
url: /docs/v6.5/guides/plugins/plugins/administration/add-custom-field.md
---

# Add custom input field to existing component

## Overview

If you were wondering how to add a new input field to an existing module in the Administration via plugin, then you've found the right guide to cover that subject. In the following examples, you'll add a new input field to the product's detail page, to display and configure some other product data not being handled by default.

## Prerequisites

This guide **does not** explain how you can create a new plugin for Shopware 6. Head over to our plugin base guide to learn how to create a plugin at first:

## Injecting into the Administration

The main entry point to customize the Administration via plugin is the `main.js` file. It has to be placed into a `<plugin root>/src/Resources/app/administration/src` directory in order to be automatically found by Shopware 6.

Your `main.js` file then needs to override the [Vue component](https://vuejs.org/v2/guide/components.html) using the `override` method of our `ComponentFactory`.

The first parameter matches the component to override, the second parameter has to be an object containing the actually overridden properties , e.g. the new twig template extension for this component.

```javascript
// <plugin root>/src/Resources/app/administration/src/main.js
import template from './extension/sw-product-settings-form/sw-product-settings-form.html.twig';

Shopware.Component.override('sw-product-settings-form', {
    template
});
```

In this case, the `sw-product-settings-form` component is overridden, which reflects the settings form on the product detail page. As mentioned above, the second parameter has to be an object, which includes the actual template extension.

## Adding the custom template

Time to create the referenced twig template for your plugin now.

::: info
We're dealing with a [TwigJS](https://github.com/twigjs/twig.js/wiki) template here.
:::

Create a file called `sw-product-settings-form.html.twig` in the following directory: `<plugin root>/src/Resources/app/administration/src/extension/sw-product-settings-form`

::: info
The path starting from 'src' is fully customizable, yet we recommend choosing a pattern like this one.
:::

```twig
// <plugin root>/src/Resources/app/administration/src/extension/sw-product-settings-form/sw-product-settings-form.html.twig
{% block sw_product_settings_form_content %}
    {% parent %}

    <sw-container columns="repeat(auto-fit, minmax(250px, 1fr))" gap="0px 30px">
        <sw-text-field label="Manufacturer ID" v-model="product.manufacturerId" disabled></sw-text-field>
    </sw-container>
{% endblock %}
```

Basically the twig block `sw_product_settings_form_content` is overridden here. Make sure to have a look at the [Twig documentation about the template inheritance](https://twig.symfony.com/doc/3.x/templates.html#template-inheritance), to understand how blocks in Twig work.

This block contains the whole settings form of the product detail page. In order to add a new input field to it, you need to override the block, call the block's original content (otherwise we'd replace the whole form), and then add your custom input field to it. Also, the input field is "disabled", since it should be readable only. This should result in a new input field with the label 'Manufacturer ID', which then contains the ID of the actually chosen manufacturer.

## Loading the JS files

As mentioned above, Shopware 6 is looking for a `main.js` file in your plugin. Its contents get minified into a new file named after your plugin and will be moved to the `public` directory of Shopware 6 root directory. Given this plugin would be named "AdministrationNewField", the minified javascript code for this example would be located under `<plugin root>/src/Resources/public/administration/js/administration-new-field.js`, once you run the command following command in your shopware root directory:

```bash
./bin/build-administration.sh
```

```bash
composer run build:js:admin
```

::: info
Your plugin has to be activated for this to work.
:::

Make sure to also include that file when publishing your plugin! A copy of this file will then be put into the directory `<shopware root>/public/bundles/administration/newfield/administration/js/administration-new-field.js`.

Your minified javascript file will now be loaded in production environments.

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/administration/module-component-management/add-custom-field.md
---

# Add custom input field to existing component

## Overview

If you were wondering how to add a new input field to an existing module in the Administration via plugin, then you've found the right guide to cover that subject. In the following examples, you'll add a new input field to the product's detail page, to display and configure some other product data not being handled by default.

## Prerequisites

This guide **does not** explain how you can create a new plugin for Shopware 6. Head over to our plugin base guide to learn how to create a plugin at first:

## Injecting into the Administration

The main entry point to customize the Administration via plugin is the `main.js` file. It has to be placed into a `<plugin root>/src/Resources/app/administration/src` directory in order to be automatically found by Shopware 6.

Your `main.js` file then needs to override the [Vue component](https://vuejs.org/v2/guide/components.html) using the `override` method of our `ComponentFactory`.

The first parameter matches the component to override, the second parameter has to be an object containing the actually overridden properties , e.g. the new twig template extension for this component.

```javascript
// <plugin root>/src/Resources/app/administration/src/main.js
import template from './extension/sw-product-settings-form/sw-product-settings-form.html.twig';

Shopware.Component.override('sw-product-settings-form', {
    template
});
```

In this case, the `sw-product-settings-form` component is overridden, which reflects the settings form on the product detail page. As mentioned above, the second parameter has to be an object, which includes the actual template extension.

## Adding the custom template

Time to create the referenced twig template for your plugin now.

::: info
We're dealing with a [TwigJS](https://github.com/twigjs/twig.js/wiki) template here.
:::

Create a file called `sw-product-settings-form.html.twig` in the following directory: `<plugin root>/src/Resources/app/administration/src/extension/sw-product-settings-form`

::: info
The path starting from 'src' is fully customizable, yet we recommend choosing a pattern like this one.
:::

```twig
// <plugin root>/src/Resources/app/administration/src/extension/sw-product-settings-form/sw-product-settings-form.html.twig
{% block sw_product_settings_form_content %}
    {% parent %}

    <sw-container columns="repeat(auto-fit, minmax(250px, 1fr))" gap="0px 30px">
        <sw-text-field label="Manufacturer ID" v-model="product.manufacturerId" disabled></sw-text-field>
    </sw-container>
{% endblock %}
```

Basically the twig block `sw_product_settings_form_content` is overridden here. Make sure to have a look at the [Twig documentation about the template inheritance](https://twig.symfony.com/doc/3.x/templates.html#template-inheritance), to understand how blocks in Twig work.

This block contains the whole settings form of the product detail page. In order to add a new input field to it, you need to override the block, call the block's original content (otherwise we'd replace the whole form), and then add your custom input field to it. Also, the input field is "disabled", since it should be readable only. This should result in a new input field with the label 'Manufacturer ID', which then contains the ID of the actually chosen manufacturer.

## Loading the JS files

As mentioned above, Shopware 6 is looking for a `main.js` file in your plugin. Its contents get minified into a new file named after your plugin and will be moved to the `public` directory of Shopware 6 root directory. Given this plugin would be named "AdministrationNewField", the minified javascript code for this example would be located under `<plugin root>/src/Resources/public/administration/js/administration-new-field.js`, once you run the command following command in your shopware root directory:

```bash
./bin/build-administration.sh
```

```bash
composer run build:js:admin
```

::: info
Your plugin has to be activated for this to work.
:::

Make sure to also include that file when publishing your plugin! A copy of this file will then be put into the directory `<shopware root>/public/bundles/administration/newfield/administration/js/administration-new-field.js`.

Your minified javascript file will now be loaded in production environments.

---

---
url: >-
  /docs/guides/plugins/plugins/administration/module-component-management/add-custom-field.md
---

# Add Custom Input Field to Existing Component

## Overview

This guide explains how to add a new input field to an existing module in the Administration using a plugin. The following examples show how to add a new input field to the product's detail page in order to display and configure other product data not being handled by default.

## Prerequisites

This guide **does not** explain how you can create a new plugin for Shopware 6. Head over to our plugin base guide to learn how to create a plugin at first:

## Injecting into the Administration

The main entry point to customize the Administration via plugin is the `main.js` file. It has to be placed into a `<plugin root>/src/Resources/app/administration/src` directory in order to be automatically found by Shopware 6.

Your `main.js` file then needs to override the [Vue component](https://vuejs.org/guide/essentials/component-basics.html) using the `override` method of our `ComponentFactory`.

The first parameter matches the component to override, the second parameter has to be an object containing the actually overridden properties , e.g. the new twig template extension for this component.

```javascript
// <plugin root>/src/Resources/app/administration/src/main.js
import template from './extension/sw-product-settings-form/sw-product-settings-form.html.twig';

Shopware.Component.override('sw-product-settings-form', {
    template
});
```

In this case, the `sw-product-settings-form` component is overridden, which reflects the settings form on the product detail page. As mentioned above, the second parameter has to be an object, which includes the actual template extension.

## Adding the custom template

Time to create the referenced twig template for your plugin now.

::: info
We're dealing with a [TwigJS](https://github.com/twigjs/twig.js/wiki) template here.
:::

Create a file called `sw-product-settings-form.html.twig` in the following directory: `<plugin root>/src/Resources/app/administration/src/extension/sw-product-settings-form`

::: info
The path starting from 'src' is fully customizable, yet we recommend choosing a pattern like this one.
:::

```twig
// <plugin root>/src/Resources/app/administration/src/extension/sw-product-settings-form/sw-product-settings-form.html.twig
{% block sw_product_settings_form_content %}
    {% parent %}

    <sw-container columns="repeat(auto-fit, minmax(250px, 1fr))" gap="0px 30px">
        <sw-text-field label="Manufacturer ID" v-model="product.manufacturerId" disabled></sw-text-field>
    </sw-container>
{% endblock %}
```

Basically the twig block `sw_product_settings_form_content` is overridden here. Make sure to have a look at the [Twig documentation about the template inheritance](https://twig.symfony.com/doc/3.x/templates.html#template-inheritance), to understand how blocks in Twig work.

This block contains the whole settings form of the product detail page. In order to add a new input field to it, you need to override the block, call the block's original content (otherwise we'd replace the whole form), and then add your custom input field to it. Also, the input field is "disabled", since it should be readable only. This should result in a new input field with the label 'Manufacturer ID', which then contains the ID of the actually chosen manufacturer.

## Loading the JS files

As mentioned above, Shopware 6 is looking for a `main.js` file in your plugin. Its contents get minified into a new file named after your plugin and will be moved to the `public` directory of Shopware 6 root directory. Given this plugin would be named "AdministrationNewField", the minified javascript code for this example would be located under `<plugin root>/src/Resources/public/administration/js/administration-new-field.js`, once you run the command following command in your shopware root directory:

```bash
shopware-cli project admin-build
```

```bash
composer run build:js:admin
```

::: info
Your plugin has to be activated for this to work.
:::

Make sure to also include that file when publishing your plugin! A copy of this file will then be put into the directory `<shopware root>/public/bundles/administration/newfield/administration/js/administration-new-field.js`.

Your minified javascript file will now be loaded in production environments.

---

---
url: /docs/v6.5/guides/plugins/plugins/storefront/add-custom-javascript.md
---

# Add Custom Javascript

## Overview

If you want to add interactivity to your Storefront you probably have to write your own JavaScript plugin. Here you will be guided through the process of writing and registering your own JavaScript plugins. You will write a plugin that simply checks if the user has scrolled to the bottom of the page and then creates an alert.

## Prerequisites

You need for this guide a running plugin and therefore a running Shopware 6 instance, with full access to all files. This also includes access to the command line to execute a command, which then builds the Storefront. A general understanding of vanilla JavaScript ES6 is also mandatory. Everything else is explained in this guide itself.

## Writing a JavaScript plugin

Storefront JavaScript plugins are vanilla JavaScript ES6 classes that extend from our Plugin base class. For more information, refer to [JavaScript classes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes) section.

The directory to create custom javascript plugins should be the following, which represents the same structure like the core: `<plugin root>/src/Resources/app/storefront/src/`

In there, you create a new directory, named after your plugin. In this guide, this will be called `example-plugin`, so the full path would look like this: `<plugin root>/src/Resources/app/storefront/src/example-plugin`

Now create an actual file for your JavaScript plugin, in this example it will be called `example-plugin.plugin.js`.

Inside this file create and export an ExamplePlugin class that extends the base Plugin class:

```javascript
// <plugin root>/src/Resources/app/storefront/src/example-plugin/example-plugin.plugin.js
import Plugin from 'src/plugin-system/plugin.class';

export default class ExamplePlugin extends Plugin {
}
```

This is just a basic vanilla JavaScript ES6 class, which extends the `Plugin` class.

Each plugin has to implement the `init()` method. This method will be called when your plugin gets initialized and is the entrypoint to your custom logic. The plugin initialization runs on `DOMContentLoaded` event, so you can be sure, that the dom is already completely loaded. In your case you add a callback to the `scroll` event from the window and check if the user has scrolled to the bottom of the page. If so we display an alert. Your full plugin now looks like this:

```javascript
// <plugin root>/src/Resources/app/storefront/src/example-plugin/example-plugin.plugin.js
import Plugin from 'src/plugin-system/plugin.class';

export default class ExamplePlugin extends Plugin {
    init() {
        window.addEventListener('scroll', this.onScroll.bind(this));
    }

    onScroll() {
        if ((window.innerHeight + window.pageYOffset) >= document.body.offsetHeight) {
            alert('Seems like there\'s nothing more to see here.');
        }
    }
}
```

A short explanation what the condition is doing here: The `window.innerHeight` contains the height of the window, as you might have guessed.

This is added to `window.pageYOffset`, which contains the current scroll position on the Y-axis. It represents the **top** value of the current scroll, which basically means: If your website is 5000px high and you scroll to the very bottom, the value would **not** be 5000px, but rather `5000px - window.innerHeight`. Thus, we have to add up the `innerHeight` to actually get the bottom of the website.

Well, and then we check if this sum is bigger or equal the total size of your website, by fetching the height of your website's `body` tag. If it is higher or equal the total height of the website, you reached the end of the website.

## Registering your plugin

Next you have to tell Shopware that your plugin should be loaded and executed. Therefore you have to register your plugin in the PluginManager.

Shopware is automatically looking for a `main.js` file in a directory `<plugin root>/src/Resources/app/storefront/src`, which then will be loaded automatically. Consider this to be your main storefront JavaScript entrypoint.

Create a `main.js` file inside your `<plugin root>/src/Resources/app/storefront/src` folder and get the PluginManager from the global window object. Then register your own plugin:

```javascript
// <plugin root>/src/Resources/app/storefront/src/main.js
// Import all necessary Storefront plugins
import ExamplePlugin from './example-plugin/example-plugin.plugin';

// Register your plugin via the existing PluginManager
const PluginManager = window.PluginManager;
PluginManager.register('ExamplePlugin', ExamplePlugin);
```

Right now, your plugin will automatically be loaded once you load the website.

## Binding your plugin to the DOM

You can also bind your plugin to a DOM element by providing a css selector:

```javascript
// <plugin root>/src/Resources/app/storefront/src/main.js
 // Import all necessary Storefront plugins
 import ExamplePlugin from './example-plugin/example-plugin.plugin';

 // Register your plugin via the existing PluginManager
 const PluginManager = window.PluginManager;
 PluginManager.register('ExamplePlugin', ExamplePlugin, '[data-example-plugin]');
```

In this case the plugin just gets executed if the HTML document contains at least one element with the `data-example-plugin` attribute. You can then use `this.el` inside your plugin to access the DOM element your plugin is bound to.

### Loading your plugin

The following will create a new template with a very short explanation. If you're looking for more information on what's going on here, head over to our guide about [Customizing templates](customize-templates).

You bound your plugin to the css selector `[data-example-plugin]`, so you have to add DOM elements with this attribute on the pages you want your plugin to be active.

Create a `<plugin root>/src/Resources/views/storefront/page/content/` folder and create a `index.html.twig` template. Inside this template, extend from the `@Storefront/storefront/page/content/index.html.twig` and overwrite the `base_main_inner` block. After the parent content of the blog, add a template tag that has the `data-example-plugin` attribute.

A lot of text, here is the respective example:

```twig
// <plugin root>/src/Resources/views/storefront/page/content/index.html.twig
{% sw_extends '@Storefront/storefront/page/content/index.html.twig' %}

{% block base_main_inner %}
    {{ parent() }}

    <template data-example-plugin></template>
{% endblock %}
```

With this template extension your plugin is active on every content page, like the homepage or category listing pages.

## Configuring your plugins

You can configure your plugins from inside the templates via data-options. First you have to define a static `options` object inside your plugin and assign your options with default values to it. In your case define a `text` option and as a default value use the text you previously directly prompted to the user. And instead of the hard coded string inside the `alert()`, use your new option value.

```javascript
// <plugin root>/src/Resources/app/storefront/src/example-plugin/example-plugin.plugin.js
import Plugin from 'src/plugin-system/plugin.class';

export default class ExamplePlugin extends Plugin {
    static options = {
        /**
         * Specifies the text that is prompted to the user
         * @type string
         */
        text: 'Seems like there\'s nothing more to see here.',
    };

    init() {
        window.addEventListener('scroll', this.onScroll.bind(this));
    }

    onScroll() {
        if ((window.innerHeight + window.pageYOffset) >= document.body.offsetHeight) {
            alert(this.options.text);
        }
    }
}
```

Now you are able to override the text that is prompted to the user from inside your templates. For this example we're going to display another message on product detail pages.

Therefore create a `product-detail` folder inside your `<plugin root>/src/Resources/views/storefront/page` folder and add an `index.html.twig` file inside that folder. In your template extend from the default `@Storefront/storefront/page/product-detail/index.html.twig` and override the block `page_product_detail_content`.

After the parent content add a template tag with the `data-example-plugin` tag to activate your plugin on product detail pages as well. Next add a `data-{your-plugin-name-in-kebab-case}-options` (in this example: `data-example-plugin-options`) attribute to the DOM element you registered your plugin on (the template tag). The value of this attribute are the options you want to override as a JSON object.

```twig
// <plugin root>/src/Resources/views/storefront/page/product-detail/index.html.twig
{% sw_extends '@Storefront/storefront/page/product-detail/index.html.twig' %}

{% set examplePluginOptions = {
    text: "Are you not interested in this product?"
} %}

{% block page_product_detail_content %}
    {{ parent() }}

    <template data-example-plugin data-example-plugin-options='{{ examplePluginOptions|json_encode }}'></template>
{% endblock %}
```

It is best practice to use a variable for the options because this is extendable from plugins.

## Modify existing options

We've just mentioned the best practice to use a template variable for setting plugin options, so other plugins can extend those options. This section will explain how to do actually achieve that.

You can use the `replace_recursive` Twig filter for this case.

Imagine the following example can be found in the core:

```twig
{% set productSliderOptions = {
    productboxMinWidth: sliderConfig.elMinWidth.value ? sliderConfig.elMinWidth.value : '',
    slider: {
        gutter: 30,
        autoplayButtonOutput: false,
        nav: false,
        mouseDrag: false,
        controls: sliderConfig.navigation.value ? true : false,
        autoplay: sliderConfig.rotate.value ? true : false
    }
} %}

{% block element_product_slider_slider %}
    <div class="base-slider"
         data-product-slider="true"
         data-product-slider-options="{{ productSliderOptions|default({})|json_encode|escape('html_attr') }}">
    </div>
{% endblock %}
```

Now you want to overwrite the value `slider.mouseDrag` with your plugin. The variable can be overwritten with `replace_recursive`:

```twig
{% block element_product_slider_slider %}
    {% set productSliderOptions = productSliderOptions|replace_recursive({
        slider: {
            mouseDrag: true
        }
    }) %}

    {{ parent() }}
{% endblock %}
```

## Plugin script path

For JavaScript you normally would have two locations where your `*.js` files are located. You have your `main.js` as an entry point inside of the following directory: `<plugin root>/src/Resources/app/storefront/src`.

Shopware will then compile the JavaScript and save the compiled version at `<plugin root>/src/Resources/app/storefront/dist/storefront/js/<plugin-name>.js`. This file will be recognized automatically by Shopware.

Make sure to ship the compiled file with your plugin as well.

## Testing your changes

To see your changes you have to build the Storefront. Use the following command and reload your Storefront:

```bash
./bin/build-storefront.sh
```

```bash
composer run build:js:storefront
```

If you now scroll to the bottom of your page an alert should appear.

## Next steps

You've got your own first javascript plugin running. You might want to start [listening to javascript events](reacting-to-javascript-events) now, or even [override other javascript plugins](override-existing-javascript) instead.

---

---
url: /docs/v6.6/guides/plugins/plugins/storefront/add-custom-javascript.md
---

# Add Custom Javascript

## Overview

If you want to add interactivity to your Storefront you probably have to write your own JavaScript plugin. Here you will be guided through the process of writing and registering your own JavaScript plugins. You will write a plugin that simply checks if the user has scrolled to the bottom of the page and then creates an alert.

## Prerequisites

You need for this guide a running plugin and therefore a running Shopware 6 instance, with full access to all files. This also includes access to the command line to execute a command, which then builds the Storefront. A general understanding of vanilla JavaScript ES6 is also mandatory. Everything else is explained in this guide itself.

## Writing a JavaScript plugin

Storefront JavaScript plugins are vanilla JavaScript ES6 classes that extend from our Plugin base class. For more information, refer to [JavaScript classes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes) section.

The directory to create custom javascript plugins should be the following, which represents the same structure like the core: `<plugin root>/src/Resources/app/storefront/src/`

In there, you create a new directory, named after your plugin. In this guide, this will be called `example-plugin`, so the full path would look like this: `<plugin root>/src/Resources/app/storefront/src/example-plugin`

Now create an actual file for your JavaScript plugin, in this example it will be called `example-plugin.plugin.js`.

Inside this file create and export an ExamplePlugin class that extends the base Plugin class:

```javascript
// <plugin root>/src/Resources/app/storefront/src/example-plugin/example-plugin.plugin.js
const { PluginBaseClass } = window;

export default class ExamplePlugin extends PluginBaseClass {
}
```

This is just a basic vanilla JavaScript ES6 class, which extends the `Plugin` class.

Each plugin has to implement the `init()` method. This method will be called when your plugin gets initialized and is the entrypoint to your custom logic. The plugin initialization runs on `DOMContentLoaded` event, so you can be sure, that the dom is already completely loaded. In your case you add a callback to the `scroll` event from the window and check if the user has scrolled to the bottom of the page. If so we display an alert. Your full plugin now looks like this:

```javascript
// <plugin root>/src/Resources/app/storefront/src/example-plugin/example-plugin.plugin.js
const { PluginBaseClass } = window;

export default class ExamplePlugin extends PluginBaseClass {
    init() {
        window.addEventListener('scroll', this.onScroll.bind(this));
    }

    onScroll() {
        if ((window.innerHeight + window.pageYOffset) >= document.body.offsetHeight) {
            alert('Seems like there\'s nothing more to see here.');
        }
    }
}
```

A short explanation what the condition is doing here: The `window.innerHeight` contains the height of the window, as you might have guessed.

This is added to `window.pageYOffset`, which contains the current scroll position on the Y-axis. It represents the **top** value of the current scroll, which basically means: If your website is 5000px high and you scroll to the very bottom, the value would **not** be 5000px, but rather `5000px - window.innerHeight`. Thus, we have to add up the `innerHeight` to actually get the bottom of the website.

Well, and then we check if this sum is bigger or equal the total size of your website, by fetching the height of your website's `body` tag. If it is higher or equal the total height of the website, you reached the end of the website.

## Registering your plugin

Next you have to tell Shopware that your plugin should be loaded and executed. Therefore you have to register your plugin in the PluginManager.

Shopware is automatically looking for a `main.js` file in a directory `<plugin root>/src/Resources/app/storefront/src`, which then will be loaded automatically. Consider this to be your main storefront JavaScript entrypoint.

Create a `main.js` file inside your `<plugin root>/src/Resources/app/storefront/src` folder and get the PluginManager from the global window object. Then register your own plugin:

```javascript
// <plugin root>/src/Resources/app/storefront/src/main.js
// Import all necessary Storefront plugins
import ExamplePlugin from './example-plugin/example-plugin.plugin';

// Register your plugin via the existing PluginManager
const PluginManager = window.PluginManager;
PluginManager.register('ExamplePlugin', ExamplePlugin);
```

Right now, your plugin will automatically be loaded once you load the website.

## Binding your plugin to the DOM

You can also bind your plugin to a DOM element by providing a css selector:

```javascript
// <plugin root>/src/Resources/app/storefront/src/main.js
// Import all necessary Storefront plugins
import ExamplePlugin from './example-plugin/example-plugin.plugin';

// Register your plugin via the existing PluginManager
const PluginManager = window.PluginManager;
PluginManager.register('ExamplePlugin', ExamplePlugin, '[data-example-plugin]');
```

In this case the plugin just gets executed if the HTML document contains at least one element with the `data-example-plugin` attribute. You can then use `this.el` inside your plugin to access the DOM element your plugin is bound to.

## Registering an async plugin

You can also register an async JS-plugin. Instead of importing a JS-plugin file at the top of your `main.js`, you can provide a dynamic import inside `PluginManager.register()`.
The import path can remain the same as the synchronous import.

```javascript
// <plugin root>/src/Resources/app/storefront/src/main.js

// Register your plugin via the existing PluginManager using a dynamic import
const PluginManager = window.PluginManager;
PluginManager.register('ExamplePlugin', () => import('./example-plugin/example-plugin.plugin'), '[data-example-plugin]');
```

If an async/dynamic import is provided, then the JS-plugin will be recognized as async by the PluginManager automatically.
This means that, the registered JS-plugin will not be included in the main bundled JavaScript (storefront.js) by default. The JS-plugin will only be downloaded on-demand if the plugin selector (`[data-example-plugin]`) is found on the current page, see [Loading your plugin](#loading-your-plugin).

Using an async JS-plugin can be helpful when the plugin is not supposed to be loaded on every page and should only be loaded when it is actually needed. This can reduce the size of the initially loaded JavaScript in the browser.
When using the "normal" import (`import ExamplePlugin from './example-plugin/example-plugin.plugin';`) in comparison, the JS-plugin will always be included in the JavaScript on all pages.

### Loading your plugin

The following will create a new template with a very short explanation. If you're looking for more information on what's going on here, head over to our guide about [Customizing templates](customize-templates).

You bound your plugin to the css selector `[data-example-plugin]`, so you have to add DOM elements with this attribute on the pages you want your plugin to be active.

Create a `<plugin root>/src/Resources/views/storefront/page/content/` folder and create a `index.html.twig` template. Inside this template, extend from the `@Storefront/storefront/page/content/index.html.twig` and overwrite the `base_main_inner` block. After the parent content of the blog, add a template tag that has the `data-example-plugin` attribute.

A lot of text, here is the respective example:

```twig
// <plugin root>/src/Resources/views/storefront/page/content/index.html.twig
{% sw_extends '@Storefront/storefront/page/content/index.html.twig' %}

{% block base_main_inner %}
    {{ parent() }}

    <template data-example-plugin></template>
{% endblock %}
```

With this template extension your plugin is active on every content page, like the homepage or category listing pages.

## Configuring your plugins

You can configure your plugins from inside the templates via data-options. First you have to define a static `options` object inside your plugin and assign your options with default values to it. In your case define a `text` option and as a default value use the text you previously directly prompted to the user. And instead of the hard coded string inside the `alert()`, use your new option value.

```javascript
// <plugin root>/src/Resources/app/storefront/src/example-plugin/example-plugin.plugin.js
const { PluginBaseClass } = window;

export default class ExamplePlugin extends PluginBaseClass {
    static options = {
        /**
         * Specifies the text that is prompted to the user
         * @type string
         */
        text: 'Seems like there\'s nothing more to see here.',
    };

    init() {
        window.addEventListener('scroll', this.onScroll.bind(this));
    }

    onScroll() {
        if ((window.innerHeight + window.pageYOffset) >= document.body.offsetHeight) {
            alert(this.options.text);
        }
    }
}
```

Now you are able to override the text that is prompted to the user from inside your templates. For this example we're going to display another message on product detail pages.

Therefore create a `product-detail` folder inside your `<plugin root>/src/Resources/views/storefront/page` folder and add an `index.html.twig` file inside that folder. In your template extend from the default `@Storefront/storefront/page/product-detail/index.html.twig` and override the block `page_product_detail_content`.

After the parent content add a template tag with the `data-example-plugin` tag to activate your plugin on product detail pages as well. Next add a `data-{your-plugin-name-in-kebab-case}-options` (in this example: `data-example-plugin-options`) attribute to the DOM element you registered your plugin on (the template tag). The value of this attribute are the options you want to override as a JSON object.

```twig
// <plugin root>/src/Resources/views/storefront/page/product-detail/index.html.twig
{% sw_extends '@Storefront/storefront/page/product-detail/index.html.twig' %}

{% set examplePluginOptions = {
    text: "Are you not interested in this product?"
} %}

{% block page_product_detail_content %}
    {{ parent() }}

    <template data-example-plugin data-example-plugin-options='{{ examplePluginOptions|json_encode }}'></template>
{% endblock %}
```

It is best practice to use a variable for the options because this is extendable from plugins.

## Modify existing options

We've just mentioned the best practice to use a template variable for setting plugin options, so other plugins can extend those options. This section will explain how to do actually achieve that.

You can use the `replace_recursive` Twig filter for this case.

Imagine the following example can be found in the core:

```twig
{% set productSliderOptions = {
    productboxMinWidth: sliderConfig.elMinWidth.value ? sliderConfig.elMinWidth.value : '',
    slider: {
        gutter: 30,
        autoplayButtonOutput: false,
        nav: false,
        mouseDrag: false,
        controls: sliderConfig.navigation.value ? true : false,
        autoplay: sliderConfig.rotate.value ? true : false
    }
} %}

{% block element_product_slider_slider %}
    <div class="base-slider"
         data-product-slider="true"
         data-product-slider-options="{{ productSliderOptions|default({})|json_encode|escape('html_attr') }}">
    </div>
{% endblock %}
```

Now you want to overwrite the value `slider.mouseDrag` with your plugin. The variable can be overwritten with `replace_recursive`:

```twig
{% block element_product_slider_slider %}
    {% set productSliderOptions = productSliderOptions|replace_recursive({
        slider: {
            mouseDrag: true
        }
    }) %}

    {{ parent() }}
{% endblock %}
```

## Plugin script path

For JavaScript you normally would have two locations where your `*.js` files are located. You have your `main.js` as an entry point inside of the following directory: `<plugin root>/src/Resources/app/storefront/src`.

Shopware will then compile the JavaScript and save the compiled version at `<plugin root>/src/Resources/app/storefront/dist/storefront/js/<plugin-name>/<plugin-name>.js`. These files will be recognized automatically by Shopware.

Make sure to ship the compiled file with your plugin as well.

## Testing your changes

To see your changes you have to build the Storefront. Use the following command and reload your Storefront:

```bash
./bin/build-storefront.sh
```

```bash
composer run build:js:storefront
```

If you now scroll to the bottom of your page an alert should appear.

## Next steps

You've got your own first javascript plugin running. You might want to start [listening to javascript events](reacting-to-javascript-events) now, or even [override other javascript plugins](override-existing-javascript) instead.

---

---
url: /docs/guides/plugins/plugins/storefront/javascript/add-custom-javascript.md
---

# Add Custom JavaScript

## Overview

Adding interactivity to your Storefront sometimes might require writing your own JavaScript plugin. This guide covers writing and registering your own JavaScript plugins. You will write a plugin that checks whether the user has scrolled to the bottom of the page, then creates an alert.

## Prerequisites

You need for this guide a running plugin and therefore a running Shopware 6 instance, with full access to all files. This also includes access to the command line to execute a command, which then builds the Storefront. A general understanding of vanilla JavaScript ES6 is also mandatory. Everything else is explained in this guide itself.

## Writing a JavaScript plugin

Storefront JavaScript plugins are vanilla JavaScript ES6 classes that extend from our Plugin base class. For more information, refer to [JavaScript classes](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Classes) section.

The directory to create custom javascript plugins should be the following, which represents the same structure like the core: `<plugin root>/src/Resources/app/storefront/src/`

In there, you create a new directory, named after your plugin. In this guide, this will be called `example-plugin`, so the full path would look like this: `<plugin root>/src/Resources/app/storefront/src/example-plugin`

Now create an actual file for your JavaScript plugin, in this example it will be called `example-plugin.plugin.js`.

Inside this file create and export an ExamplePlugin class that extends the base Plugin class:

```javascript
// <plugin root>/src/Resources/app/storefront/src/example-plugin/example-plugin.plugin.js
const { PluginBaseClass } = window;

export default class ExamplePlugin extends PluginBaseClass {
}
```

This is just a basic vanilla JavaScript ES6 class, which extends the `Plugin` class.

Each plugin has to implement the `init()` method. This method will be called when your plugin gets initialized and is the entrypoint to your custom logic. The plugin initialization runs on `DOMContentLoaded` event, so you can be sure, that the dom is already completely loaded. In your case you add a callback to the `scroll` event from the window and check if the user has scrolled to the bottom of the page. If so we display an alert. Your full plugin now looks like this:

```javascript
// <plugin root>/src/Resources/app/storefront/src/example-plugin/example-plugin.plugin.js
const { PluginBaseClass } = window;

export default class ExamplePlugin extends PluginBaseClass {
    init() {
        window.addEventListener('scroll', this.onScroll.bind(this));
    }

    onScroll() {
        if ((window.innerHeight + window.pageYOffset) >= document.body.offsetHeight) {
            alert('Seems like there\'s nothing more to see here.');
        }
    }
}
```

A short explanation what the condition is doing here: The `window.innerHeight` contains the height of the window, as you might have guessed.

This is added to `window.pageYOffset`, which contains the current scroll position on the Y-axis. It represents the **top** value of the current scroll, which basically means: If your website is 5000px high and you scroll to the very bottom, the value would **not** be 5000px, but rather `5000px - window.innerHeight`. Thus, we have to add up the `innerHeight` to actually get the bottom of the website.

Well, and then we check if this sum is bigger or equal the total size of your website, by fetching the height of your website's `body` tag. If it is higher or equal the total height of the website, you reached the end of the website.

## Registering your plugin

Next you have to tell Shopware that your plugin should be loaded and executed. Therefore you have to register your plugin in the PluginManager.

Shopware is automatically looking for a `main.js` file in a directory `<plugin root>/src/Resources/app/storefront/src`, which then will be loaded automatically. Consider this to be your main storefront JavaScript entrypoint.

Create a `main.js` file inside your `<plugin root>/src/Resources/app/storefront/src` folder and get the PluginManager from the global window object. Then register your own plugin:

```javascript
// <plugin root>/src/Resources/app/storefront/src/main.js
// Import all necessary Storefront plugins
import ExamplePlugin from './example-plugin/example-plugin.plugin';

// Register your plugin via the existing PluginManager
const PluginManager = window.PluginManager;
PluginManager.register('ExamplePlugin', ExamplePlugin);
```

Right now, your plugin will automatically be loaded once you load the website.

## Binding your plugin to the DOM

You can also bind your plugin to a DOM element by providing a css selector:

```javascript
// <plugin root>/src/Resources/app/storefront/src/main.js
// Import all necessary Storefront plugins
import ExamplePlugin from './example-plugin/example-plugin.plugin';

// Register your plugin via the existing PluginManager
const PluginManager = window.PluginManager;
PluginManager.register('ExamplePlugin', ExamplePlugin, '[data-example-plugin]');
```

In this case the plugin just gets executed if the HTML document contains at least one element with the `data-example-plugin` attribute. You can then use `this.el` inside your plugin to access the DOM element your plugin is bound to.

## Registering an async plugin

You can also register an async JS-plugin. Instead of importing a JS-plugin file at the top of your `main.js`, you can provide a dynamic import inside `PluginManager.register()`.
The import path can remain the same as the synchronous import.

```javascript
// <plugin root>/src/Resources/app/storefront/src/main.js

// Register your plugin via the existing PluginManager using a dynamic import
const PluginManager = window.PluginManager;
PluginManager.register('ExamplePlugin', () => import('./example-plugin/example-plugin.plugin'), '[data-example-plugin]');
```

If an async/dynamic import is provided, then the JS-plugin will be recognized as async by the PluginManager automatically.
This means that, the registered JS-plugin will not be included in the main bundled JavaScript (storefront.js) by default. The JS-plugin will only be downloaded on-demand if the plugin selector (`[data-example-plugin]`) is found on the current page, see [Loading your plugin](#loading-your-plugin).

Using an async JS-plugin can be helpful when the plugin is not supposed to be loaded on every page and should only be loaded when it is actually needed. This can reduce the size of the initially loaded JavaScript in the browser.
When using the "normal" import (`import ExamplePlugin from './example-plugin/example-plugin.plugin';`) in comparison, the JS-plugin will always be included in the JavaScript on all pages.

### Loading your plugin

The following will create a new template with a very short explanation. If you're looking for more information on what's going on here, head over to our guide about [Customizing templates](../templates/customize-templates.md).

You bound your plugin to the css selector `[data-example-plugin]`, so you have to add DOM elements with this attribute on the pages you want your plugin to be active.

Create a `<plugin root>/src/Resources/views/storefront/page/content/` folder and create a `index.html.twig` template. Inside this template, extend from the `@Storefront/storefront/page/content/index.html.twig` and overwrite the `base_main_inner` block. After the parent content of the blog, add a template tag that has the `data-example-plugin` attribute.

A lot of text, here is the respective example:

```twig
// <plugin root>/src/Resources/views/storefront/page/content/index.html.twig
{% sw_extends '@Storefront/storefront/page/content/index.html.twig' %}

{% block base_main_inner %}
    {{ parent() }}

    <template data-example-plugin></template>
{% endblock %}
```

With this template extension your plugin is active on every content page, like the homepage or category listing pages.

## Configuring your plugins

You can configure your plugins from inside the templates via data-options. First you have to define a static `options` object inside your plugin and assign your options with default values to it. In your case define a `text` option and as a default value use the text you previously directly prompted to the user. And instead of the hard coded string inside the `alert()`, use your new option value.

```javascript
// <plugin root>/src/Resources/app/storefront/src/example-plugin/example-plugin.plugin.js
const { PluginBaseClass } = window;

export default class ExamplePlugin extends PluginBaseClass {
    static options = {
        /**
         * Specifies the text that is prompted to the user
         * @type string
         */
        text: 'Seems like there\'s nothing more to see here.',
    };

    init() {
        window.addEventListener('scroll', this.onScroll.bind(this));
    }

    onScroll() {
        if ((window.innerHeight + window.pageYOffset) >= document.body.offsetHeight) {
            alert(this.options.text);
        }
    }
}
```

Now you are able to override the text that is prompted to the user from inside your templates. For this example we're going to display another message on product detail pages.

Therefore create a `product-detail` folder inside your `<plugin root>/src/Resources/views/storefront/page` folder and add an `index.html.twig` file inside that folder. In your template extend from the default `@Storefront/storefront/page/product-detail/index.html.twig` and override the block `page_product_detail_content`.

After the parent content add a template tag with the `data-example-plugin` tag to activate your plugin on product detail pages as well. Next add a `data-{your-plugin-name-in-kebab-case}-options` (in this example: `data-example-plugin-options`) attribute to the DOM element you registered your plugin on (the template tag). The value of this attribute are the options you want to override as a JSON object.

```twig
// <plugin root>/src/Resources/views/storefront/page/product-detail/index.html.twig
{% sw_extends '@Storefront/storefront/page/product-detail/index.html.twig' %}

{% set examplePluginOptions = {
    text: "Are you not interested in this product?"
} %}

{% block page_product_detail_content %}
    {{ parent() }}

    <template data-example-plugin data-example-plugin-options='{{ examplePluginOptions|json_encode }}'></template>
{% endblock %}
```

It is best practice to use a variable for the options because this is extendable from plugins.

## Modify existing options

We've just mentioned the best practice to use a template variable for setting plugin options, so other plugins can extend those options. This section will explain how to do actually achieve that.

You can use the `replace_recursive` Twig filter for this case.

Imagine the following example can be found in the core:

```twig
{% set productSliderOptions = {
    productboxMinWidth: sliderConfig.elMinWidth.value ? sliderConfig.elMinWidth.value : '',
    slider: {
        gutter: 30,
        autoplayButtonOutput: false,
        nav: false,
        mouseDrag: false,
        controls: sliderConfig.navigation.value ? true : false,
        autoplay: sliderConfig.rotate.value ? true : false
    }
} %}

{% block element_product_slider_slider %}
    <div class="base-slider"
         data-product-slider="true"
         data-product-slider-options="{{ productSliderOptions|default({})|json_encode|escape('html_attr') }}">
    </div>
{% endblock %}
```

Now you want to overwrite the value `slider.mouseDrag` with your plugin. The variable can be overwritten with `replace_recursive`:

```twig
{% block element_product_slider_slider %}
    {% set productSliderOptions = productSliderOptions|replace_recursive({
        slider: {
            mouseDrag: true
        }
    }) %}

    {{ parent() }}
{% endblock %}
```

## Plugin script path

For JavaScript you normally would have two locations where your `*.js` files are located. You have your `main.js` as an entry point inside of the following directory: `<plugin root>/src/Resources/app/storefront/src`.

Shopware will then compile the JavaScript and save the compiled version at `<plugin root>/src/Resources/app/storefront/dist/storefront/js/<plugin-name>/<plugin-name>.js`. These files will be recognized automatically by Shopware.

Make sure to ship the compiled file with your plugin as well.

## Testing your changes

To see your changes you have to build the Storefront. Use the following command and reload your Storefront:

```bash
shopware-cli project storefront-build
```

```bash
composer run build:js:storefront
```

If you now scroll to the bottom of your page an alert should appear.

## Next steps

With your own first JavaScript plugin now running, you might want to start [listening to JavaScript events](./reacting-to-javascript-events.md) or [overriding other JavaScript plugins](./override-existing-javascript.md).

---

---
url: /docs/guides/plugins/plugins/storefront/howto/add-listing-filters.md
---

# Add Custom Listing Filters

## Overview

In an online shop, filters are an important feature. So you might use filters in your custom plugin. This guide will get you covered on how to implement your own, custom filters in Shopware's Storefront.

## Prerequisites

Before you start reading this guide, make sure you got an own plugin installed to work with. If you need a starting point for that, see this guide:

## Create new Filter

At first, you need to create a subscriber. In this example, we will call it `ExampleListingSubscriber`. If you are not sure on working with subscribers, please refer to the guide on working with events in Shopware:

As usual, we will start by creating this new class in the same path as you're seeing in Shopware's core - `/src/Subscriber/ExampleListingSubscriber.php`.

New listing filters, e.g. for your product listing, can be registered via the event `\Shopware\Core\Content\Product\Events\ProductListingCollectFilterEvent` This event was introduced to enable every developer to specify the metadata for a filter. The handling, meaning if and how a filter is added, is done by Shopware's core:

```php
    public static function getSubscribedEvents(): array
    {
        return [
            ProductListingCollectFilterEvent::class => 'addFilter'
        ];
    }
```

After that, you can start to actually add your custom filters. Arguably an important step is to define your filter. Therefore, you're able to use the `Filter` class, including the parameters below:

| Parameter | Description |
| :--- | :--- |
| `name` | Unique name of the filter |
| `filtered` | Set this option to `true` if this filter is active |
| `aggregations` | Defines aggregations behind a filter. Sometimes a filter contains multiple aggregations like properties |
| `filter` | Sets the DAL filter which should be added to the criteria |
| `values` | Defines the values which will be added as `currentFilter` to the result |
| `exclude` | Configure exclusions |

As a result, an example filter could look like this:

```php
$filter = new Filter(
    // name
    'manufacturer',

    // filtered
    !empty($ids),

    // aggregations
    [new EntityAggregation('manufacturer', 'product.manufacturerId', 'product_manufacturer')],

    // filter
    new EqualsAnyFilter('product.manufacturerId', $ids),

    // values
    $ids
);
```

Inside the `ProductListingCollectFilterEvent`, you get the existing filters, can define your new custom filters and merge them into the existing ones. Here is a complete example implementation, adding a filter on the product information `isCloseout`. Please note the comments for explanation:

```php
// <plugin root>/src/Subscriber/ExampleListingSubscriber.php
class ExampleListingSubscriber implements EventSubscriberInterface
{
    // register event
    public static function getSubscribedEvents(): array
    {
        return [
            ProductListingCollectFilterEvent::class => 'addFilter'
        ];
    }

    public function addFilter(ProductListingCollectFilterEvent $event): void
    {
        // fetch existing filters
        $filters = $event->getFilters();
        $request = $event->getRequest();

        $filtered = (bool) $request->get('isCloseout');

        $filter = new Filter(
            // unique name of the filter
            'isCloseout',

            // defines if this filter is active
            $filtered,

            // Defines aggregations behind a filter. A filter can contain multiple aggregations like properties
            [
                new FilterAggregation(
                    'active-filter',
                    new MaxAggregation('active', 'product.isCloseout'),
                    [new EqualsFilter('product.isCloseout', true)]
                ),
            ],

            // defines the DAL filter which should be added to the criteria   
            new EqualsFilter('product.isCloseout', true),

            // defines the values which will be added as currentFilter to the result
            $filtered
        );

        // Add your custom filter
        $filters->add($filter);
    }
}
```

## Add your filter to the Storefront UI

Well, fine - you successfully created a filter via subscriber. However, you want to enable your shop customer to use it, right? Now you need to integrate your filter in the Storefront. Let's start by searching the template file you need to extend in Shopware's Storefront. It's this one - `src/Storefront/Resources/views/storefront/component/listing/filter-panel.html.twig`.

In this template, the existing filters are contained in the block `component_filter_panel_items`. We are going to extend this block with our new filter. If you're not sure on how to customize templates in the Storefront, we got you covered with another guide:

::: info
The block `component_filter_panel_items` is available from Shopware Version 6.4.8.0
:::

Including our filter will be done as seen below, please take the comments into account:

```twig
// <plugin root>/src/Resources/views/storefront/component/listing/filter-panel.html.twig
{% sw_extends '@Storefront/storefront/component/listing/filter-panel.html.twig' %}

{% block component_filter_panel_items %}
    {{ parent() }}

    {# We'll include our filter element here #}
    {% sw_include '@Storefront/storefront/component/listing/filter/filter-boolean.html.twig' with {
        name: 'isCloseout',
        displayName: 'Closeout'
    } %}
{% endblock %}
```

As we want to filter a boolean value, we choose the `filter-boolean` component here. Sure, there are some more you can use - dependent on your filter's values:

| Name | Description |
| :--- | :--- |
| `filter-boolean` | A filter to display boolean values |
| `filter-multi-select` | Filters with multiple values |
| `filter-property-select` | A filter tailored specifically for properties |
| `filter-range` | Displays a range which can be used for filtering |
| `filter-rating-select` and `filter-rating-select-item` | Filter component for rating |

Extending `component_filter_panel_items` as shown above puts our filter *after* the already existing ones. We could put it at the beginning by moving the `parent()` call to the end of the block.

If we instead want our filter to be placed before or after a specific filter in the middle of the list, we can instead extend the block for that filter. For example, if we want our filter to be displayed after the price filter, we would extend the block `component_filter_panel_item_price`:

```twig
// <plugin root>/src/Resources/views/storefront/component/listing/filter-panel.html.twig
{% sw_extends '@Storefront/storefront/component/listing/filter-panel.html.twig' %}

{% block component_filter_panel_item_price %}
    {{ parent() }}

    {# We'll include our filter element here #}
    {% sw_include '@Storefront/storefront/component/listing/filter/filter-boolean.html.twig' with {
        name: 'isCloseout',
        displayName: 'Closeout'
    } %}
{% endblock %}
```

## Next steps

To add [custom sorting options](../howto/add-custom-sorting-product-listing.md) to your listing in the Storefront, head over to the corresponding guide.

---

---
url: /docs/v6.5/guides/plugins/plugins/storefront/add-listing-filters.md
---

# Add Custom Listing Filters

## Overview

In an online shop, filters are an important feature. So you might use filters in your custom plugin. This guide will get you covered on how to implement your own, custom filters in Shopware's Storefront.

## Prerequisites

Before you start reading this guide, make sure you got an own plugin installed to work with. If you need a starting point for that, see this guide:

## Create new Filter

At first, you need to create a subscriber. In this example, we will call it `ExampleListingSubscriber`. If you are not sure on working with subscribers, please refer to the guide on working with events in Shopware:

As usual, we will start by creating this new class in the same path as you're seeing in Shopware's core - `/src/Subscriber/ExampleListingSubscriber.php`.

New listing filters, e.g. for your product listing, can be registered via the event `\Shopware\Core\Content\Product\Events\ProductListingCollectFilterEvent` This event was introduced to enable every developer to specify the metadata for a filter. The handling, meaning if and how a filter is added, is done by Shopware's core:

```php
    public static function getSubscribedEvents(): array
    {
        return [
            ProductListingCollectFilterEvent::class => 'addFilter'
        ];
    }
```

After that, you can start to actually add your custom filters. Arguably an important step is to define your filter. Therefore, you're able to use the `Filter` class, including the parameters below:

| Parameter | Description |
| :--- | :--- |
| `name` | Unique name of the filter |
| `filtered` | Set this option to `true` if this filter is active |
| `aggregations` | Defines aggregations behind a filter. Sometimes a filter contains multiple aggregations like properties |
| `filter` | Sets the DAL filter which should be added to the criteria |
| `values` | Defines the values which will be added as `currentFilter` to the result |
| `exclude` | Configure exclusions |

As a result, an example filter could look like this:

```php
$filter = new Filter(
    // name
    'manufacturer',

    // filtered
    !empty($ids),

    // aggregations
    [new EntityAggregation('manufacturer', 'product.manufacturerId', 'product_manufacturer')],

    // filter
    new EqualsAnyFilter('product.manufacturerId', $ids),

    // values
    $ids
);
```

Inside the `ProductListingCollectFilterEvent`, you get the existing filters, can define your new custom filters and merge them into the existing ones. Here is a complete example implementation, adding a filter on the product information `isCloseout`. Please note the comments for explanation:

```php
// <plugin root>/src/Subscriber/ExampleListingSubscriber.php
class ExampleListingSubscriber implements EventSubscriberInterface
{
    // register event
    public static function getSubscribedEvents(): array
    {
        return [
            ProductListingCollectFilterEvent::class => 'addFilter'
        ];
    }

    public function addFilter(ProductListingCollectFilterEvent $event): void
    {
        // fetch existing filters
        $filters = $event->getFilters();
        $request = $event->getRequest();

        $filtered = (bool) $request->get('isCloseout');

        $filter = new Filter(
            // unique name of the filter
            'isCloseout',

            // defines if this filter is active
            $filtered,

            // Defines aggregations behind a filter. A filter can contain multiple aggregations like properties
            [
                new FilterAggregation(
                    'active-filter',
                    new MaxAggregation('active', 'product.isCloseout'),
                    [new EqualsFilter('product.isCloseout', true)]
                ),
            ],

            // defines the DAL filter which should be added to the criteria   
            new EqualsFilter('product.isCloseout', true),

            // defines the values which will be added as currentFilter to the result
            $filtered
        );

        // Add your custom filter
        $filters->add($filter);
    }
}
```

## Add your filter to the Storefront UI

Well, fine - you successfully created a filter via subscriber. However, you want to enable your shop customer to use it, right? Now you need to integrate your filter in the Storefront. Let's start by searching the template file you need to extend in Shopware's Storefront. It's this one - `src/Storefront/Resources/views/storefront/component/listing/filter-panel.html.twig`.

In this template, the existing filters are contained in the block `component_filter_panel_items`. We are going to extend this block with our new filter. If you're not sure on how to customize templates in the Storefront, we got you covered with another guide:

::: info
The block `component_filter_panel_items` is available from Shopware Version 6.4.8.0
:::

Including our filter will be done as seen below, please take the comments into account:

```twig
// <plugin root>/src/Resources/views/storefront/component/listing/filter-panel.html.twig
{% sw_extends '@Storefront/storefront/component/listing/filter-panel.html.twig' %}

{% block component_filter_panel_items %}
    {{ parent() }}

    {# We'll include our filter element here #}
    {% sw_include '@Storefront/storefront/component/listing/filter/filter-boolean.html.twig' with {
        name: 'isCloseout',
        displayName: 'Closeout'
    } %}
{% endblock %}
```

As we want to filter a boolean value, we choose the `filter-boolean` component here. Sure, there are some more you can use - dependent on your filter's values:

| Name | Description |
| :--- | :--- |
| `filter-boolean` | A filter to display boolean values |
| `filter-multi-select` | Filters with multiple values |
| `filter-property-select` | A filter tailored specifically for properties |
| `filter-range` | Displays a range which can be used for filtering |
| `filter-rating-select` and `filter-rating-select-item` | Filter component for rating |

Extending  `component_filter_panel_items` as shown above puts our filter *after* the already existing ones. We could put it at the beginning by moving the `parent()` call to the end of the block.

If we instead want our filter to be placed before or after a specific filter in the middle of the list, we can instead extend the block for that filter. For example, if we want our filter to be displayed after the price filter, we would extend the block `component_filter_panel_item_price`:

```twig
// <plugin root>/src/Resources/views/storefront/component/listing/filter-panel.html.twig
{% sw_extends '@Storefront/storefront/component/listing/filter-panel.html.twig' %}

{% block component_filter_panel_item_price %}
    {{ parent() }}

    {# We'll include our filter element here #}
    {% sw_include '@Storefront/storefront/component/listing/filter/filter-boolean.html.twig' with {
        name: 'isCloseout',
        displayName: 'Closeout'
    } %}
{% endblock %}
```

## Next steps

To add [custom sorting options](add-custom-sorting-product-listing) to your listing in the Storefront, head over to the corresponding guide.

---

---
url: /docs/v6.6/guides/plugins/plugins/storefront/add-listing-filters.md
---

# Add Custom Listing Filters

## Overview

In an online shop, filters are an important feature. So you might use filters in your custom plugin. This guide will get you covered on how to implement your own, custom filters in Shopware's Storefront.

## Prerequisites

Before you start reading this guide, make sure you got an own plugin installed to work with. If you need a starting point for that, see this guide:

## Create new Filter

At first, you need to create a subscriber. In this example, we will call it `ExampleListingSubscriber`. If you are not sure on working with subscribers, please refer to the guide on working with events in Shopware:

As usual, we will start by creating this new class in the same path as you're seeing in Shopware's core - `/src/Subscriber/ExampleListingSubscriber.php`.

New listing filters, e.g. for your product listing, can be registered via the event `\Shopware\Core\Content\Product\Events\ProductListingCollectFilterEvent` This event was introduced to enable every developer to specify the metadata for a filter. The handling, meaning if and how a filter is added, is done by Shopware's core:

```php
    public static function getSubscribedEvents(): array
    {
        return [
            ProductListingCollectFilterEvent::class => 'addFilter'
        ];
    }
```

After that, you can start to actually add your custom filters. Arguably an important step is to define your filter. Therefore, you're able to use the `Filter` class, including the parameters below:

| Parameter | Description |
| :--- | :--- |
| `name` | Unique name of the filter |
| `filtered` | Set this option to `true` if this filter is active |
| `aggregations` | Defines aggregations behind a filter. Sometimes a filter contains multiple aggregations like properties |
| `filter` | Sets the DAL filter which should be added to the criteria |
| `values` | Defines the values which will be added as `currentFilter` to the result |
| `exclude` | Configure exclusions |

As a result, an example filter could look like this:

```php
$filter = new Filter(
    // name
    'manufacturer',

    // filtered
    !empty($ids),

    // aggregations
    [new EntityAggregation('manufacturer', 'product.manufacturerId', 'product_manufacturer')],

    // filter
    new EqualsAnyFilter('product.manufacturerId', $ids),

    // values
    $ids
);
```

Inside the `ProductListingCollectFilterEvent`, you get the existing filters, can define your new custom filters and merge them into the existing ones. Here is a complete example implementation, adding a filter on the product information `isCloseout`. Please note the comments for explanation:

```php
// <plugin root>/src/Subscriber/ExampleListingSubscriber.php
class ExampleListingSubscriber implements EventSubscriberInterface
{
    // register event
    public static function getSubscribedEvents(): array
    {
        return [
            ProductListingCollectFilterEvent::class => 'addFilter'
        ];
    }

    public function addFilter(ProductListingCollectFilterEvent $event): void
    {
        // fetch existing filters
        $filters = $event->getFilters();
        $request = $event->getRequest();

        $filtered = (bool) $request->get('isCloseout');

        $filter = new Filter(
            // unique name of the filter
            'isCloseout',

            // defines if this filter is active
            $filtered,

            // Defines aggregations behind a filter. A filter can contain multiple aggregations like properties
            [
                new FilterAggregation(
                    'active-filter',
                    new MaxAggregation('active', 'product.isCloseout'),
                    [new EqualsFilter('product.isCloseout', true)]
                ),
            ],

            // defines the DAL filter which should be added to the criteria   
            new EqualsFilter('product.isCloseout', true),

            // defines the values which will be added as currentFilter to the result
            $filtered
        );

        // Add your custom filter
        $filters->add($filter);
    }
}
```

## Add your filter to the Storefront UI

Well, fine - you successfully created a filter via subscriber. However, you want to enable your shop customer to use it, right? Now you need to integrate your filter in the Storefront. Let's start by searching the template file you need to extend in Shopware's Storefront. It's this one - `src/Storefront/Resources/views/storefront/component/listing/filter-panel.html.twig`.

In this template, the existing filters are contained in the block `component_filter_panel_items`. We are going to extend this block with our new filter. If you're not sure on how to customize templates in the Storefront, we got you covered with another guide:

::: info
The block `component_filter_panel_items` is available from Shopware Version 6.4.8.0
:::

Including our filter will be done as seen below, please take the comments into account:

```twig
// <plugin root>/src/Resources/views/storefront/component/listing/filter-panel.html.twig
{% sw_extends '@Storefront/storefront/component/listing/filter-panel.html.twig' %}

{% block component_filter_panel_items %}
    {{ parent() }}

    {# We'll include our filter element here #}
    {% sw_include '@Storefront/storefront/component/listing/filter/filter-boolean.html.twig' with {
        name: 'isCloseout',
        displayName: 'Closeout'
    } %}
{% endblock %}
```

As we want to filter a boolean value, we choose the `filter-boolean` component here. Sure, there are some more you can use - dependent on your filter's values:

| Name | Description |
| :--- | :--- |
| `filter-boolean` | A filter to display boolean values |
| `filter-multi-select` | Filters with multiple values |
| `filter-property-select` | A filter tailored specifically for properties |
| `filter-range` | Displays a range which can be used for filtering |
| `filter-rating-select` and `filter-rating-select-item` | Filter component for rating |

Extending  `component_filter_panel_items` as shown above puts our filter *after* the already existing ones. We could put it at the beginning by moving the `parent()` call to the end of the block.

If we instead want our filter to be placed before or after a specific filter in the middle of the list, we can instead extend the block for that filter. For example, if we want our filter to be displayed after the price filter, we would extend the block `component_filter_panel_item_price`:

```twig
// <plugin root>/src/Resources/views/storefront/component/listing/filter-panel.html.twig
{% sw_extends '@Storefront/storefront/component/listing/filter-panel.html.twig' %}

{% block component_filter_panel_item_price %}
    {{ parent() }}

    {# We'll include our filter element here #}
    {% sw_include '@Storefront/storefront/component/listing/filter/filter-boolean.html.twig' with {
        name: 'isCloseout',
        displayName: 'Closeout'
    } %}
{% endblock %}
```

## Next steps

To add [custom sorting options](add-custom-sorting-product-listing) to your listing in the Storefront, head over to the corresponding guide.

---

---
url: /docs/v6.5/guides/plugins/plugins/content/media/add-custom-file-extension.md
---

# Add Custom Media File Extension

## Overview

You might have come across the fact, that you cannot just upload any type of media to Shopware by using the Media
module in the Administration.
If that's the case for you, this guide will be the solution.
It will provide an explanation on how you can add new allowed file extensions to Shopware using a plugin.

## Prerequisites

As most of our plugin guides, this guide was also built upon our [Plugin base guide](../../plugin-base-guide).
Furthermore, you'll have to know about adding classes to the [Dependency injection](../../plugin-fundamentals/dependency-injection) container
and about using a subscriber in order to [Listen to events](../../plugin-fundamentals/listening-to-events).

## Adding a custom extension

In this section, we're going to take care of allowing a new extension to Shopware first, without letting Shopware know
exactly what kind of file this new extension represents (Images, videos, documents, ...).

For this to work, all you have to do is to register to the `MediaFileExtensionWhitelistEvent` event, which can be found
[here](https://github.com/shopware/shopware/blob/v6.4.0.0/src/Core/Content/Media/File/FileSaver.php#L397-L398).
This is of course done via a [subscriber](../../plugin-fundamentals/listening-to-events).

Have a look at the following code example:

```php
// <plugin root>/src/Service/Subscriber.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Content\Media\Event\MediaFileExtensionWhitelistEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class Subscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            MediaFileExtensionWhitelistEvent::class => 'addEntryToFileExtensionWhitelist'
        ];
    }

    public function addEntryToFileExtensionWhitelist(MediaFileExtensionWhitelistEvent $event): void
    {
        $whiteList = $event->getWhitelist();
        $whiteList[] = 'img';

        $event->setWhitelist($whiteList);
    }
}
```

You can use the method `getWhitelist` of the `$event` variable to get the current whitelist, which is just a plain array of extensions.
Therefore you can add new array entries and then set the array back to the `$event` instance by using the respective setter method
`setWhitelist`.

And that's it already! Shopware will now allow uploading files with the extension `.img`.

## Recognising the new extension

There is another thing you most likely want to do here.
While you can add new extensions like mentioned above, Shopware does not automatically recognise which kind of extension it is dealing with.
Is it a new image extension and should be displayed as such? Is it a video file extension? Maybe a new kind of document?

In order to let Shopware know which kind of type we're dealing with, you can add a new `TypeDetector` class
to let Shopware know about your new extension.

In the following example we'll imagine that we've added a new **image** extension called `img`, like we did above, and we're going to let Shopware know
about it.

What we'll be doing now, is to add a custom `TypeDetector` class which returns an `ImageType` if the extension of the file to be checked matches our type detector.
Have a look at the following example:

```php
// <plugin root>/src/Core/Content/Media/TypeDetector/CustomImageTypeDetector.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Media\TypeDetector;

use Shopware\Core\Content\Media\File\MediaFile;
use Shopware\Core\Content\Media\MediaType\ImageType;
use Shopware\Core\Content\Media\MediaType\MediaType;
use Shopware\Core\Content\Media\TypeDetector\TypeDetectorInterface;

class CustomImageTypeDetector implements TypeDetectorInterface
{
    protected const SUPPORTED_FILE_EXTENSIONS = [
        'img' => [ImageType::TRANSPARENT],
    ];

    public function detect(MediaFile $mediaFile, ?MediaType $previouslyDetectedType): ?MediaType
    {
        $fileExtension = mb_strtolower($mediaFile->getFileExtension());
        if (!\array_key_exists($fileExtension, self::SUPPORTED_FILE_EXTENSIONS)) {
            return $previouslyDetectedType;
        }

        if ($previouslyDetectedType === null) {
            $previouslyDetectedType = new ImageType();
        }

        $previouslyDetectedType->addFlags(self::SUPPORTED_FILE_EXTENSIONS[$fileExtension]);

        return $previouslyDetectedType;
    }
}
```

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Core\Content\Media\TypeDetector\CustomImageTypeDetector">
            <tag name="shopware.media_type.detector" priority="10"/>
        </service>
    </services>
</container>
```

You will have to create a new class which implements from the interface `TypeDetectorInterface`.
This will come with the requirement of having a `detect` method, which will return the respective media type.

Inside of the `detect` method, we're first checking if the file extension matches our allowed extensions, in this case only
`img`.
If that's not the case, just return the `$previouslyDetectedType`, which most likely comes from the `DefaultTypeDetector` and which
tried to detect the type already by analysing the file's MIME-type.

If the extension does indeed match, we're for sure going to return `ImageType` here.
Make sure to add flags to your media type, e.g. the `transparent` flag, or if it's an animated image.

You can find all available flags in their respective media type classes,
e.g. [here](https://github.com/shopware/shopware/blob/v6.4.0.0/src/Core/Content/Media/MediaType/ImageType.php#L7-L10) for the image media type.

Make sure to register your new type detector to the [Dependency injection container](../../plugin-fundamentals/dependency-injection)
by using the tag `shopware.media_type.detector`.

Shopware will now recognise your new image extension and handle your new file like an image.

---

---
url: /docs/v6.6/guides/plugins/plugins/content/media/add-custom-file-extension.md
---

# Add Custom Media File Extension

## Overview

You might have come across the fact, that you cannot just upload any type of media to Shopware by using the Media
module in the Administration.
If that's the case for you, this guide will be the solution.
It will provide an explanation on how you can add new allowed file extensions to Shopware using a plugin.

## Prerequisites

As most of our plugin guides, this guide was also built upon our [Plugin base guide](../../plugin-base-guide).
Furthermore, you'll have to know about adding classes to the [Dependency injection](../../plugin-fundamentals/dependency-injection) container
and about using a subscriber in order to [Listen to events](../../plugin-fundamentals/listening-to-events).

## Adding a custom extension

In this section, we're going to take care of allowing a new extension to Shopware first, without letting Shopware know
exactly what kind of file this new extension represents (Images, videos, documents, ...).

For this to work, all you have to do is to register to the `MediaFileExtensionWhitelistEvent` event, which can be found
[here](https://github.com/shopware/shopware/blob/v6.4.0.0/src/Core/Content/Media/File/FileSaver.php#L397-L398).
This is of course done via a [subscriber](../../plugin-fundamentals/listening-to-events).

Have a look at the following code example:

```php
// <plugin root>/src/Service/Subscriber.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Content\Media\Event\MediaFileExtensionWhitelistEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class Subscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            MediaFileExtensionWhitelistEvent::class => 'addEntryToFileExtensionWhitelist'
        ];
    }

    public function addEntryToFileExtensionWhitelist(MediaFileExtensionWhitelistEvent $event): void
    {
        $whiteList = $event->getWhitelist();
        $whiteList[] = 'img';

        $event->setWhitelist($whiteList);
    }
}
```

You can use the method `getWhitelist` of the `$event` variable to get the current whitelist, which is just a plain array of extensions.
Therefore you can add new array entries and then set the array back to the `$event` instance by using the respective setter method
`setWhitelist`.

And that's it already! Shopware will now allow uploading files with the extension `.img`.

## Recognising the new extension

There is another thing you most likely want to do here.
While you can add new extensions like mentioned above, Shopware does not automatically recognise which kind of extension it is dealing with.
Is it a new image extension and should be displayed as such? Is it a video file extension? Maybe a new kind of document?

In order to let Shopware know which kind of type we're dealing with, you can add a new `TypeDetector` class
to let Shopware know about your new extension.

In the following example we'll imagine that we've added a new **image** extension called `img`, like we did above, and we're going to let Shopware know
about it.

What we'll be doing now, is to add a custom `TypeDetector` class which returns an `ImageType` if the extension of the file to be checked matches our type detector.
Have a look at the following example:

```php
// <plugin root>/src/Core/Content/Media/TypeDetector/CustomImageTypeDetector.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Media\TypeDetector;

use Shopware\Core\Content\Media\File\MediaFile;
use Shopware\Core\Content\Media\MediaType\ImageType;
use Shopware\Core\Content\Media\MediaType\MediaType;
use Shopware\Core\Content\Media\TypeDetector\TypeDetectorInterface;

class CustomImageTypeDetector implements TypeDetectorInterface
{
    protected const SUPPORTED_FILE_EXTENSIONS = [
        'img' => [ImageType::TRANSPARENT],
    ];

    public function detect(MediaFile $mediaFile, ?MediaType $previouslyDetectedType): ?MediaType
    {
        $fileExtension = mb_strtolower($mediaFile->getFileExtension());
        if (!\array_key_exists($fileExtension, self::SUPPORTED_FILE_EXTENSIONS)) {
            return $previouslyDetectedType;
        }

        if ($previouslyDetectedType === null) {
            $previouslyDetectedType = new ImageType();
        }

        $previouslyDetectedType->addFlags(self::SUPPORTED_FILE_EXTENSIONS[$fileExtension]);

        return $previouslyDetectedType;
    }
}
```

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Core\Content\Media\TypeDetector\CustomImageTypeDetector">
            <tag name="shopware.media_type.detector" priority="10"/>
        </service>
    </services>
</container>
```

You will have to create a new class which implements from the interface `TypeDetectorInterface`.
This will come with the requirement of having a `detect` method, which will return the respective media type.

Inside of the `detect` method, we're first checking if the file extension matches our allowed extensions, in this case only
`img`.
If that's not the case, just return the `$previouslyDetectedType`, which most likely comes from the `DefaultTypeDetector` and which
tried to detect the type already by analysing the file's MIME-type.

If the extension does indeed match, we're for sure going to return `ImageType` here.
Make sure to add flags to your media type, e.g. the `transparent` flag, or if it's an animated image.

You can find all available flags in their respective media type classes,
e.g. [here](https://github.com/shopware/shopware/blob/v6.4.0.0/src/Core/Content/Media/MediaType/ImageType.php#L7-L10) for the image media type.

Make sure to register your new type detector to the [Dependency injection container](../../plugin-fundamentals/dependency-injection)
by using the tag `shopware.media_type.detector`.

Shopware will now recognise your new image extension and handle your new file like an image.

---

---
url: /docs/guides/plugins/plugins/content/media/add-custom-file-extension.md
---

# Add Custom Media File Extensions

## Overview

Not all media types can be uploaded to Shopware with the Administration's Media module. This guide explains how to use plugins to add custom media file extensions.

## Prerequisites

Review these guides before proceeding:

* [Plugin base guide](../../plugin-base-guide.md)
* [Dependency injection](../../services/dependency-injection.md), to learn how to add classes to the container
* [Listen to events](../../framework/event/listening-to-events.md), for guidance on using subscribers

## Adding a custom extension

In this section, we're going to allow a new extension to Shopware first, without letting Shopware know exactly what kind of file this new extension represents (Images, videos, documents, etc.).

For this to work, use a [subscriber](../../framework/event/listening-to-events.md) to register for the `MediaFileExtensionWhitelistEvent` event found [here](https://github.com/shopware/shopware/blob/v6.4.0.0/src/Core/Content/Media/File/FileSaver.php#L397-L398).

Have a look at the following code example:

```php
// <plugin root>/src/Service/Subscriber.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Content\Media\Event\MediaFileExtensionWhitelistEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class Subscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            MediaFileExtensionWhitelistEvent::class => 'addEntryToFileExtensionWhitelist'
        ];
    }

    public function addEntryToFileExtensionWhitelist(MediaFileExtensionWhitelistEvent $event): void
    {
        $whiteList = $event->getWhitelist();
        $whiteList[] = 'img';

        $event->setWhitelist($whiteList);
    }
}
```

You can use the method `getWhitelist` of the `$event` variable to get the current allowlist, which is just a plain array of extensions.
Therefore, you can add new array entries and then set the array back to the `$event` instance by using the respective setter method
`setWhitelist`.

And that's it already! Shopware now allows uploading files with the `.img` extension.

## Recognising the new extension

There is another thing you most likely want to do here.
While you can add new extensions as mentioned above, Shopware does not automatically recognise the type of extension it is dealing with.
Is it a new image extension and should be displayed as such? Is it a video file extension? Maybe a new kind of document?

To let Shopware know which kind of type we're dealing with, you can add a new `TypeDetector` class
to let Shopware know about your new extension.

In the following example, we'll imagine that we've added a new **image** extension called `img`, like we did above, and we're going to let Shopware know
about it.

What we'll be doing now is adding a custom `TypeDetector` class that returns an `ImageType` if the file's extension matches our type detector.
Have a look at the following example:

```php
// <plugin root>/src/Core/Content/Media/TypeDetector/CustomImageTypeDetector.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Media\TypeDetector;

use Shopware\Core\Content\Media\File\MediaFile;
use Shopware\Core\Content\Media\MediaType\ImageType;
use Shopware\Core\Content\Media\MediaType\MediaType;
use Shopware\Core\Content\Media\TypeDetector\TypeDetectorInterface;

class CustomImageTypeDetector implements TypeDetectorInterface
{
    protected const SUPPORTED_FILE_EXTENSIONS = [
        'img' => [ImageType::TRANSPARENT],
    ];

    public function detect(MediaFile $mediaFile, ?MediaType $previouslyDetectedType): ?MediaType
    {
        $fileExtension = mb_strtolower($mediaFile->getFileExtension());
        if (!\array_key_exists($fileExtension, self::SUPPORTED_FILE_EXTENSIONS)) {
            return $previouslyDetectedType;
        }

        if ($previouslyDetectedType === null) {
            $previouslyDetectedType = new ImageType();
        }

        $previouslyDetectedType->addFlags(self::SUPPORTED_FILE_EXTENSIONS[$fileExtension]);

        return $previouslyDetectedType;
    }
}
```

```php
// <plugin root>/src/Resources/config/services.php
<?php declare(strict_types=1);

use Swag\BasicExample\Core\Content\Media\TypeDetector\CustomImageTypeDetector;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(CustomImageTypeDetector::class)
        ->tag('shopware.media_type.detector', ['priority' => 10]);
};
```

You will need to create a new class that implements the `TypeDetectorInterface` interface.
This will come with the requirement of having a `detect` method, which will return the respective media type.

Inside the `detect` method, we're first checking if the file extension matches our allowed extensions, in this case, only
`img`.
If that's not the case, just return the `$previouslyDetectedType`, which most likely comes from the `DefaultTypeDetector` and which
tried to detect the type already by analysing the file's MIME-type.

If the extension does match, we're definitely going to return `ImageType` here.
Make sure to add flags to your media type, e.g., the `transparent` flag, or if it's an animated image.

You can find all available flags in their respective media type classes,
e.g. [here](https://github.com/shopware/shopware/blob/v6.4.0.0/src/Core/Content/Media/MediaType/ImageType.php#L7-L10) for the image media type.

Make sure to register your new type detector to the [Dependency injection container](../../services/dependency-injection.md) by using the tag `shopware.media_type.detector`.

Shopware will now recognise your new image extension and handle your new file like an image.

## Public vs private media

Shopware uses **two separate extension allowlists** depending on whether the media is public or private:

| Allowlist | Configuration parameter | When used |
|-----------|-------------------------|-----------|
| **Public** | `shopware.filesystem.allowed_extensions` | Media stored in the public filesystem (product images, CMS assets, etc.). Files are accessible via URL. |
| **Private** | `shopware.filesystem.private_allowed_extensions` | Media stored in the private filesystem (digital product downloads, documents, etc.). Files are not directly accessible via URL and require authentication to download. |

The `MediaFileExtensionWhitelistEvent` is dispatched with one of these allowlists depending on whether the media being uploaded is marked as private. Your subscriber receives the appropriate allowlist each time.

If your custom extension should work for both public and private media, add it to your subscriber. The same logic applies to both allowlists, since the event is fired separately for each upload context.

## Media types

When implementing a `TypeDetector`, you must return the correct `MediaType` for your extension. The following types are available:

| MediaType class | Purpose |
|-----------------|---------|
| `ImageType` | Images (jpg, png, etc.). Supports thumbnails and flags such as `transparent`, `animated`, and `vectorGraphic`. |
| `VideoType` | Video files (mp4, webm, etc.). **Note:** Not all browsers support all video formats. Shopware displays a warning in the Administration about formats that may not be playable everywhere (e.g., MOV, AVI, WMV). |
| `AudioType` | Audio files (mp3, wav, etc.). **Note:** Not all browsers support all audio formats. Shopware displays a warning in the Administration about formats that may not be playable everywhere (e.g., FLAC, AAC, WMA). |
| `DocumentType` | Documents (PDF, DOC, etc.). |
| `SpatialObjectType` | 3D/spatial files (e.g. GLB). |
| `BinaryType` | Fallback for unknown or generic file types. |

Choose the type that best matches how Shopware should handle your custom extension (e.g., image thumbnails, document previews).

---

---
url: /docs/v6.5/guides/plugins/apps/administration/add-custom-modules.md
---

# Add custom module

:::info
This guide will show you how to add custom modules to the Shopware Administration using your manifest file. This works for simple applications; however, if you want to write more advanced applications, the [Meteor Admin SDK](https://shopware.github.io/meteor-admin-sdk/) is recommended. It has many more features and is more flexible.

For further details and guidance on custom modules, refer to the documentation provided on the Meteor Admin SDK's [custom modules](https://shopware.github.io/meteor-admin-sdk/docs/guide/api-reference/ui/mainModule) section.
:::

## Overview

In your app, you are able to add your own modules to the Administration. Your custom modules are loaded as iframes which are embedded in the Shopware Administration and within this iframe, your website will be loaded and shown.

Creating custom modules takes place at the `<admin>` section of your `manifest.xml`. Take a look at the [Manifest Reference](../../../../resources/references/app-reference/manifest-reference) You can add any amount of custom modules by adding new `<module>` elements to your manifest.

To configure your module, you can set it up with with some additional attributes.

* `name` (required): The technical name of the module. This is the name your module is referenced with.
* `parent` (required): The Administration navigation id of the menu item that serves as the parent menu item.
* `source` (optional): The URL to your app servers endpoint from which the module is served from. This can be omitted if you want to define a menu item that should serve as a parent menu item for other app modules.
* `parent` (optional): The Administration navigation id from the menu item that serves as the parent menu item. If omitted your module will be listed under the "My apps" menu entry. **This field will be required in future versions as we are going to remove the "My Apps" menu item**
* `position` (optional): A numeric index that sets the position of your menu entry regarding to it's siblings.

Additionally you can define `label` elements inside of your `module` element, to set up how your module will be displayed in the admin menu.

```xml
// manifest.xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        ...
    </meta>
    <admin>
        <module name="exampleModule"
                source="https://example.com/promotion/view/promotion-module"
                parent="sw-marketing"
                position="50"
        >
            <label>Example module</label>
            <label lang="de-DE">Beispiel Modul</label>
        </module>
    </admin>
</manifest>
```

For a complete reference of the structure of the manifest file, take a look at the [Manifest reference](../../../../resources/references/app-reference/manifest-reference).

If the user opens the module in the Administration your app will receive a request to the URL defined in the `source` attribute of your `module` element. Your app can determine the shop that has opened the module through query parameters added to the url:

* `shop-id`: The unique identifier of the shop, where the app was installed
* `shop-url`: The URL of the shop, this can later be used to access the Shopware API
* `timestamp`: The Unix timestamp when the request was created
* `shopware-shop-signature`: SHA256 HMAC of the rest of the query string, signed with the `shop-secret`

A sample request may look like this:

```text
https://example.com/promotion/view/promotion-config?shop-id=HKTOOpH9nUQ2&shop-url=http%3A%2F%2Fmy.shop.com&timestamp=1592406102&shopware-shop-signature=3621fffa80187f6d43ce6cb25760340ab9ba2ea2f601e6a78a002e601579f415
```

In this case the `shopware-shop-signature` parameter contains an SHA256 HMAC of the rest of the query string, signed again with the secret your app assigned the shop during the [registration](../app-base-guide#setup). The signature can be used to verify the authenticity of the request.

```php
// injected or build by yourself
$shopResolver = new ShopResolver($repository);
$contextResolver = new ContextResolver();

$shop = $shopResolver->resolveShop($serverRequest);
$module = $contextResolver->assembleModule($serverRequest, $shop);
```

```php
use Shopware\App\SDK\Context\Module\ModuleAction;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\AsController;
use Symfony\Component\Routing\Annotation\Route;

#[AsController]
class ModuleController {
    #[Route('/module')]
    public function show(ModuleAction $module): Response
    {
        // handle payment
        
        return $this->render('....');
    }
}
```

## Leave loading state

Because your module is displayed as an iframe in the Administration, Shopware can not easily tell when your module has finished loading. Therefore, your new module will display a loading spinner to signalize your iframe is loading. To leave the loading state, your iframe needs to give a notification when the loading process is done.

```javascript
function sendReadyState() {
    window.parent.postMessage('sw-app-loaded', '*');
}
```

This has to be done as soon as everything is loaded so that the loading spinner disappears. If your view is not fully loaded after 5 seconds, it will be aborted.

## Structure your modules

With Shopware 6.4.0.0 we added a third level in the admin menu structure. This change was made to give you as a developer the opportunity to group your Administration modules if needed.

When you define a module, it gets automatically loaded by the Administration. Additionally the Administration creates a menu entry for your module. You can reference this menu entry and set it as the parent menu entry for your other modules.

The navigation id of your modules always uses the pattern `app-<appName>-<moduleName>`. So, within your manifest you can add a reference to modules that you just created:

```xml
// manifest.xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        <name>myApp</app>
        ...
    </meta>
    <admin>
        <module name="myModules"
                source="https://example.com/promotion/view/promotion-module"
                parent="sw-catalogue"
                position="50"
        >
            <label>My apps modules</label>
            <label lang="de-DE">Module meiner app</label>
        </module>

        <module name="someModule"
                source="https://example.com/promotion/view/promotion-module"
                parent="app-myApp-myModules"
                position="1"
        >
            <label>Module underneath "My apps modules"</label>
            <label lang="de-DE">Modul unterhalb von "Module meiner app"</label>
        </module>
    </admin>
</manifest>
```

Modules that are used as a parent for other modules do not need the `source` attribute to be set, although they can.

## Add main module to your app

With Shopware 6.4.0.0 You can define a main module for your app. This "special" module will be opened from the list of your installed apps as well as from the app detail page if you bought it from the Shopware store.

Your main module can be defined by adding a `main-module` element within your `administration` section of your manifest file. It's only required attribute is the `source` attribute.

To avoid mixing other modules with your main module, we decided to separate the main module from modules with navigation entries. You can still use the same URL on both, a module that is available through the menu and your main module.

```xml
// manifest.xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        <name>myApp</app>
        ...
    </meta>
    <admin>
        <module name="normalModule"
                source="https://example.com/main"
                parent="sw-catalogue"
                position="50"
        >
            <label>Module in admin menu</label>
            <label lang="de-DE">Modul im Adminmenü</label>
        </module>

        <!-- You can use the same url to open your module from the app store -->
        <main-module source="https://example.com/main"/>
    </admin>
</manifest>
```

This feature is not compatible with themes as they will always open the theme config by default.

## Admin design compatibility

As your module page is integrated as an iframe you are not able to use the stylesheet and javascript out of the box.
Having the stylesheets that are used in the Administration can be beneficial for the app module to seamlessly integrate into the Administration.
You can use the shop version that is passed as `sw-version` within the request query to determine what stylesheets you want to load.
The compiled Administration stylesheets for each version can be found within the tagged releases of the `shopware/administration` package within the `Resources/public/static` folder.
Combining this information enables your app to look exactly like the Administration, although it is encapsulated within an iframe.

---

---
url: /docs/v6.5/guides/plugins/plugins/administration/add-custom-module.md
---

# Add custom module

In the `Administration` core code, each module is defined in a directory called `module`.
Inside the `module` directory lies the list of several modules, each having their own directory named after the module itself.

## Prerequisites

This guide **does not** explain how to create a new plugin for Shopware 6.
Head over to our Plugin base guide to learn how to create a plugin at first:

## Creating the index.js file

The first step is creating a new directory `<plugin root>/src/Resources/app/administration/src/module/swag-example`, so you can store your own modules files in there.
Right afterwards, create a new file called `index.js` in there. Consider it to be the main file for your custom module.

::: warning
This is necessary, because Shopware 6 is automatically requiring an `index.js` file for each module.
:::

Your custom module directory isn't known to Shopware 6 yet.
The entry point of your plugin is the `main.js` file.
That's the file you need to change now, so that it loads your new module.
For this, simply add the following line to your `main.js` file:

```javascript
// <plugin root>/src/Resources/app/administration/src/main.js
import './module/swag-example';
```

Now your module's `index.js` will be executed.

## Registering the module

Your `index.js` is still empty now, so let's get going to actually create a new module.
This is technically done by calling the method `registerModule` method of our [ModuleFactory](https://github.com/shopware/shopware/blob/trunk/src/Administration/Resources/app/administration/src/core/factory/module.factory.ts), but you're not going to use this directly.

Instead, you're using the `Shopware.Module.register()` method, but why is that?

`Shopware` is a [global object](the-shopware-object) created for third party developers.
It is mainly the bridge between the Shopware Administration and our plugin.
The `Module` object comes with a `register` helper method to easily register your module.
The method needs two parameters to be set, the first one being the module's name, the second being a javascript object, which contains your module's configuration.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/swag-example/index.js
Shopware.Module.register('swag-example', {
    // configuration here
});
```

## Configuring the module

In this file, you can configure a couple of things, e.g. the color of your module.
Each module needs a primary color, which will be used on specific accents and locations throughout your module.
To name a few, it's the color of the main icon of the module, the tag in the global search input and the accent color of the smart bar.

In this example `#ff3d58` is used as a color, which is a soft red.
Also, each module has their own icon. You can see here [here](https://component-library.shopware.com/icons/) which icons are available in Shopware 6 by default.
In our case here, let's say we use the icon `default-shopping-paper-bag-product`, which will also be used for the module.

::: danger
This is not the icon being used for a menu entry! The icon for that needs to be configured separately.
Please refer to the [Add a menu entry](add-menu-entry) guide for more information on this topic.
:::

In addition, you're able to configure a title here, which will be used for the actual browser title.
Just add a string for the key `title`.
This will be the default title for your module, you can edit this for each component later on.

The `description` is last basic information you should set here, which will be shown as an empty-state.
That means the description will be shown e.g. when you integrated a list component, but your list is empty as of now.
In that case, your module's description will be displayed instead.

Another important aspect are the routes which your module is going to use, such as e.g. `swag-example-list` for the list of your module, `swag-example-detail` for the detail page and `swag-example-create` for creating a new entry.
Those routes are configured as an object in a property named `routes`. We will cover that in the next paragraph.

## Setting up menu entry and routes

The next steps are covered in their own guides. The first one would be adding a menu entry, so please take a look at the guide regarding:

The second one refers to setting up custom routes, its guide can be found in the guide on adding custom routes:

## Set up additional meta info

If you have been following that guide, then you should have got a menu entry then.
The related routes are also set up already and linked to components, which will be created in the next main step.
There's a few more things we need to change in the configurations though that you should add to your module, such as a unique `name` and a `type`.
For reference, see this example:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/swag-example/index.js
Shopware.Module.register('swag-example', {
    type: 'plugin',
    name: 'Example',
    title: 'swag-example.general.mainMenuItemGeneral',
    description: 'sw-property.general.descriptionTextModule',
    color: '#ff3d58',
    icon: 'default-shopping-paper-bag-product',
...
```

The `name` should be a technical unique one, the `type` would be 'plugin' here. When it comes to this `type`, there are basically two options in Shopware: `core` and `plugin`.
So every third-party module should use `plugin`.
To give a little context: Looking at `module.factory` inside `registerModule` the plugin type is the only case which is being checked and has some different behaviour.
So it is more a convention and not a real validation which throws an error when `type` is divergent to these options.

## Implementing snippets

You've already set a label for your module's menu entry.
Yet, by default the `Administration` expects the value in there to be a [Vuei18n](https://kazupon.github.io/vue-i18n/started.html#html) variable, a translation key that is.
It's looking for a translation key `example` now and since you did not provide any translations at all yet, it can't find any translation for it and will just print the key of a snippet.
Sounds like it's time to implement translation snippets as well, right?

This is done by providing a new object to your module configuration, `snippets` this time.
This object contains another object for each language you want to support.
In this example `de-DE` and of course `en-GB` will be supported.

Each language then contains a nested object of translations, so let's have a look at an example:

```json
{
    "swag-example": {
        "nested": {
            "value": "example"
        },
        "foo": "bar"
    }
}
```

In this example you would have access to two translations by the following paths: `swag-example.nested.value` to get the value 'example' and `swag-example.foo` to get the value 'bar'.
You can nest those objects as much as you want. Please note that each path is prefixed by the extension name.

Since those translation objects become rather large, you should store them into separate files.
For this purpose, create a new directory `snippet` in your module's directory and in there two new files: `de-DE.json` and `en-GB.json`

Then, when each file contains your translations as an object, you only have to import them into your module again.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/swag-example/index.js
[...]

import deDE from './snippet/de-DE';
import enGB from './snippet/en-GB';

Shopware.Module.register('swag-example', {
    ...
    snippets: {
        'de-DE': deDE,
        'en-GB': enGB
    },
});
```

Let's also create the first translation, which is for your menu's label.
It's key should be something like this: `swag-example.general.mainMenuItemGeneral`

Thus open the `snippet/en-GB.json` file and create the new object in there.
The structure here is the same as in the first example, just formatted as json file.
Afterwards, use this path in your menu entry's `label` property.

To translate the `description` or the `title`, add those to your snippet file as well and edit the values in your module's `description` and `title`.
The title will be the same as the main menu entry by default.

This should be your snippet file now:

```json
{
    "swag-example": {
        "general": {
            "mainMenuItemGeneral": "My custom module",
            "descriptionTextModule": "Manage this custom module here"
        }
    }
}
```

## Build the Administration

As mentioned above, Shopware 6 is looking for a `main.js` file in your plugin.
Its contents get minified into a new file named after your plugin and will be moved to the `public` directory of Shopware 6 root directory.
Given this plugin would be named "AdministrationNewModule", the bundled and minified javascript code for this example would be located under `<plugin root>/src/Resources/public/administration/js/administration-new-module.js`, once you run the command following command in your shopware root directory:

```bash
./bin/build-administration.sh
```

```bash
composer run build:js:admin
```

::: info
Your plugin has to be activated for this to work.
:::

Make sure to also include that file when publishing your plugin!
A copy of this file will then be put into the directory `<shopware root>/public/bundles/administration/administrationnewmodule/administration/js/administration-new-module.js`.

Your minified javascript file will now be loaded in production environments.

## Special: Case Settings

### Link your module into settings

If you think about creating a module concerning settings, you might want to link your module in the `settings` section of the Administration.
You can add the `settingsItem` option to the module configuration as seen below:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/swag-example/index.js
import './page/swag-plugin-list';
import './page/swag-plugin-detail';
Shopware.Module.register('swag-plugin', {
    ...
    settingsItem: [{
        group: 'plugin',
        to: 'swag.plugin.list',
        icon: 'default-object-rocket',
        name: 'swag-example.general.mainMenuItemGeneral'
    }]
});
```

The `group` property targets to the group section, the item will be displayed in 'shop', 'system' and 'plugins' sections.
The `to` gets the link path of the route. The `icon` contains the icon name which will be display.

### Add custom settings card

You can even provide custom setting cards that are either placed in shop, system or plugin tab.
This can be achieved by adding the key settingsItem to your module object:

```javascript
settingsItem: [{ // this can be a single object if no collection is needed
    to: 'custom.module.overview', // route to anything
    group: 'system', // either system, shop or plugins
    icon: 'default-object-lab-flask',
    iconComponent: YourCustomIconRenderingComponent, // optional, this overrides icon attribute
    id: '', // optional, fallback is taken from module
    name: '', // optional, fallback is taken from module
    label: '', // optional, fallback is taken from module
}]
```

## Example for the final module

Here's your final module:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/swag-example/index.js
import './page/swag-example-list';
import './page/swag-example-detail';
import './page/swag-example-create';
import deDE from './snippet/de-DE';
import enGB from './snippet/en-GB';

Shopware.Module.register('swag-example', {
    type: 'plugin',
    name: 'Example',
    title: 'swag-example.general.mainMenuItemGeneral',
    description: 'sw-property.general.descriptionTextModule',
    color: '#ff3d58',
    icon: 'default-shopping-paper-bag-product',

    snippets: {
        'de-DE': deDE,
        'en-GB': enGB
    },

    routes: {
        list: {
            component: 'swag-example-list',
            path: 'list'
        },
        detail: {
            component: 'swag-example-detail',
            path: 'detail/:id',
            meta: {
                parentPath: 'swag.example.list'
            }
        },
        create: {
            component: 'swag-example-create',
            path: 'create',
            meta: {
                parentPath: 'swag.example.list'
            }
        }
    },

    navigation: [{
        label: 'swag-example.general.mainMenuItemGeneral',
        color: '#ff3d58',
        path: 'swag.example.list',
        icon: 'default-shopping-paper-bag-product',
        position: 100
    }]
});
```

## Next steps

As you might have noticed, we are just adding a custom module to the module.
However, there's a lot more possible when it comes to extending the Administration.
In addition, you surely want to customize your module even more.
You may want to try the following things:

* [Add custom component](add-custom-component)
* [Add a menu entry](add-menu-entry)
* [Add a custom route](add-custom-route)
* [Add a custom service](add-custom-service)
* [Add translations](adding-snippets)
* [Customizing another module](customizing-modules)
* [Dealing with data in the Administration](using-data-handling)
* [Adding permissions to your module](add-acl-rules)

---

---
url: /docs/v6.6/guides/plugins/apps/administration/add-custom-modules.md
---

# Add custom module

:::info
This guide will show you how to add custom modules to the Shopware Administration using your manifest file. This works for simple applications; however, if you want to write more advanced applications, the [Meteor Admin SDK](/resources/admin-extension-sdk/) is recommended. It has many more features and is more flexible.

For further details and guidance on custom modules, refer to the documentation provided on the Meteor Admin SDK's [custom modules](/resources/admin-extension-sdk/api-reference/ui/mainModule) section.
:::

## Prerequisites

You should be familiar with the concept of Apps, especially their registration flow as well as signing and verifying requests and responses between Shopware and the App backend server, as that is required to authenticate the requests coming from the shops and showing the correct content in your modules.

## Overview

In your app, you are able to add your own modules to the Administration. Your custom modules are loaded as iframes which are embedded in the Shopware Administration and within this iframe, your website will be loaded and shown.

Creating custom modules takes place at the `<admin>` section of your `manifest.xml`. Take a look at the [Manifest Reference](../../../../resources/references/app-reference/manifest-reference) You can add any amount of custom modules by adding new `<module>` elements to your manifest.

To configure your module, you can set it up with with some additional attributes.

* `name` (required): The technical name of the module. This is the name your module is referenced with.
* `parent` (required): The Administration navigation id of the menu item that serves as the parent menu item.
* `source` (optional): The URL to your app servers endpoint from which the module is served from. This can be omitted if you want to define a menu item that should serve as a parent menu item for other app modules.
* `parent` (optional): The Administration navigation id from the menu item that serves as the parent menu item. If omitted your module will be listed under the "My apps" menu entry. **This field will be required in future versions as we are going to remove the "My Apps" menu item**
* `position` (optional): A numeric index that sets the position of your menu entry regarding to it's siblings.

Additionally you can define `label` elements inside of your `module` element, to set up how your module will be displayed in the admin menu.

::: code-group

```xml [manifest.xml]
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        ...
    </meta>
    <admin>
        <module name="exampleModule"
                source="https://example.com/promotion/view/promotion-module"
                parent="sw-marketing"
                position="50"
        >
            <label>Example module</label>
            <label lang="de-DE">Beispiel Modul</label>
        </module>
    </admin>
</manifest>
```

:::

For a complete reference of the structure of the manifest file, take a look at the [Manifest reference](../../../../resources/references/app-reference/manifest-reference).

If the user opens the module in the Administration your app will receive a request to the URL defined in the `source` attribute of your `module` element. Your app can determine the shop that has opened the module through query parameters added to the url:

* `shop-id`: The unique identifier of the shop, where the app was installed
* `shop-url`: The URL of the shop, this can later be used to access the Shopware API
* `timestamp`: The Unix timestamp when the request was created
* `shopware-shop-signature`: SHA256 HMAC of the rest of the query string, signed with the `shop-secret`

A sample request may look like this:

```text
https://example.com/promotion/view/promotion-config?shop-id=HKTOOpH9nUQ2&shop-url=http%3A%2F%2Fmy.shop.com&timestamp=1592406102&shopware-shop-signature=3621fffa80187f6d43ce6cb25760340ab9ba2ea2f601e6a78a002e601579f415
```

In this case the `shopware-shop-signature` parameter contains an SHA256 HMAC of the rest of the query string, signed again with the secret your app assigned the shop during the [registration](../app-base-guide#setup). The signature can be used to verify the authenticity of the request.

```php
// injected or build by yourself
$shopResolver = new ShopResolver($repository);
$contextResolver = new ContextResolver();

$shop = $shopResolver->resolveShop($serverRequest);
$module = $contextResolver->assembleModule($serverRequest, $shop);
```

```php
use Shopware\App\SDK\Context\Module\ModuleAction;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\AsController;
use Symfony\Component\Routing\Attribute\Route;

#[AsController]
class ModuleController {
    #[Route('/module')]
    public function show(ModuleAction $module): Response
    {
        // handle payment
        
        return $this->render('....');
    }
}
```

## Leave loading state

Because your module is displayed as an iframe in the Administration, Shopware can not easily tell when your module has finished loading. Therefore, your new module will display a loading spinner to signalize your iframe is loading. To leave the loading state, your iframe needs to give a notification when the loading process is done.

```javascript
function sendReadyState() {
    window.parent.postMessage('sw-app-loaded', '*');
}
```

This has to be done as soon as everything is loaded so that the loading spinner disappears. If your view is not fully loaded after 5 seconds, it will be aborted.

## Structure your modules

With Shopware 6.4.0.0 we added a third level in the admin menu structure. This change was made to give you as a developer the opportunity to group your Administration modules if needed.

When you define a module, it gets automatically loaded by the Administration. Additionally the Administration creates a menu entry for your module. You can reference this menu entry and set it as the parent menu entry for your other modules.

The navigation id of your modules always uses the pattern `app-<appName>-<moduleName>`. So, within your manifest you can add a reference to modules that you just created:

::: code-group

```xml [manifest.xml]
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        <name>myApp</app>
        ...
    </meta>
    <admin>
        <module name="myModules"
                source="https://example.com/promotion/view/promotion-module"
                parent="sw-catalogue"
                position="50"
        >
            <label>My apps modules</label>
            <label lang="de-DE">Module meiner app</label>
        </module>

        <module name="someModule"
                source="https://example.com/promotion/view/promotion-module"
                parent="app-myApp-myModules"
                position="1"
        >
            <label>Module underneath "My apps modules"</label>
            <label lang="de-DE">Modul unterhalb von "Module meiner app"</label>
        </module>
    </admin>
</manifest>
```

:::

Modules that are used as a parent for other modules do not need the `source` attribute to be set, although they can.

## Add main module to your app

With Shopware 6.4.0.0 You can define a main module for your app. This "special" module will be opened from the list of your installed apps as well as from the app detail page if you bought it from the Shopware store.

Your main module can be defined by adding a `main-module` element within your `administration` section of your manifest file. It's only required attribute is the `source` attribute.

To avoid mixing other modules with your main module, we decided to separate the main module from modules with navigation entries. You can still use the same URL on both, a module that is available through the menu and your main module.

::: code-group

```xml [manifest.xml]
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        <name>myApp</app>
        ...
    </meta>
    <admin>
        <module name="normalModule"
                source="https://example.com/main"
                parent="sw-catalogue"
                position="50"
        >
            <label>Module in admin menu</label>
            <label lang="de-DE">Modul im Adminmenü</label>
        </module>

        <!-- You can use the same url to open your module from the app store -->
        <main-module source="https://example.com/main"/>
    </admin>
</manifest>
```

:::

This feature is not compatible with themes as they will always open the theme config by default.

## Admin design compatibility

As your module page is integrated as an iframe you are not able to use the stylesheet and javascript out of the box.
Having the stylesheets that are used in the Administration can be beneficial for the app module to seamlessly integrate into the Administration.
You can use the shop version that is passed as `sw-version` within the request query to determine what stylesheets you want to load.
The compiled Administration stylesheets for each version can be found within the tagged releases of the `shopware/administration` package within the `Resources/public/static` folder.
Combining this information enables your app to look exactly like the Administration, although it is encapsulated within an iframe.

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/administration/module-component-management/add-custom-module.md
---

# Add custom module

In the `Administration` core code, each module is defined in a directory called `module`.
Inside the `module` directory lies the list of several modules, each having their own directory named after the module itself.

## Prerequisites

This guide **does not** explain how to create a new plugin for Shopware 6.
Head over to our Plugin base guide to learn how to create a plugin at first:

## Creating the index.js file

The first step is creating a new directory `<plugin root>/src/Resources/app/administration/src/module/swag-example`, so you can store your own modules files in there.
Right afterwards, create a new file called `index.js` in there. Consider it to be the main file for your custom module.

::: warning
This is necessary, because Shopware 6 is automatically requiring an `index.js` file for each module.
:::

Your custom module directory isn't known to Shopware 6 yet.
The entry point of your plugin is the `main.js` file.
That's the file you need to change now, so that it loads your new module.
For this, simply add the following line to your `main.js` file:

```javascript
// <plugin root>/src/Resources/app/administration/src/main.js
import './module/swag-example';
```

Now your module's `index.js` will be executed.

## Registering the module

Your `index.js` is still empty now, so let's get going to actually create a new module.
This is technically done by calling the method `registerModule` method of our [ModuleFactory](https://github.com/shopware/shopware/blob/trunk/src/Administration/Resources/app/administration/src/core/factory/module.factory.ts), but you're not going to use this directly.

Instead, you're using the `Shopware.Module.register()` method, but why is that?

`Shopware` is a [global object](../data-handling-processing/the-shopware-object.md) created for third party developers.
It is mainly the bridge between the Shopware Administration and our plugin.
The `Module` object comes with a `register` helper method to easily register your module.
The method needs two parameters to be set, the first one being the module's name, the second being a javascript object, which contains your module's configuration.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/swag-example/index.js
Shopware.Module.register('swag-example', {
    // configuration here
});
```

## Configuring the module

In this file, you can configure a couple of things, e.g. the color of your module.
Each module needs a primary color, which will be used on specific accents and locations throughout your module.
To name a few, it's the color of the main icon of the module, the tag in the global search input and the accent color of the smart bar.

In this example `#ff3d58` is used as a color, which is a soft red.
Also, each module has their own icon. You can see here [here](https://component-library.shopware.com/icons/) which icons are available in Shopware 6 by default.
In our case here, let's say we use the icon `regular-shopping-bag`, which will also be used for the module.

::: danger
This is not the icon being used for a menu entry! The icon for that needs to be configured separately.
Please refer to the [Add a menu entry](../routing-navigation/add-menu-entry.md) guide for more information on this topic.
:::

In addition, you're able to configure a title here, which will be used for the actual browser title.
Just add a string for the key `title`.
This will be the default title for your module, you can edit this for each component later on.

The `description` is last basic information you should set here, which will be shown as an empty-state.
That means the description will be shown e.g. when you integrated a list component, but your list is empty as of now.
In that case, your module's description will be displayed instead.

Another important aspect are the routes which your module is going to use, such as e.g. `swag-example-list` for the list of your module, `swag-example-detail` for the detail page and `swag-example-create` for creating a new entry.
Those routes are configured as an object in a property named `routes`. We will cover that in the next paragraph.

## Setting up menu entry and routes

The next steps are covered in their own guides. The first one would be adding a menu entry, so please take a look at the guide regarding:

The second one refers to setting up custom routes, its guide can be found in the guide on adding custom routes:

## Set up additional meta info

If you have been following that guide, then you should have got a menu entry then.
The related routes are also set up already and linked to components, which will be created in the next main step.
There's a few more things we need to change in the configurations though that you should add to your module, such as a unique `name` and a `type`.
For reference, see this example:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/swag-example/index.js
Shopware.Module.register('swag-example', {
    type: 'plugin',
    name: 'Example',
    title: 'swag-example.general.mainMenuItemGeneral',
    description: 'sw-property.general.descriptionTextModule',
    color: '#ff3d58',
    icon: 'regular-shopping-bag',
...
```

The `name` should be a technical unique one, the `type` would be 'plugin' here. When it comes to this `type`, there are basically two options in Shopware: `core` and `plugin`.
So every third-party module should use `plugin`.
To give a little context: Looking at `module.factory` inside `registerModule` the plugin type is the only case which is being checked and has some different behaviour.
So it is more a convention and not a real validation which throws an error when `type` is divergent to these options.

## Implementing snippets

You've already set a label for your module's menu entry.
Yet, by default the `Administration` expects the value in there to be a [Vuei18n](https://kazupon.github.io/vue-i18n/started.html#html) variable, a translation key that is.
It's looking for a translation key `example` now and since you did not provide any translations at all yet, it can't find any translation for it and will just print the key of a snippet.
Sounds like it's time to implement translation snippets as well, right?

This is done by providing a new object to your module configuration, `snippets` this time.
This object contains another object for each language you want to support.
In this example `de-DE` and of course `en-GB` will be supported.

Each language then contains a nested object of translations, so let's have a look at an example:

```json
{
    "swag-example": {
        "nested": {
            "value": "example"
        },
        "foo": "bar"
    }
}
```

In this example you would have access to two translations by the following paths: `swag-example.nested.value` to get the value 'example' and `swag-example.foo` to get the value 'bar'.
You can nest those objects as much as you want. Please note that each path is prefixed by the extension name.

Since those translation objects become rather large, you should store them into separate files.
For this purpose, create a new directory `snippet` in your module's directory and in there two new files: `de-DE.json` and `en-GB.json`.
The snippet files will be loaded automatically based on the folder structure.

Let's also create the first translation, which is for your menu's label.
It's key should be something like this: `swag-example.general.mainMenuItemGeneral`

Thus open the `snippet/en-GB.json` file and create the new object in there.
The structure here is the same as in the first example, just formatted as json file.
Afterwards, use this path in your menu entry's `label` property.

To translate the `description` or the `title`, add those to your snippet file as well and edit the values in your module's `description` and `title`.
The title will be the same as the main menu entry by default.

This should be your snippet file now:

```json
{
    "swag-example": {
        "general": {
            "mainMenuItemGeneral": "My custom module",
            "descriptionTextModule": "Manage this custom module here"
        }
    }
}
```

## Build the Administration

As mentioned above, Shopware 6 is looking for a `main.js` file in your plugin.
Its contents get minified into a new file named after your plugin and will be moved to the `public` directory of Shopware 6 root directory.
Given this plugin would be named "AdministrationNewModule", the bundled and minified javascript code for this example would be located under `<plugin root>/src/Resources/public/administration/js/administration-new-module.js`, once you run the command following command in your shopware root directory:

```bash
./bin/build-administration.sh
```

```bash
composer run build:js:admin
```

::: info
Your plugin has to be activated for this to work.
:::

Make sure to also include that file when publishing your plugin!
A copy of this file will then be put into the directory `<shopware root>/public/bundles/administration/administrationnewmodule/administration/js/administration-new-module.js`.

Your minified javascript file will now be loaded in production environments.

## Special: Case Settings

### Link your module into settings

If you think about creating a module concerning settings, you might want to link your module in the `settings` section of the Administration.
You can add the `settingsItem` option to the module configuration as seen below:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/swag-example/index.js
import './page/swag-plugin-list';
import './page/swag-plugin-detail';
Shopware.Module.register('swag-plugin', {
    ...
    settingsItem: [{
        group: 'plugins',
        icon: 'regular-rocket',
        to: 'swag.plugin.list',
        name: 'SwagExampleMenuItemGeneral', // optional, fallback is taken from module
        id: '', // optional, fallback is taken from module
        label: '', // optional, fallback is taken from module
        iconComponent: YourCustomIconRenderingComponent, // optional, this overrides the component used to render the icon
    }]
});
```

The `group` property determines the tab, the item will be displayed in. Valid options are 'shop', 'system' and 'plugins'.

The `icon` property contains the icon name which will be displayed. Refer to the [Meteor Icon Kit documentation](https://developer.shopware.com/resources/meteor-icon-kit/) for icon names.

The `to` property must contain the name of the route. The route has to be defined in a separate routes section as described [here](../routing-navigation/add-custom-route.md). Have a look at the `Configuring the route` section in particular to find out about the name of your route.

## Example for the final module

Here's your final module:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/swag-example/index.js
import './page/swag-example-list';
import './page/swag-example-detail';
import './page/swag-example-create';
import deDE from './snippet/de-DE';
import enGB from './snippet/en-GB';

Shopware.Module.register('swag-example', {
    type: 'plugin',
    name: 'Example',
    title: 'swag-example.general.mainMenuItemGeneral',
    description: 'sw-property.general.descriptionTextModule',
    color: '#ff3d58',
    icon: 'regular-shopping-bag',

    snippets: {
        'de-DE': deDE,
        'en-GB': enGB
    },

    routes: {
        list: {
            component: 'swag-example-list',
            path: 'list'
        },
        detail: {
            component: 'swag-example-detail',
            path: 'detail/:id',
            meta: {
                parentPath: 'swag.example.list'
            }
        },
        create: {
            component: 'swag-example-create',
            path: 'create',
            meta: {
                parentPath: 'swag.example.list'
            }
        }
    },

    navigation: [{
        label: 'swag-example.general.mainMenuItemGeneral',
        color: '#ff3d58',
        path: 'swag.example.list',
        icon: 'regular-shopping-bag',
        position: 100
    }]
});
```

## Next steps

As you might have noticed, we are just adding a custom module to the module.
However, there's a lot more possible when it comes to extending the Administration.
In addition, you surely want to customize your module even more.
You may want to try the following things:

* [Add custom component](../module-component-management/add-custom-component.md)
* [Add a menu entry](../routing-navigation/add-menu-entry.md)
* [Add a custom route](../routing-navigation/add-custom-route.md)
* [Add a custom service](../services-utilities/add-custom-service.md)
* [Add translations](../templates-styling/adding-snippets.md)
* [Customizing another module](customizing-modules.md)
* [Dealing with data in the Administration](../data-handling-processing/using-data-handling.md)
* [Adding permissions to your module](../permissions-error-handling/add-acl-rules.md)

---

---
url: /docs/guides/plugins/apps/administration/add-custom-modules.md
---

# Add Custom Module

## Overview

This guide will show you how to add custom modules to the Shopware Administration using your manifest file. This works for simple applications; however, if you want to write more advanced applications, the [Meteor Admin SDK](meteor-admin-sdk.md) is recommended. It has many more features and is more flexible.

For further details and guidance on custom modules, refer to the documentation provided on the Meteor Admin SDK's [custom modules](https://developer.shopware.com/resources/admin-extension-sdk/api-reference/ui/mainModule.html) section.

## Prerequisites

You should be familiar with the concept of Apps, especially their registration flow as well as signing and verifying requests and responses between Shopware and the App backend server, as that is required to authenticate the requests coming from the shops and showing the correct content in your modules.

In your app, you are able to add your own modules to the Administration. Your custom modules are loaded as iframes which are embedded in the Shopware Administration and within this iframe, your website will be loaded and shown.

Creating custom modules takes place at the `<admin>` section of your `manifest.xml`; see the [Manifest Reference](../../../../resources/references/app-reference/manifest-reference.md) for more details. You can add any amount of custom modules by adding new `<module>` elements to your manifest.

To configure your module, you can set it up with with some additional attributes.

* `name` (required): The technical name of the module. This is the name your module is referenced with.
* `parent` (required): The Administration navigation id of the menu item that serves as the parent menu item.
* `source` (optional): The URL to your app servers endpoint from which the module is served from. This can be omitted if you want to define a menu item that should serve as a parent menu item for other app modules.
* `parent` (optional): The Administration navigation id from the menu item that serves as the parent menu item. If omitted your module will be listed under the "My apps" menu entry. **This field will be required in future versions as we are going to remove the "My Apps" menu item**
* `position` (optional): A numeric index that sets the position of your menu entry regarding to it's siblings.

Additionally you can define `label` elements inside of your `module` element, to set up how your module will be displayed in the admin menu.

::: code-group

```xml [manifest.xml]
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        ...
    </meta>
    <admin>
        <module name="exampleModule"
                source="https://example.com/promotion/view/promotion-module"
                parent="sw-marketing"
                position="50"
        >
            <label>Example module</label>
            <label lang="de-DE">Beispiel Modul</label>
        </module>
    </admin>
</manifest>
```

:::

For a complete reference of the structure of the manifest file, take a look at the [Manifest reference](../../../../resources/references/app-reference/manifest-reference.md).

If the user opens the module in the Administration your app will receive a request to the URL defined in the `source` attribute of your `module` element. Your app can determine the shop that has opened the module through query parameters added to the url:

* `shop-id`: The unique identifier of the shop, where the app was installed
* `shop-url`: The URL of the shop, this can later be used to access the Shopware API
* `timestamp`: The Unix timestamp when the request was created
* `shopware-shop-signature`: SHA256 HMAC of the rest of the query string, signed with the `shop-secret`

A sample request may look like this:

```text
https://example.com/promotion/view/promotion-config?shop-id=HKTOOpH9nUQ2&shop-url=http%3A%2F%2Fmy.shop.com&timestamp=1592406102&shopware-shop-signature=3621fffa80187f6d43ce6cb25760340ab9ba2ea2f601e6a78a002e601579f415
```

In this case the `shopware-shop-signature` parameter contains an SHA256 HMAC of the rest of the query string, signed again with the secret your app assigned the shop during the [registration](../lifecycle/app-registration-setup.md#setup). The signature can be used to verify the authenticity of the request.

```php
// injected or build by yourself
$shopResolver = new ShopResolver($repository);
$contextResolver = new ContextResolver();

$shop = $shopResolver->resolveShop($serverRequest);
$module = $contextResolver->assembleModule($serverRequest, $shop);
```

```php
use Shopware\App\SDK\Context\Module\ModuleAction;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\AsController;
use Symfony\Component\Routing\Attribute\Route;

#[AsController]
class ModuleController {
    #[Route('/module')]
    public function show(ModuleAction $module): Response
    {
        // handle payment
        
        return $this->render('....');
    }
}
```

## Leave loading state

Because your module is displayed as an iframe in the Administration, Shopware can not easily tell when your module has finished loading. Therefore, your new module will display a loading spinner to signal that your iframe is loading. To leave the loading state, your iframe needs to give a notification when the loading process is done.

```javascript
function sendReadyState() {
    window.parent.postMessage('sw-app-loaded', '*');
}
```

This has to be done as soon as everything is loaded so that the loading spinner disappears. If your view is not fully loaded after 5 seconds, it will be aborted.

## Structure your modules

With Shopware 6.4.0.0 we added a third level in the admin menu structure. This change was made to give you as a developer the opportunity to group your Administration modules if needed.

When you define a module, it gets automatically loaded by the Administration. Additionally the Administration creates a menu entry for your module. You can reference this menu entry and set it as the parent menu entry for your other modules.

The navigation id of your modules always uses the pattern `app-<appName>-<moduleName>`. So, within your manifest you can add a reference to modules that you just created:

::: code-group

```xml [manifest.xml]
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        <name>myApp</app>
        ...
    </meta>
    <admin>
        <module name="myModules"
                source="https://example.com/promotion/view/promotion-module"
                parent="sw-catalogue"
                position="50"
        >
            <label>My apps modules</label>
            <label lang="de-DE">Module meiner app</label>
        </module>

        <module name="someModule"
                source="https://example.com/promotion/view/promotion-module"
                parent="app-myApp-myModules"
                position="1"
        >
            <label>Module underneath "My apps modules"</label>
            <label lang="de-DE">Modul unterhalb von "Module meiner app"</label>
        </module>
    </admin>
</manifest>
```

:::

Modules that are used as a parent for other modules do not need the `source` attribute to be set, although they can.

## Add main module to your app

With Shopware 6.4.0.0 You can define a main module for your app. This "special" module will be opened from the list of your installed apps as well as from the app detail page if you bought it from the Shopware store.

Your main module can be defined by adding a `main-module` element within your `administration` section of your manifest file. It's only required attribute is the `source` attribute.

To avoid mixing other modules with your main module, we decided to separate the main module from modules with navigation entries. You can still use the same URL on both, a module that is available through the menu and your main module.

::: code-group

```xml [manifest.xml]
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        <name>myApp</app>
        ...
    </meta>
    <admin>
        <module name="normalModule"
                source="https://example.com/main"
                parent="sw-catalogue"
                position="50"
        >
            <label>Module in admin menu</label>
            <label lang="de-DE">Modul im Adminmenü</label>
        </module>

        <!-- You can use the same url to open your module from the app store -->
        <main-module source="https://example.com/main"/>
    </admin>
</manifest>
```

:::

This feature is not compatible with themes as they will always open the theme config by default.

## Admin design compatibility

As your module page is integrated as an iframe you are not able to use the stylesheet and javascript out of the box.
Having the stylesheets that are used in the Administration can be beneficial for the app module to seamlessly integrate into the Administration.
You can use the shop version that is passed as `sw-version` within the request query to determine what stylesheets you want to load.
The compiled Administration stylesheets for each version can be found within the tagged releases of the `shopware/administration` package within the `Resources/public/static` folder.
Combining this information enables your app to look exactly like the Administration, although it is encapsulated within an iframe.

---

---
url: >-
  /docs/guides/plugins/plugins/administration/module-component-management/add-custom-module.md
---

# Add Custom Module

## Overview

In the `Administration` core code, each module is defined in a directory called `module`.
Inside the `module` directory lies the list of several modules, each having their own directory named after the module itself.

## Prerequisites

This guide **does not** explain how to create a new plugin for Shopware 6.
Head over to our Plugin base guide to learn how to create a plugin at first:

## Creating the index.js file

The first step is creating a new directory `<plugin root>/src/Resources/app/administration/src/module/swag-example`, so you can store your own modules files in there.
Right afterward, create a new file called `index.js` in there. Consider it to be the main file for your custom module.

::: warning
This is necessary, because Shopware 6 is automatically requiring an `index.js` file for each module.
:::

Your custom module directory isn't known to Shopware 6 yet.
The entry point of your plugin is the `main.js` file.
That's the file you need to change now so that it loads your new module.
For this, add the following line to your `main.js` file:

```javascript
// <plugin root>/src/Resources/app/administration/src/main.js
import './module/swag-example';
```

Now your module's `index.js` will be executed.

## Registering the module

Your `index.js` is still empty now, so let's get going to actually create a new module.
This is technically done by calling the method `registerModule` method of our [ModuleFactory](https://github.com/shopware/shopware/blob/trunk/src/Administration/Resources/app/administration/src/core/factory/module.factory.ts), but you're not going to use this directly.

Instead, you're using the `Shopware.Module.register()` method, but why is that?

`Shopware` is a [global object](../data-handling-processing/the-shopware-object.md) created for third party developers.
It is mainly the bridge between the Shopware Administration and our plugin.
The `Module` object comes with a `register` helper method to easily register your module.
The method needs two parameters to be set, the first one being the module's name, the second being a javascript object, which contains your module's configuration.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/swag-example/index.js
Shopware.Module.register('swag-example', {
    // configuration here
});
```

## Configuring the module

In this file, you can configure a couple of things, e.g., the color of your module.
Each module needs a primary color, which will be used on specific accents and locations throughout your module.
To name a few, it's the color of the main icon of the module, the tag in the global search input and the accent color of the smart bar.

In this example `#ff3d58` is used as a color, which is a soft red.
Also, each module has its own icon. You can see [here](https://shopware.design/icons/) which icons are available in Shopware 6 by default.
In our case here, let's say we use the icon `regular-shopping-bag`, which will also be used for the module.

::: danger
This is not the icon being used for a menu entry! The icon for that needs to be configured separately.
Please refer to the [Add a menu entry](../routing-navigation/add-menu-entry.md) guide for more information on this topic.
:::

In addition, you're able to configure a title here, which will be used for the actual browser title.
Just add a string for the key `title`.
This will be the default title for your module, you can edit this for each component later on.

The `description` is last basic information you should set here, which will be shown as an empty-state.
That means the description will be shown e.g., when you integrated a list component, but your list is empty as of now.
In that case, your module's description will be displayed instead.

Another important aspect is the routes that your module is going to use, such as e.g. `swag-example-list` for the list of your module, `swag-example-detail` for the detail page and `swag-example-create` for creating a new entry.
Those routes are configured as an object in a property named `routes`. We will cover that in the next paragraph.

## Setting up menu entry and routes

The next steps are covered in their own guides. The first one would be adding a menu entry, so please take a look at the guide regarding:

The second one refers to setting up custom routes; its guide can be found in the guide on adding custom routes:

## Set up additional meta info

If you have been following that guide, then you should have got a menu entry then.
The related routes are also set up already and linked to components, which will be created in the next main step.
There's a few more things we need to change in the configurations though that you should add to your module, such as a unique `name` and a `type`.
For reference, see this example:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/swag-example/index.js
Shopware.Module.register('swag-example', {
    type: 'plugin',
    name: 'Example',
    title: 'swag-example.general.mainMenuItemGeneral',
    description: 'sw-property.general.descriptionTextModule',
    color: '#ff3d58',
    icon: 'regular-shopping-bag',
...
```

The `name` should be technically unique, the `type` would be 'plugin' here. When it comes to this `type`, there are basically two options in Shopware: `core` and `plugin`.
So every third-party module should use `plugin`.
To give a little context: Looking at `module.factory` inside `registerModule` the plugin type is the only case which is being checked and has some different behavior.
So it is more a convention and not a real validation which throws an error when `type` is divergent to these options.

## Implementing snippets

You've already set a label for your module's menu entry.
Yet, by default the `Administration` expects the value in there to be a [Vuei18n](https://kazupon.github.io/vue-i18n/started.html#html) variable, a translation key that is.
It's looking for a translation key `example` now and since you did not provide any translations at all yet, it can't find any translation for it and will just print the key of a snippet.
Now let's implement the translation snippets.

This is done by providing a new object to your module configuration, `snippets` this time.
This object contains another object for each language you want to support.
In this example `de-DE` and of course `en-GB` will be supported.

Each language then contains a nested object of translations, so let's have a look at an example:

```json
{
    "swag-example": {
        "nested": {
            "value": "example"
        },
        "foo": "bar"
    }
}
```

In this example you would have access to two translations by the following paths: `swag-example.nested.value` to get the value 'example' and `swag-example.foo` to get the value 'bar'.
You can nest those objects as much as you want. Please note that each path is prefixed by the extension name.

Since those translation objects become rather large, you should store them into separate files.
For this purpose, create a new directory `snippet` in your module's directory and in there two new files: `de-DE.json` and `en-GB.json`.
The snippet files will be loaded automatically based on the folder structure.

Let's also create the first translation, which is for your menu's label.
It's key should be something like this: `swag-example.general.mainMenuItemGeneral`

Thus open the `snippet/en-GB.json` file and create the new object in there.
The structure here is the same as in the first example, just formatted as json file.
Afterward, use this path in your menu entry's `label` property.

To translate the `description` or the `title`, add those to your snippet file as well and edit the values in your module's `description` and `title`.
The title will be the same as the main menu entry by default.

This should be your snippet file now:

```json
{
    "swag-example": {
        "general": {
            "mainMenuItemGeneral": "My custom module",
            "descriptionTextModule": "Manage this custom module here"
        }
    }
}
```

## Build the Administration

As mentioned above, Shopware 6 is looking for a `main.js` file in your plugin.
Its contents get minified into a new file named after your plugin and will be moved to the `public` directory of Shopware 6 root directory.
Given this plugin would be named "AdministrationNewModule", the bundled and minified javascript code for this example would be located under `<plugin root>/src/Resources/public/administration/js/administration-new-module.js`, once you run the command following command in your shopware root directory:

```bash
shopware-cli project admin-build
```

```bash
composer run build:js:admin
```

::: info
Your plugin has to be activated for this to work.
:::

Make sure to also include that file when publishing your plugin!
A copy of this file will then be put into the directory `<shopware root>/public/bundles/administration/administrationnewmodule/administration/js/administration-new-module.js`.

Your minified JavaScript file will now be loaded in production environments.

## Special: Case Settings

### Link your module into settings

If you think about creating a module concerning settings, you might want to link your module in the `settings` section of the Administration.
You can add the `settingsItem` option to the module configuration as seen below:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/swag-example/index.js
import './page/swag-plugin-list';
import './page/swag-plugin-detail';
Shopware.Module.register('swag-plugin', {
    ...
    settingsItem: [{
        group: 'plugins',
        icon: 'regular-rocket',
        to: 'swag.plugin.list',
        name: 'SwagExampleMenuItemGeneral', // optional, fallback is taken from module
        id: '', // optional, fallback is taken from module
        label: '', // optional, fallback is taken from module
        iconComponent: YourCustomIconRenderingComponent, // optional, this overrides the component used to render the icon
    }]
});
```

The `group` property determines the tab, the item will be displayed in. Valid options are 'shop', 'system' and 'plugins'.

The `icon` property contains the icon name which will be displayed. Refer to the [Meteor Icon Kit documentation](https://developer.shopware.com/resources/meteor-icon-kit/) for icon names.

The `to` property must contain the name of the route. The route has to be defined in a separate routes section as described [here](../routing-navigation/add-custom-route.md). Have a look at the `Configuring the route` section in particular to find out about the name of your route.

## Example for the final module

Here's your final module:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/swag-example/index.js
import './page/swag-example-list';
import './page/swag-example-detail';
import './page/swag-example-create';
import deDE from './snippet/de-DE';
import enGB from './snippet/en-GB';

Shopware.Module.register('swag-example', {
    type: 'plugin',
    name: 'Example',
    title: 'swag-example.general.mainMenuItemGeneral',
    description: 'sw-property.general.descriptionTextModule',
    color: '#ff3d58',
    icon: 'regular-shopping-bag',

    snippets: {
        'de-DE': deDE,
        'en-GB': enGB
    },

    routes: {
        list: {
            component: 'swag-example-list',
            path: 'list'
        },
        detail: {
            component: 'swag-example-detail',
            path: 'detail/:id',
            meta: {
                parentPath: 'swag.example.list'
            }
        },
        create: {
            component: 'swag-example-create',
            path: 'create',
            meta: {
                parentPath: 'swag.example.list'
            }
        }
    },

    navigation: [{
        label: 'swag-example.general.mainMenuItemGeneral',
        color: '#ff3d58',
        path: 'swag.example.list',
        icon: 'regular-shopping-bag',
        position: 100
    }]
});
```

## Next steps

As you might have noticed, we are just adding a custom module to the module.
However, there's a lot more possible when it comes to extending the Administration.
In addition, you surely want to customize your module even more.
You may want to try the following things:

* [Add custom component](../module-component-management/add-custom-component.md)
* [Add a menu entry](../routing-navigation/add-menu-entry.md)
* [Add a custom route](../routing-navigation/add-custom-route.md)
* [Add a custom service](../services-utilities/add-custom-service.md)
* [Add translations](../templates-styling/adding-snippets.md)
* [Customizing another module](customizing-modules.md)
* [Dealing with data in the Administration](../data-handling-processing/using-data-handling.md)
* [Adding permissions to your module](../permissions-error-handling/add-acl-rules.md)

---

---
url: /docs/guides/plugins/plugins/storefront/controllers/add-custom-page.md
---

# Add Custom Page

## Overview

In this guide, you will learn how to create a custom page for your Storefront.
A page in general consists of a controller, a page loader, a "page loaded" event and a page class, which is like a struct and contains the most necessary data for the page.

## Prerequisites

To add your own custom page for your plugin, you first need a plugin as base.
Therefore, you can refer to the [Plugin Base Guide](../../plugin-base-guide.md). Since you need to load your page with a controller, you might want to have a look at our guide about [creating a controller](../controllers/add-custom-controller.md) first.
The controller created in the previously mentioned controller guide will also be used in this guide.

## Adding custom page

In the following sections, we'll create each of the necessary classes one by one.
The first one will be a controller, whose creation is not going to be explained here again.
Have a look at the guide about [creating a controller](../controllers/add-custom-controller.md) to see why it works.

### Creating `ExampleController`

Let's have a look at an example controller.

::: code-group

```php [PLUGIN_ROOT/src/Storefront/Controller/ExampleController.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

use Shopware\Core\PlatformRequest;
use Shopware\Storefront\Framework\Routing\StorefrontRouteScope;
use Shopware\Storefront\Controller\StorefrontController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

#[Route(defaults: [PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [StorefrontRouteScope::ID]])]
class ExampleController extends StorefrontController
{
    #[Route(path: '/example-page', name: 'frontend.example.page', methods: ['GET'])]
    public function examplePage(): Response
    {
    }
}
```

:::

It has a method `examplePage`, which is accessible via the route `example-page`.
This method will be responsible for loading your page later on, but we'll leave it like that for now.

Don't forget to [register your controller via the DI](../controllers/add-custom-controller.md#servicesphp-example).

### Creating the pageloader

To stick to Shopware's default location for the page loader, we'll have to create a new directory: `<plugin root>/src/Storefront/Page/Example`.

In there, we will proceed to create all page related classes, such as the page loader.

Go ahead and create a new file called `ExamplePageLoader.php`.
It's a new service, which doesn't have to extend from any other class.
You might want to implement a `ExamplePageLoaderInterface` interface, which is not explained in this guide.
You can do that to have a decoratable page loader class.

The page loader is responsible for creating your page class instance (`ExamplePage`, will be created in the next section), filling it with data, e.g. from store api, and firing a `PageLoaded` event, so others can react to your page being loaded.
Do not use a repository directly in a page loader. Always get the data for your pages from a store api route instead.

Let's have a look at a full example `ExamplePageLoader`:

::: code-group

```php [PLUGIN_ROOT/src/Storefront/Page/Example/ExamplePageLoader.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Page\Example;

use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Page\GenericPageLoaderInterface;
use Symfony\Component\EventDispatcher\EventDispatcherInterface;
use Symfony\Component\HttpFoundation\Request;

class ExamplePageLoader
{
    private GenericPageLoaderInterface $genericPageLoader;

    private EventDispatcherInterface $eventDispatcher;

    public function __construct(GenericPageLoaderInterface $genericPageLoader, EventDispatcherInterface $eventDispatcher)
    {
        $this->genericPageLoader = $genericPageLoader;
        $this->eventDispatcher = $eventDispatcher;
    }

    public function load(Request $request, SalesChannelContext $context): ExamplePage
    {
        $page = $this->genericPageLoader->load($request, $context);
        $page = ExamplePage::createFrom($page);

        // Do additional stuff, e.g. load more data from store api and add it to page
         $page->setExampleData(...);

        $this->eventDispatcher->dispatch(
            new ExamplePageLoadedEvent($page, $context, $request)
        );

        return $page;
    }
}
```

:::

So first of all, as already mentioned: This is a new class or service, which doesn't have to extend from any other class.
The constructor is passed two arguments: The `GenericPageLoaderInterface` and the `EventDispatcherInterface`.

The first one is not necessary, but useful, since it loads all kinds of default page data.

The `EventDispatcherInterface` is of course necessary to fire an event later on.

Every page loader should implement a `load` method, which is not mandatory, but convention.
You want your page loader to work like all the other page loaders, right?
It should return an instance of your example page, in this case `ExamplePage`.
Don't worry, we haven't created that one yet, it will be created in the next sections.
So, the first thing it does is basically creating a `Page` instance, containing basic data, like the meta-information.

Afterwards, you're creating your own page instance by using the method `createFrom`.
This method is available, since your `ExamplePage` has to extend from the `Page` struct, which in return extends from the `Struct` class.
The latter implements the [CreateFromTrait](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Core/Framework/Struct/CreateFromTrait.php) containing this method.
In short, this will create an instance of your `ExamplePage`, containing all the data from the generic `Page` object.

Afterwards, you can add more data to your page instance by using a setter.
Of course, your example page class then has to have such a setter method, as well as a getter.

As already mentioned, you should also fire an event once your page was loaded.
For this case, you need a custom page loaded event class, which is also created in the next sections.
It will be called `ExamplePageLoadedEvent`.

The last thing to do in this method is to return your new page instance.

Remember to register your new page loader in the DI container:

::: code-group

```php [PLUGIN_ROOT/src/Resources/config/services.php]
$services->set(ExamplePageLoader::class)
    ->public()
    ->args([
        service('Shopware\Storefront\Page\GenericPageLoader'),
        service('event_dispatcher'),
    ]);
```

:::

#### Adjusting the controller

Theoretically, this is all your page loader does - but it's not being used yet.
Therefore, you have to inject your page loader to your custom controller and execute the `load` method.

::: code-group

```php [PLUGIN_ROOT/src/Storefront/Controller/ExampleController.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

...

class ExampleController extends StorefrontController
{
    private ExamplePageLoader $examplePageLoader;

    public function __construct(ExamplePageLoader $examplePageLoader)
    {
        $this->examplePageLoader = $examplePageLoader;
    }

    #[Route(path: '/example-page', name: 'frontend.example.page', methods: ['GET'])]
    public function examplePage(Request $request, SalesChannelContext $context): Response
    {
        $page = $this->examplePageLoader->load($request, $context);

        return $this->renderStorefront('@SwagBasicExample/storefront/page/example/index.html.twig', [
            'example' => 'Hello world',
            'page' => $page
        ]);
    }
}
```

:::

Note, that we've added the page to the template variables.

#### Adjusting the services.php

In addition, it is necessary to pass the argument with the ID of the `ExamplePageLoader` class to the [configuration](add-custom-controller.md#servicesphp-example) of the controller service in the `services.php`.

::: code-group

```php [PLUGIN_ROOT/src/Resources/config/services.php]
<?php declare(strict_types=1);

use Swag\BasicExample\Storefront\Controller\ExampleController;
use Swag\BasicExample\Storefront\Page\Example\ExamplePageLoader;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(ExampleController::class)
        ->public()
        ->args([service(ExamplePageLoader::class)])
        ->call('setContainer', [service('service_container')]);
};
```

:::

### Creating the example page

So now we're going to create the example page class, that was already used in our page loader, `ExamplePage`.

It has to extend from the `Shopware\Storefront\Page\Page` class to contain the meta information, as well as some helper methods.

Let's have a look at an example:

::: code-group

```php [PLUGIN_ROOT/src/Storefront/Page/Example/ExamplePage.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Page\Example;

use Shopware\Storefront\Page\Page;
use Swag\BasicExample\Core\Content\Example\ExampleEntity;

class ExamplePage extends Page
{
    protected ExampleEntity $exampleData;

    public function getExampleData(): ExampleEntity
    {
        return $this->exampleData;
    }

    public function setExampleData(ExampleEntity $exampleData): void
    {
        $this->exampleData = $exampleData;
    }
}
```

:::

As explained in the page loader section, your page can contain all kinds of custom data.
It has to provide a getter and a setter for the custom data, so it can be applied and read.
In this example, the entity from our guide about [creating custom complex data](../../framework/data-handling/add-custom-complex-data.md#entity-class) is being used.

And that's it already.
Your page is ready to go.

### Creating the page loaded event

One more class is missing, the custom event class.
It has to extend from the `Shopware\Storefront\Page\PageLoadedEvent` class.

Its constructor parameter will be the `ExamplePage`, which it has to save into a property and there needs to be a getter to get the example page instance.
Additional constructor parameters are the `Request` and the `SalesChannelContext`, which you have to pass to the parent's constructor.

Here's the example:

::: code-group

```php [PLUGIN_ROOT/src/Storefront/Page/Example/ExamplePageLoadedEvent.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Page\Example;

use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Page\PageLoadedEvent;
use Symfony\Component\HttpFoundation\Request;

class ExamplePageLoadedEvent extends PageLoadedEvent
{
    protected ExamplePage $page;

    public function __construct(ExamplePage $page, SalesChannelContext $salesChannelContext, Request $request)
    {
        $this->page = $page;
        parent::__construct($salesChannelContext, $request);
    }

    public function getPage(): ExamplePage
    {
        return $this->page;
    }
}
```

:::

And that's it for your `ExamplePageLoadedEvent` class.

Your example page should now be fully functioning.

## Next steps

You've now successfully created a whole new page, including a custom controller, a custom template,
and the necessary classes to create a new page, a loader, the page struct and the page loaded event.

In your `load` method, you've used the `GenericPageLoader`, which takes care of the meta-information of the page.
There are also "pagelets", basically reusable fractions of a page. Learn how to [create a custom pagelet](add-custom-pagelet.md).

---

---
url: /docs/v6.5/guides/plugins/plugins/storefront/add-custom-page.md
---

# Add Custom Page

## Overview

In this guide you will learn how to create custom page for your Storefront. A page in general consists of a controller, a page loader, a "page loaded" event and a page class, which is like a struct and contains most necessary data for the page.

## Prerequisites

In order to add your own custom page for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide). Since you need to load your page with a controller, you might want to have a look at our guide about [creating a controller](add-custom-controller) first. The controller created in the previously mentioned controller guide will also be used in this guide.

## Adding custom page

In the following sections, we'll create each of the necessary classes one by one. The first one will be controller, whose creation is not going to explained here again. Have a look at the guide about [creating a controller](add-custom-controller) to see why it works.

### Creating ExampleController

Let's have a look at an example controller.

```php
// <plugin root>/src/Storefront/Controller/ExampleController.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

use Shopware\Storefront\Controller\StorefrontController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

#[Route(defaults: ['_routeScope' => ['storefront']])]
class ExampleController extends StorefrontController
{
    #[Route(path: '/example-page', name: 'frontend.example.page', methods: ['GET'])]
    public function examplePage(): Response
    {
    }
}
```

It has a method `examplePage`, which is accessible via the route `example-page`. This method will be responsible for loading your page later on, but we'll leave it like that for now.

Don't forget to [register your controller via the DI](add-custom-controller#Services.xml%20example).

### Creating the pageloader

In order to stick to Shopware's default location for the page loader, we'll have to create a new directory: `<plugin root>/src/Storefront/Page/Example`.

In there, we will proceed to create all page related classes, such as the page loader.

Go ahead and create a new file called `ExamplePageLoader.php`. It's a new service, which doesn't have to extend from any other class. You might want to implement a `ExamplePageLoaderInterface` interface, which is not explained in this guide. You can do that in order to have a decoratable page loader class.

The page loader is responsible for creating your page class instance (`ExamplePage`, will be created in the next section), filling it with data, e.g. from store api, and firing a `PageLoaded` event, so others can react to your page being loaded.
Do not use a repository directly in a page loader. Always get the data for your pages from a store api route instead.

Let's have a look at a full example `ExamplePageLoader`:

```php
// <plugin root>/src/Storefront/Page/Example/ExamplePageLoader.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Page\Example;

use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Page\GenericPageLoaderInterface;
use Symfony\Component\EventDispatcher\EventDispatcherInterface;
use Symfony\Component\HttpFoundation\Request;

class ExamplePageLoader
{
    private GenericPageLoaderInterface $genericPageLoader;

    private EventDispatcherInterface $eventDispatcher;

    public function __construct(GenericPageLoaderInterface $genericPageLoader, EventDispatcherInterface $eventDispatcher)
    {
        $this->genericPageLoader = $genericPageLoader;
        $this->eventDispatcher = $eventDispatcher;
    }

    public function load(Request $request, SalesChannelContext $context): ExamplePage
    {
        $page = $this->genericPageLoader->load($request, $context);
        $page = ExamplePage::createFrom($page);

        // Do additional stuff, e.g. load more data from store api and add it to page
         $page->setExampleData(...);

        $this->eventDispatcher->dispatch(
            new ExamplePageLoadedEvent($page, $context, $request)
        );

        return $page;
    }
}
```

So first of all, as already mentioned: This is a new class or service, which doesn't have to extend from any other class. The constructor is passed two arguments: The `GenericPageLoaderInterface` and the `EventDispatcherInterface`.

The first one is not necessary, but useful, since it loads all kind of default page stuff, such as a footer and a header and loads some additional helpful data. Once again, you don't have to do that, but if you want your page to have a footer etc., you should add it.

The `EventDispatcherInterface` is of course necessary in order to fire an event later on.

Every page loader should implement a `load` method, which is not mandatory, but convention. You want your page loader to work like all the other page loaders, right? It should return an instance of your example page, in this case `ExamplePage`. Don't worry, we haven't created that one yet, it will be created in the next sections. So, the first thing it does is basically creating a `Page` instance, containing all necessary basic data, such as the footer etc.

Afterwards you're creating your own page instance by using the method `createFrom`. This method is available, since your `ExamplePage` has to extend from the `Page` struct, which in return extends from the `Struct` class. The latter implements the [CreateFromTrait](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Core/Framework/Struct/CreateFromTrait.php) containing this method. In short, this will create an instance of your `ExamplePage`, containing all the data from the generic `Page` object.

Afterwards, you can add more data to your page instance by using a setter. Of course, your example page class then has to have such a setter method, as well as a getter.

As already mentioned, you should also fire an event once your page was loaded. For this case, you need a custom page loaded event class, which is also created in the next sections. It will be called `ExamplePageLoadedEvent`.

The last thing to do in this method is to return your new page instance.

Remember to register your new page loader in the DI container:

```html
// <plugin root>/src/Resources/config/services.xml
<service id="Swag\BasicExample\Storefront\Page\Example\ExamplePageLoader" public="true">
    <argument type="service" id="Shopware\Storefront\Page\GenericPageLoader" />
    <argument type="service" id="event_dispatcher"/>
</service>
```

#### Adjusting the controller

Theoretically, this is all your page loader does - but it's not being used yet. Therefore, you have to inject your page loader to your custom controller and execute the `load` method.

```php
// <plugin root>/src/Storefront/Controller/ExampleController.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

...

class ExampleController extends StorefrontController
{
    private ExamplePageLoader $examplePageLoader;

    public function __construct(ExamplePageLoader $examplePageLoader)
    {
        $this->examplePageLoader = $examplePageLoader;
    }

    #[Route(path: '/example-page', name: 'frontend.example.page', methods: ['GET'])]
    public function examplePage(Request $request, SalesChannelContext $context): Response
    {
        $page = $this->examplePageLoader->load($request, $context);

        return $this->renderStorefront('@SwagBasicExample/storefront/page/example/index.html.twig', [
            'example' => 'Hello world',
            'page' => $page
        ]);
    }
}
```

Note, that we've added the page to the template variables.

### Creating the example page

So now we're going to create the example page class, that was already used in our page loader, `ExamplePage`.

It has to extend from the `Shopware\Storefront\Page\Page` class in order to contain a field for the header, the footer etc., as well as some helper methods.

Let's have a look at an example:

```php
// <plugin root>/src/Storefront/Page/Example/ExamplePage.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Page\Example;

use Shopware\Storefront\Page\Page;
use Swag\BasicExample\Core\Content\Example\ExampleEntity;

class ExamplePage extends Page
{
    protected ExampleEntity $exampleData;

    public function getExampleData(): ExampleEntity
    {
        return $this->exampleData;
    }

    public function setExampleData(ExampleEntity $exampleData): void
    {
        $this->exampleData = $exampleData;
    }
}
```

As explained in the page loader section, your page can contain all kinds of custom data. It has to provide a getter and a setter for the custom data, so it can be applied and read. In this example, the entity from our guide about [creating custom complex data](../framework/data-handling/add-custom-complex-data#Entity%20class) is being used.

And that's it already. Your page is ready to go.

### Creating the page loaded event

One more class is missing, the custom event class. It has to extend from the `Shopware\Storefront\Page\PageLoadedEvent` class.

Its constructor parameter will be the `ExamplePage`, which it has to save into a property and there needs to be a getter in order to get the example page instance. Additional constructor parameters are the `Request` and the `SalesChannelContext`, which you have to pass to the parent's constructor.

Here's the example:

```php
// <plugin root>/src/Storefront/Page/Example/ExamplePageLoadedEvent.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Page\Example;

use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Page\PageLoadedEvent;
use Symfony\Component\HttpFoundation\Request;

class ExamplePageLoadedEvent extends PageLoadedEvent
{
    protected ExamplePage $page;

    public function __construct(ExamplePage $page, SalesChannelContext $salesChannelContext, Request $request)
    {
        $this->page = $page;
        parent::__construct($salesChannelContext, $request);
    }

    public function getPage(): ExamplePage
    {
        return $this->page;
    }
}
```

And that's it for your `ExamplePageLoadedEvent` class.

Your example page should now be fully functioning.

## Next steps

You've now successfully created a whole new page, including a custom controller, a custom template, and the necessary classes to create a new page, a loader, the page struct and the page loaded event.

In your `load` method, you've used the `GenericPageLoader`, which takes care of such a thing as the footer or the header. Those two are so called "pagelets", basically reusable fractions of a page. Learn how to [create a custom pagelet](add-custom-pagelet).

---

---
url: /docs/v6.6/guides/plugins/plugins/storefront/add-custom-page.md
---

# Add Custom Page

## Overview

In this guide you will learn how to create custom page for your Storefront. A page in general consists of a controller, a page loader, a "page loaded" event and a page class, which is like a struct and contains most necessary data for the page.

## Prerequisites

In order to add your own custom page for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide). Since you need to load your page with a controller, you might want to have a look at our guide about [creating a controller](add-custom-controller) first. The controller created in the previously mentioned controller guide will also be used in this guide.

## Adding custom page

In the following sections, we'll create each of the necessary classes one by one. The first one will be controller, whose creation is not going to explained here again. Have a look at the guide about [creating a controller](add-custom-controller) to see why it works.

### Creating ExampleController

Let's have a look at an example controller.

```php
// <plugin root>/src/Storefront/Controller/ExampleController.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

use Shopware\Storefront\Controller\StorefrontController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

#[Route(defaults: ['_routeScope' => ['storefront']])]
class ExampleController extends StorefrontController
{
    #[Route(path: '/example-page', name: 'frontend.example.page', methods: ['GET'])]
    public function examplePage(): Response
    {
    }
}
```

It has a method `examplePage`, which is accessible via the route `example-page`. This method will be responsible for loading your page later on, but we'll leave it like that for now.

Don't forget to [register your controller via the DI](add-custom-controller#services-xml-example).

### Creating the pageloader

In order to stick to Shopware's default location for the page loader, we'll have to create a new directory: `<plugin root>/src/Storefront/Page/Example`.

In there, we will proceed to create all page related classes, such as the page loader.

Go ahead and create a new file called `ExamplePageLoader.php`. It's a new service, which doesn't have to extend from any other class. You might want to implement a `ExamplePageLoaderInterface` interface, which is not explained in this guide. You can do that in order to have a decoratable page loader class.

The page loader is responsible for creating your page class instance (`ExamplePage`, will be created in the next section), filling it with data, e.g. from store api, and firing a `PageLoaded` event, so others can react to your page being loaded.
Do not use a repository directly in a page loader. Always get the data for your pages from a store api route instead.

Let's have a look at a full example `ExamplePageLoader`:

```php
// <plugin root>/src/Storefront/Page/Example/ExamplePageLoader.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Page\Example;

use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Page\GenericPageLoaderInterface;
use Symfony\Component\EventDispatcher\EventDispatcherInterface;
use Symfony\Component\HttpFoundation\Request;

class ExamplePageLoader
{
    private GenericPageLoaderInterface $genericPageLoader;

    private EventDispatcherInterface $eventDispatcher;

    public function __construct(GenericPageLoaderInterface $genericPageLoader, EventDispatcherInterface $eventDispatcher)
    {
        $this->genericPageLoader = $genericPageLoader;
        $this->eventDispatcher = $eventDispatcher;
    }

    public function load(Request $request, SalesChannelContext $context): ExamplePage
    {
        $page = $this->genericPageLoader->load($request, $context);
        $page = ExamplePage::createFrom($page);

        // Do additional stuff, e.g. load more data from store api and add it to page
         $page->setExampleData(...);

        $this->eventDispatcher->dispatch(
            new ExamplePageLoadedEvent($page, $context, $request)
        );

        return $page;
    }
}
```

So first of all, as already mentioned: This is a new class or service, which doesn't have to extend from any other class. The constructor is passed two arguments: The `GenericPageLoaderInterface` and the `EventDispatcherInterface`.

The first one is not necessary, but useful, since it loads all kind of default page stuff, such as a footer and a header and loads some additional helpful data. Once again, you don't have to do that, but if you want your page to have a footer etc., you should add it.

The `EventDispatcherInterface` is of course necessary in order to fire an event later on.

Every page loader should implement a `load` method, which is not mandatory, but convention. You want your page loader to work like all the other page loaders, right? It should return an instance of your example page, in this case `ExamplePage`. Don't worry, we haven't created that one yet, it will be created in the next sections. So, the first thing it does is basically creating a `Page` instance, containing all necessary basic data, such as the footer etc.

Afterwards you're creating your own page instance by using the method `createFrom`. This method is available, since your `ExamplePage` has to extend from the `Page` struct, which in return extends from the `Struct` class. The latter implements the [CreateFromTrait](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Core/Framework/Struct/CreateFromTrait.php) containing this method. In short, this will create an instance of your `ExamplePage`, containing all the data from the generic `Page` object.

Afterwards, you can add more data to your page instance by using a setter. Of course, your example page class then has to have such a setter method, as well as a getter.

As already mentioned, you should also fire an event once your page was loaded. For this case, you need a custom page loaded event class, which is also created in the next sections. It will be called `ExamplePageLoadedEvent`.

The last thing to do in this method is to return your new page instance.

Remember to register your new page loader in the DI container:

```html
// <plugin root>/src/Resources/config/services.xml
<service id="Swag\BasicExample\Storefront\Page\Example\ExamplePageLoader" public="true">
    <argument type="service" id="Shopware\Storefront\Page\GenericPageLoader" />
    <argument type="service" id="event_dispatcher"/>
</service>
```

#### Adjusting the controller

Theoretically, this is all your page loader does - but it's not being used yet. Therefore, you have to inject your page loader to your custom controller and execute the `load` method.

```php
// <plugin root>/src/Storefront/Controller/ExampleController.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

...

class ExampleController extends StorefrontController
{
    private ExamplePageLoader $examplePageLoader;

    public function __construct(ExamplePageLoader $examplePageLoader)
    {
        $this->examplePageLoader = $examplePageLoader;
    }

    #[Route(path: '/example-page', name: 'frontend.example.page', methods: ['GET'])]
    public function examplePage(Request $request, SalesChannelContext $context): Response
    {
        $page = $this->examplePageLoader->load($request, $context);

        return $this->renderStorefront('@SwagBasicExample/storefront/page/example/index.html.twig', [
            'example' => 'Hello world',
            'page' => $page
        ]);
    }
}
```

Note, that we've added the page to the template variables.

#### Adjusting the services.xml

In addition, it is necessary to pass the argument with the ID of the `ExamplePageLoader` class to the [configuration](add-custom-controller#services-xml-example) of the controller service in the `services.xml`.

```html
// <plugin root>/src/Resources/config/services.xml
<service id="Swag\BasicExample\Storefront\Controller\ExampleController" public="true">
    <argument type="service" id="Swag\BasicExample\Storefront\Page\Example\ExamplePageLoader" />
    <call method="setContainer">
        <argument type="service" id="service_container"/>
    </call>
    <call method="setTwig">
        <argument type="service" id="twig"/>
    </call>
</service>
```

### Creating the example page

So now we're going to create the example page class, that was already used in our page loader, `ExamplePage`.

It has to extend from the `Shopware\Storefront\Page\Page` class in order to contain a field for the header, the footer etc., as well as some helper methods.

Let's have a look at an example:

```php
// <plugin root>/src/Storefront/Page/Example/ExamplePage.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Page\Example;

use Shopware\Storefront\Page\Page;
use Swag\BasicExample\Core\Content\Example\ExampleEntity;

class ExamplePage extends Page
{
    protected ExampleEntity $exampleData;

    public function getExampleData(): ExampleEntity
    {
        return $this->exampleData;
    }

    public function setExampleData(ExampleEntity $exampleData): void
    {
        $this->exampleData = $exampleData;
    }
}
```

As explained in the page loader section, your page can contain all kinds of custom data. It has to provide a getter and a setter for the custom data, so it can be applied and read. In this example, the entity from our guide about [creating custom complex data](../framework/data-handling/add-custom-complex-data#entity-class) is being used.

And that's it already. Your page is ready to go.

### Creating the page loaded event

One more class is missing, the custom event class. It has to extend from the `Shopware\Storefront\Page\PageLoadedEvent` class.

Its constructor parameter will be the `ExamplePage`, which it has to save into a property and there needs to be a getter in order to get the example page instance. Additional constructor parameters are the `Request` and the `SalesChannelContext`, which you have to pass to the parent's constructor.

Here's the example:

```php
// <plugin root>/src/Storefront/Page/Example/ExamplePageLoadedEvent.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Page\Example;

use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Page\PageLoadedEvent;
use Symfony\Component\HttpFoundation\Request;

class ExamplePageLoadedEvent extends PageLoadedEvent
{
    protected ExamplePage $page;

    public function __construct(ExamplePage $page, SalesChannelContext $salesChannelContext, Request $request)
    {
        $this->page = $page;
        parent::__construct($salesChannelContext, $request);
    }

    public function getPage(): ExamplePage
    {
        return $this->page;
    }
}
```

And that's it for your `ExamplePageLoadedEvent` class.

Your example page should now be fully functioning.

## Next steps

You've now successfully created a whole new page, including a custom controller, a custom template, and the necessary classes to create a new page, a loader, the page struct and the page loaded event.

In your `load` method, you've used the `GenericPageLoader`, which takes care of such a thing as the footer or the header. Those two are so called "pagelets", basically reusable fractions of a page. Learn how to [create a custom pagelet](add-custom-pagelet).

---

---
url: /docs/guides/plugins/plugins/storefront/controllers/add-custom-pagelet.md
---

# Add Custom Pagelet

## Overview

In this guide, you will learn how to create custom pagelets for your Storefront pages.

In short: Pages are exactly that, a fully functioning page of your store with a template loaded by a route. A pagelet is an important and reusable fraction of several pages, such as a footer or the navigation.

## Prerequisites

To add your own custom pagelet for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../../plugin-base-guide.md). Since a pagelet is just part of another page, we are going to use the page created in our guide about [adding a custom page](../controllers/add-custom-page.md).

## Adding custom pagelet

Basically a pagelet is created exactly like a page: You need a pagelet loader, a pagelet struct to hold the data and a pagelet loaded event.

Since creating this kind of classes is explained in detail in our guide about [adding a custom page](../controllers/add-custom-page.md), it is not going to be explained here in detail again. Yet, there's some differences worth mentioning:

* The struct to hold the data has to extend from the `Shopware\Storefront\Pagelet\Pagelet` class instead of `Shopware\Storefront\Page\Page`

* A pagelet doesn't have to be bound to a controller, e.g. with an extra route. It can have a route though!

* A pagelet is mostly loaded by another page or multiple pages, that's their purpose

* The `GenericPageLoaderInterface` is not used, since it is responsible to load the footer or header pagelet. You don't want to load

  a pagelet (footer or header) into your pagelet

* The pagelet instance is not created via `Pagelet::createFrom()`, but rather you just create a new instance yourself. That's because the

  `Pagelet::createFrom()` was only necessary to create a new instance of your page, which already contains the footer & header pagelets.

  Once again: You don't want that in your pagelet.

* The pagelet loaded event class extends from `Shopware\Storefront\Pagelet\PageletLoadedEvent` instead of `Shopware\Storefront\Page\PageLoadedEvent`

Let's now have a look at the example classes. The pagelet is going to be called `ExamplePagelet` in the following examples.

### The ExamplePageletLoader

::: code-group

```php [PLUGIN_ROOT/src/Storefront/Pagelet/Example/ExamplePageletLoader.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Pagelet\Example;

use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Page\GenericPageLoaderInterface;
use Symfony\Component\EventDispatcher\EventDispatcherInterface;
use Symfony\Component\HttpFoundation\Request;

class ExamplePageletLoader
{
    private EventDispatcherInterface $eventDispatcher;

    public function __construct(EventDispatcherInterface $eventDispatcher)
    {
        $this->eventDispatcher = $eventDispatcher;
    }

    public function load(Request $request, SalesChannelContext $context): ExamplePagelet
    {
        $pagelet = new ExamplePagelet();

        // Do additional stuff, e.g. load more data from store-api and add it to page
        $pagelet->setExampleData(...);

        $this->eventDispatcher->dispatch(
            new ExamplePageletLoadedEvent($pagelet, $context, $request)
        );

        return $pagelet;
    }
}
```

:::

Note the instance creation without the `::createFrom()` call.
The rest is quite equal, you can load your data, set it to the pagelet struct, you fire an event, and you return the pagelet.

### The ExamplePagelet struct

::: code-group

```php [PLUGIN_ROOT/src/Storefront/Pagelet/Example/ExamplePagelet.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Pagelet\Example;

use Shopware\Storefront\Pagelet\Pagelet;
use Swag\BasicExample\Core\Content\Example\ExampleEntity;

class ExamplePagelet extends Pagelet
{
    protected ExampleEntity $exampleData;

    public function getExampleData(): ExampleEntity
    {
        return $this->exampleData;
    }

    public function setExampleData(ExampleEntity $exampleData): void
    {
        $this->exampleData = $exampleData;
    }
}
```

:::

Just like the page struct, this is basically just a class holding data.
Note the different `extend` though, you're not extending from `Shopware\Storefront\Page\Page` here.

### The ExamplePageletLoadedEvent

::: code-group

```php [PLUGIN_ROOT/src/Storefront/Pagelet/Example/ExamplePageletLoadedEvent.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Pagelet\Example;

use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Pagelet\PageletLoadedEvent;
use Symfony\Component\HttpFoundation\Request;

class ExamplePageletLoadedEvent extends PageletLoadedEvent
{
    protected ExamplePagelet $pagelet;

    public function __construct(ExamplePagelet $pagelet, SalesChannelContext $salesChannelContext, Request $request)
    {
        $this->pagelet = $pagelet;
        parent::__construct($salesChannelContext, $request);
    }

    public function getPagelet(): ExamplePagelet
    {
        return $this->pagelet;
    }
}
```

:::

Note the different `extends`, which uses the `PageletLoadedEvent` class instead.
Also, the getter method is no longer `getPage`, but `getPagelet` instead.

## Loading the pagelet

### Loading the pagelet via another page

Most times you want to load your pagelet as part of another page.
This is simply done by calling the `load` method of your pagelet in another page's `load` method.

Using the example from our [adding a custom page](../controllers/add-custom-page.md) guide, this is what the `load` method could look like:

::: code-group

```php [PLUGIN_ROOT/src/Storefront/Page/Example/ExamplePageLoader.php]
public function load(Request $request, SalesChannelContext $context): ExamplePage
{
    $page = $this->genericPageLoader->load($request, $context);
    $page = ExamplePage::createFrom($page);

    $page->setExamplePagelet($this->examplePageletLoader->load($request, $context));

    // Do additional stuff, e.g. load more data from store-api and add it to page
    $page->setExampleData(...);

    $this->eventDispatcher->dispatch(
        new ExamplePageletLoadedEvent($page, $context, $request)
    );

    return $page;
}
```

:::

Of course, in this example your `ExamplePage` struct needs a method `setExamplePagelet`, as well as the respective getter method `getExamplePagelet`.
And then that's it, you've loaded your pagelet as part of another page.

### Loading the pagelet via route

As already mentioned, a pagelet can be loaded via a route if you want it to.
For that case, you can add a new route to your controller and load the pagelet via the `ExamplePageletLoader`:

```php
#[Route(path: '/example-pagelet', name: 'frontend.example.pagelet', methods: ['POST'], defaults: ['XmlHttpRequest' => 'true'])]
public function examplePagelet(Request $request, SalesChannelContext $context): Response
{
    $pagelet = $this->examplePageletLoader->load($request, $context);

    return $this->renderStorefront('@Storefront/storefront/pagelet/example/index.html.twig', [
        'pagelet' => $pagelet
    ]);
}
```

Using the part `defaults: ['XmlHttpRequest' => true]` in the attribute ensures that this pagelet can be loaded using an XML HTTP Request.

---

---
url: /docs/v6.5/guides/plugins/plugins/storefront/add-custom-pagelet.md
---

# Add Custom Pagelet

## Overview

In this guide you will learn how to create custom pagelets for your Storefront pages.

In short: Pages are exactly that, a fully functioning page of your store with a template loaded by a route. A pagelet is an important and reusable fraction of several pages, such as a footer or the navigation.

## Prerequisites

In order to add your own custom pagelet for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide). Since a pagelet is just part of another page, we are going to use the page created in our guide about [adding a custom page](add-custom-page).

## Adding custom pagelet

Basically a pagelet is created exactly like a page: You need a pagelet loader, a pagelet struct to hold the data and a pagelet loaded event.

Since creating this kind of classes is explained in detail in our guide about [adding a custom page](add-custom-page), it is not going to be explained here in detail again. Yet, there's some differences worth mentioning:

* The struct to hold the data has to extend from the `Shopware\Storefront\Pagelet\Pagelet` class instead of `Shopware\Storefront\Page\Page`

* A pagelet doesn't have to be bound to a controller, e.g. with an extra route. It can have a route though!

* A pagelet is mostly loaded by another page or multiple pages, that's their purpose

* The `GenericPageLoaderInterface` is not used, since it is responsible to load the footer or header pagelet. You don't want to load

  a pagelet (footer or header) into your pagelet

* The pagelet instance is not created via `Pagelet::createFrom()`, but rather you just create a new instance yourself. That's because the

  `Pagelet::createFrom()` was only necessary to create a new instance of your page, which already contains the footer & header pagelets.

  Once again: You don't want that in your pagelet.

* The pagelet loaded event class extends from `Shopware\Storefront\Pagelet\PageletLoadedEvent` instead of `Shopware\Storefront\Page\PageLoadedEvent`

Let's now have a look at the example classes. The pagelet is going to be called `ExamplePagelet` in the following examples.

### The ExamplePageletLoader

```php
// <plugin root>/src/Storefront/Pagelet/Example/ExamplePageletLoader.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Pagelet\Example;

use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Page\GenericPageLoaderInterface;
use Symfony\Component\EventDispatcher\EventDispatcherInterface;
use Symfony\Component\HttpFoundation\Request;

class ExamplePageletLoader
{
    private EventDispatcherInterface $eventDispatcher;

    public function __construct(EventDispatcherInterface $eventDispatcher)
    {
        $this->eventDispatcher = $eventDispatcher;
    }

    public function load(Request $request, SalesChannelContext $context): ExamplePagelet
    {
        $pagelet = new ExamplePagelet();

        // Do additional stuff, e.g. load more data from store-api and add it to page
        $pagelet->setExampleData(...);

        $this->eventDispatcher->dispatch(
            new ExamplePageletLoadedEvent($pagelet, $context, $request)
        );

        return $pagelet;
    }
}
```

Note the instance creation without the `::createFrom()` call. The rest is quite equal, you can load your data, set it to the pagelet struct, you fire an event and you return the pagelet.

### The ExamplePagelet struct

```php
// <plugin root>/src/Storefront/Pagelet/Example/ExamplePagelet.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Pagelet\Example;

use Shopware\Storefront\Pagelet\Pagelet;
use Swag\BasicExample\Core\Content\Example\ExampleEntity;

class ExamplePagelet extends Pagelet
{
    protected ExampleEntity $exampleData;

    public function getExampleData(): ExampleEntity
    {
        return $this->exampleData;
    }

    public function setExampleData(ExampleEntity $exampleData): void
    {
        $this->exampleData = $exampleData;
    }
}
```

Just like the page struct, this is basically just a class holding data. Note the different `extend` though, you're not extending from `Shopware\Storefront\Page\Page` here. It only contained helper method for the header & footer pagelets.

### The ExamplePageletLoadedEvent

```php
// <plugin root>/src/Storefront/Pagelet/Example/ExamplePageletLoadedEvent.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Pagelet\Example;

use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Pagelet\PageletLoadedEvent;
use Symfony\Component\HttpFoundation\Request;

class ExamplePageletLoadedEvent extends PageletLoadedEvent
{
    protected ExamplePagelet $pagelet;

    public function __construct(ExamplePagelet $pagelet, SalesChannelContext $salesChannelContext, Request $request)
    {
        $this->pagelet = $pagelet;
        parent::__construct($salesChannelContext, $request);
    }

    public function getPagelet(): ExamplePagelet
    {
        return $this->pagelet;
    }
}
```

Note the different `extends`, which uses the `PageletLoadedEvent` class instead. Also, the getter method is no longer `getPage`, but `getPagelet` instead.

## Loading the pagelet

### Loading the pagelet via another page

Most times you want to load your pagelet as part of another page. This is simply done by calling the `load` method of your pagelet in another page's `load` method.

Using the example from our [adding a custom page](add-custom-page) guide, this is what the `load` method could look like:

```php
// <plugin root>/src/Storefront/Page/Example/ExamplePageLoader.php
public function load(Request $request, SalesChannelContext $context): ExamplePage
{
    $page = $this->genericPageLoader->load($request, $context);
    $page = ExamplePage::createFrom($page);

    $page->setExamplePagelet($this->examplePageletLoader->load($request, $context));

    // Do additional stuff, e.g. load more data from store-api and add it to page
     $page->setExampleData(...);

    $this->eventDispatcher->dispatch(
        new ExamplePageletLoadedEvent($page, $context, $request)
    );

    return $page;
}
```

Of course, in this example your `ExamplePage` struct needs a method `setExamplePagelet`, as well as the respective getter method `getExamplePagelet`. And then that's it, you've loaded your pagelet as part of another page.

### Loading the pagelet via route

As already mentioned, a pagelet can be loaded via a route if you want it to. For that case, you can simply add a new route to your controller and load the pagelet via the `ExamplePageletLoader`:

```php
#[Route(path: '/example-pagelet', name: 'frontend.example.pagelet', methods: ['POST'], defaults: ['XmlHttpRequest' => 'true'])]
public function examplePagelet(Request $request, SalesChannelContext $context): Response
{
    $pagelet = $this->examplePageletLoader->load($request, $context);

    return $this->renderStorefront('@Storefront/storefront/pagelet/example/index.html.twig', [
        'pagelet' => $pagelet
    ]);
}
```

Using the part `defaults={"XmlHttpRequest"=true}` in the annotation ensures, that this pagelet can be loaded using an XML HTTP Request.

---

---
url: /docs/v6.6/guides/plugins/plugins/storefront/add-custom-pagelet.md
---

# Add Custom Pagelet

## Overview

In this guide you will learn how to create custom pagelets for your Storefront pages.

In short: Pages are exactly that, a fully functioning page of your store with a template loaded by a route. A pagelet is an important and reusable fraction of several pages, such as a footer or the navigation.

## Prerequisites

In order to add your own custom pagelet for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide). Since a pagelet is just part of another page, we are going to use the page created in our guide about [adding a custom page](add-custom-page).

## Adding custom pagelet

Basically a pagelet is created exactly like a page: You need a pagelet loader, a pagelet struct to hold the data and a pagelet loaded event.

Since creating this kind of classes is explained in detail in our guide about [adding a custom page](add-custom-page), it is not going to be explained here in detail again. Yet, there's some differences worth mentioning:

* The struct to hold the data has to extend from the `Shopware\Storefront\Pagelet\Pagelet` class instead of `Shopware\Storefront\Page\Page`

* A pagelet doesn't have to be bound to a controller, e.g. with an extra route. It can have a route though!

* A pagelet is mostly loaded by another page or multiple pages, that's their purpose

* The `GenericPageLoaderInterface` is not used, since it is responsible to load the footer or header pagelet. You don't want to load

  a pagelet (footer or header) into your pagelet

* The pagelet instance is not created via `Pagelet::createFrom()`, but rather you just create a new instance yourself. That's because the

  `Pagelet::createFrom()` was only necessary to create a new instance of your page, which already contains the footer & header pagelets.

  Once again: You don't want that in your pagelet.

* The pagelet loaded event class extends from `Shopware\Storefront\Pagelet\PageletLoadedEvent` instead of `Shopware\Storefront\Page\PageLoadedEvent`

Let's now have a look at the example classes. The pagelet is going to be called `ExamplePagelet` in the following examples.

### The ExamplePageletLoader

```php
// <plugin root>/src/Storefront/Pagelet/Example/ExamplePageletLoader.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Pagelet\Example;

use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Page\GenericPageLoaderInterface;
use Symfony\Component\EventDispatcher\EventDispatcherInterface;
use Symfony\Component\HttpFoundation\Request;

class ExamplePageletLoader
{
    private EventDispatcherInterface $eventDispatcher;

    public function __construct(EventDispatcherInterface $eventDispatcher)
    {
        $this->eventDispatcher = $eventDispatcher;
    }

    public function load(Request $request, SalesChannelContext $context): ExamplePagelet
    {
        $pagelet = new ExamplePagelet();

        // Do additional stuff, e.g. load more data from store-api and add it to page
        $pagelet->setExampleData(...);

        $this->eventDispatcher->dispatch(
            new ExamplePageletLoadedEvent($pagelet, $context, $request)
        );

        return $pagelet;
    }
}
```

Note the instance creation without the `::createFrom()` call. The rest is quite equal, you can load your data, set it to the pagelet struct, you fire an event and you return the pagelet.

### The ExamplePagelet struct

```php
// <plugin root>/src/Storefront/Pagelet/Example/ExamplePagelet.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Pagelet\Example;

use Shopware\Storefront\Pagelet\Pagelet;
use Swag\BasicExample\Core\Content\Example\ExampleEntity;

class ExamplePagelet extends Pagelet
{
    protected ExampleEntity $exampleData;

    public function getExampleData(): ExampleEntity
    {
        return $this->exampleData;
    }

    public function setExampleData(ExampleEntity $exampleData): void
    {
        $this->exampleData = $exampleData;
    }
}
```

Just like the page struct, this is basically just a class holding data. Note the different `extend` though, you're not extending from `Shopware\Storefront\Page\Page` here. It only contained helper method for the header & footer pagelets.

### The ExamplePageletLoadedEvent

```php
// <plugin root>/src/Storefront/Pagelet/Example/ExamplePageletLoadedEvent.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Pagelet\Example;

use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Pagelet\PageletLoadedEvent;
use Symfony\Component\HttpFoundation\Request;

class ExamplePageletLoadedEvent extends PageletLoadedEvent
{
    protected ExamplePagelet $pagelet;

    public function __construct(ExamplePagelet $pagelet, SalesChannelContext $salesChannelContext, Request $request)
    {
        $this->pagelet = $pagelet;
        parent::__construct($salesChannelContext, $request);
    }

    public function getPagelet(): ExamplePagelet
    {
        return $this->pagelet;
    }
}
```

Note the different `extends`, which uses the `PageletLoadedEvent` class instead. Also, the getter method is no longer `getPage`, but `getPagelet` instead.

## Loading the pagelet

### Loading the pagelet via another page

Most times you want to load your pagelet as part of another page. This is simply done by calling the `load` method of your pagelet in another page's `load` method.

Using the example from our [adding a custom page](add-custom-page) guide, this is what the `load` method could look like:

```php
// <plugin root>/src/Storefront/Page/Example/ExamplePageLoader.php
public function load(Request $request, SalesChannelContext $context): ExamplePage
{
    $page = $this->genericPageLoader->load($request, $context);
    $page = ExamplePage::createFrom($page);

    $page->setExamplePagelet($this->examplePageletLoader->load($request, $context));

    // Do additional stuff, e.g. load more data from store-api and add it to page
     $page->setExampleData(...);

    $this->eventDispatcher->dispatch(
        new ExamplePageletLoadedEvent($page, $context, $request)
    );

    return $page;
}
```

Of course, in this example your `ExamplePage` struct needs a method `setExamplePagelet`, as well as the respective getter method `getExamplePagelet`. And then that's it, you've loaded your pagelet as part of another page.

### Loading the pagelet via route

As already mentioned, a pagelet can be loaded via a route if you want it to. For that case, you can simply add a new route to your controller and load the pagelet via the `ExamplePageletLoader`:

```php
#[Route(path: '/example-pagelet', name: 'frontend.example.pagelet', methods: ['POST'], defaults: ['XmlHttpRequest' => 'true'])]
public function examplePagelet(Request $request, SalesChannelContext $context): Response
{
    $pagelet = $this->examplePageletLoader->load($request, $context);

    return $this->renderStorefront('@Storefront/storefront/pagelet/example/index.html.twig', [
        'pagelet' => $pagelet
    ]);
}
```

Using the part `defaults: ['XmlHttpRequest' => true]` in the attribute ensures, that this pagelet can be loaded using an XML HTTP Request.

---

---
url: /docs/v6.5/guides/plugins/plugins/administration/add-custom-route.md
---

# Add custom route

Routes in the Shopware 6 Administration are essentially the same as in any other [Vue Router](https://router.vuejs.org). This guide will teach you the basics of creating your very first route from scratch.

## Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files and preferably a registered module. Of course you'll have to understand JavaScript, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation.

## Configuring the route

So lets start with configuring our own route. In order to add routes to a module you simply add the `routes` property, which expects an object containing multiple route configuration objects. Each route configuration object needs to have a `name`, which is set using the configuration object's key. Furthermore, we need to set a component and a path: A route points to a [component](https://vuejs.org/v2/guide/components.html) using the key `component`, which targets the component to be shown when this route is requested. The key `path` represents the actual path, that's going to be used for this route. Do not get confused just because it is equal to the route name in the first route.

Now, our route should look like this:

```javascript
// routes: {
//     nameOfTheRoute: {
//         component: 'example',
//         path: 'actualPathInTheBrowser'
//     }
// }
routes: {
    overview: {
        component: 'sw-product-list',
        path: 'overview'
    },
},
```

Routes can be matched by name and path. This configuration results in this route's full name being `custom.module.overview` and the URL being `/overview` relative to the Administration's default URL. Usually you want to render your custom component here, which is explained [here](add-custom-component). But that is not all! Routes can have parameters, to then be handed to the components being rendered and much more. Learn more about what the Vue Router can do in its official [Documentation](https://router.vuejs.org/guide/essentials/dynamic-matching.html#reacting-to-params-changes).

## Meta data and dynamic parameters

Let's extend this example:

```javascript
Shopware.Module.register('swag-example', {
    color: '#ff3d58',
    icon: 'default-shopping-paper-bag-product',
    title: 'My custom module',
    description: 'Manage your custom module here.',

    routes: {
        overview: {
            component: 'swag-example-list',
            path: 'overview'
        },
        // This is our second route
        detail: {
            component: 'sw-example-detail',
            path: 'detail/:id',
            meta: {
                parentPath: 'swag.example.list'
            }
        }
    },
});
```

This second route, `detail`, comes with a dynamic parameter as part of the route. When you want to open a detail page of an example, the route also has to contain the ID of the example, in the `path` of `detail`:

```javascript
path: 'detail/:id'
```

Furthermore, the `detail` route comes with another new configuration, which is called `meta`. As the name suggests, you can use this object to apply more meta information for your route. In this case the `parentPath` is filled. Its purpose is to link the path of the actual parent route. In the Administration, this results in a "back" button on the top left of your module when being on the detail page. This button will then link back to the list route and the icon defined earlier will also be used for this button.

You might want to have a closer look at the `parentPath` value though. Its route follows this pattern: `<bundle-name>.<name of the route>`

See in this example:

```javascript
...
   meta: {
       parentPath: 'swag.example.list'
   }
...
```

The `bundle-name` is separated by dots instead of dashes here though. The second part is the **name** of the route, the key of the route configuration that is. Thus the path to the `list` route is `swag.example.list`. The same applies for the `create` route.

## More interesting topics

* [Adding a custom service](add-custom-service)
* [Customizing a module](customizing-modules)
* [Adding permissions](add-acl-rules)

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/administration/routing-navigation/add-custom-route.md
---

# Add custom route

Routes in the Shopware 6 Administration are essentially the same as in any other [Vue Router](https://router.vuejs.org). This guide will teach you the basics of creating your very first route from scratch.

## Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files and preferably a registered module. Of course you'll have to understand JavaScript, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation.

## Configuring the route

So lets start with configuring our own route. In order to add routes to a module you simply add the `routes` property, which expects an object containing multiple route configuration objects. Each route configuration object needs to have a `name`, which is set using the configuration object's key. Furthermore, we need to set a component and a path: A route points to a [component](https://vuejs.org/v2/guide/components.html) using the key `component`, which targets the component to be shown when this route is requested. The key `path` represents the actual path, that's going to be used for this route. Do not get confused just because it is equal to the route name in the first route.

Now, our route should look like this:

```javascript
// routes: {
//     nameOfTheRoute: {
//         component: 'example',
//         path: 'actualPathInTheBrowser'
//     }
// }
routes: {
    overview: {
        component: 'sw-product-list',
        path: 'overview'
    },
},
```

Routes can be matched by name and path. This configuration results in this route's full name being `custom.module.overview` and the URL being `/custom/module/overview` relative to the Administration's default URL. The routes full name is a combination of the module's id and the name of the item inside the `routes` object. In this case the module's id is `custom-module` (Notice that all dashes are automatically replaced by dots in the final route name).

Usually you want to render your custom component here, which is explained [here](../module-component-management/add-custom-component.md). But that is not all! Routes can have parameters, to then be handed to the components being rendered and much more. Learn more about what the Vue Router can do in its official [Documentation](https://router.vuejs.org/guide/essentials/dynamic-matching.html#reacting-to-params-changes).

## Meta data and dynamic parameters

Let's extend this example:

```javascript
Shopware.Module.register('swag-example', {
    color: '#ff3d58',
    icon: 'default-shopping-paper-bag-product',
    title: 'My custom module',
    description: 'Manage your custom module here.',

    routes: {
        overview: {
            component: 'swag-example-list',
            path: 'overview'
        },
        // This is our second route
        detail: {
            component: 'sw-example-detail',
            path: 'detail/:id',
            meta: {
                parentPath: 'swag.example.list'
            }
        }
    },
});
```

This second route, `detail`, comes with a dynamic parameter as part of the route. When you want to open a detail page of an example, the route also has to contain the ID of the example, in the `path` of `detail`:

```javascript
path: 'detail/:id'
```

Furthermore, the `detail` route comes with another new configuration, which is called `meta`. As the name suggests, you can use this object to apply more meta information for your route. In this case the `parentPath` is filled. Its purpose is to link the path of the actual parent route. In the Administration, this results in a "back" button on the top left of your module when being on the detail page. This button will then link back to the list route and the icon defined earlier will also be used for this button.

You might want to have a closer look at the `parentPath` value though. Its route follows this pattern: `<bundle-name>.<name of the route>`

See in this example:

```javascript
...
   meta: {
       parentPath: 'swag.example.list'
   }
...
```

The `bundle-name` is separated by dots instead of dashes here though. The second part is the **name** of the route, the key of the route configuration that is. Thus the path to the `list` route is `swag.example.list`. The same applies for the `create` route.

## More interesting topics

* [Adding a custom service](../services-utilities/add-custom-service.md)
* [Customizing a module](../module-component-management/customizing-modules.md)
* [Adding permissions](../permissions-error-handling/add-acl-rules.md)

---

---
url: >-
  /docs/guides/plugins/plugins/administration/routing-navigation/add-custom-route.md
---

# Add Custom Route

## Overview

Routes in the Shopware 6 Administration are essentially the same as in any other [Vue Router](https://router.vuejs.org). This guide will teach you the basics of creating your very first route from scratch.

## Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files and preferably a registered module. Of course you'll have to understand JavaScript, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation.

## Configuring the route

So lets start with configuring our own route. In order to add routes to a module you simply add the `routes` property, which expects an object containing multiple route configuration objects. Each route configuration object needs to have a `name`, which is set using the configuration object's key. Furthermore, we need to set a component and a path: A route points to a [component](https://vuejs.org/guide/essentials/component-basics.html) using the key `component`, which targets the component to be shown when this route is requested. The key `path` represents the actual path, that's going to be used for this route. Do not get confused just because it is equal to the route name in the first route.

Now, our route should look like this:

```javascript
// routes: {
//     nameOfTheRoute: {
//         component: 'example',
//         path: 'actualPathInTheBrowser'
//     }
// }
routes: {
    overview: {
        component: 'sw-product-list',
        path: 'overview'
    },
},
```

Routes can be matched by name and path. This configuration results in this route's full name being `custom.module.overview` and the URL being `/custom/module/overview` relative to the Administration's default URL. The routes full name is a combination of the module's id and the name of the item inside the `routes` object. In this case the module's id is `custom-module` (Notice that all dashes are automatically replaced by dots in the final route name).

Usually you want to render your custom component here, which is explained [here](../module-component-management/add-custom-component.md). But that is not all! Routes can have parameters, to then be handed to the components being rendered and much more. Learn more about what the Vue Router can do in its official [Documentation](https://router.vuejs.org/guide/essentials/dynamic-matching.html#reacting-to-params-changes).

## Meta data and dynamic parameters

Let's extend this example:

```javascript
Shopware.Module.register('swag-example', {
    color: '#ff3d58',
    icon: 'default-shopping-paper-bag-product',
    title: 'My custom module',
    description: 'Manage your custom module here.',

    routes: {
        overview: {
            component: 'swag-example-list',
            path: 'overview'
        },
        // This is our second route
        detail: {
            component: 'sw-example-detail',
            path: 'detail/:id',
            meta: {
                parentPath: 'swag.example.list'
            }
        }
    },
});
```

This second route, `detail`, comes with a dynamic parameter as part of the route. When you want to open a detail page of an example, the route also has to contain the ID of the example, in the `path` of `detail`:

```javascript
path: 'detail/:id'
```

Furthermore, the `detail` route comes with another new configuration, which is called `meta`. As the name suggests, you can use this object to apply more meta information for your route. In this case the `parentPath` is filled. Its purpose is to link the path of the actual parent route. In the Administration, this results in a "back" button on the top left of your module when being on the detail page. This button will then link back to the list route and the icon defined earlier will also be used for this button.

You might want to have a closer look at the `parentPath` value though. Its route follows this pattern: `<bundle-name>.<name of the route>`

See in this example:

```javascript
...
   meta: {
       parentPath: 'swag.example.list'
   }
...
```

The `bundle-name` is separated by dots instead of dashes here though. The second part is the **name** of the route, the key of the route configuration that is. Thus the path to the `list` route is `swag.example.list`. The same applies for the `create` route.

## More interesting topics

* [Adding a custom service](../services-utilities/add-custom-service.md)
* [Customizing a module](../module-component-management/customizing-modules.md)
* [Adding permissions](../permissions-error-handling/add-acl-rules.md)

---

---
url: /docs/v6.5/guides/plugins/apps/rule-builder/add-custom-rule-conditions.md
---

# Add custom rule conditions

## Overview

In this guide, you'll learn how to make your app introduce custom conditions for use in the [Rule Builder](../../../../concepts/framework/rules). Custom conditions can be defined with fields to be rendered in the Administration and with their own logic, using the same approach as [App Scripts](../app-scripts/).

::: info
Note that app rule conditions were introduced in Shopware 6.4.12.0, and are not supported in previous versions.
:::

## Prerequisites

If you're not familiar with the app system, please take a look at the concept first.

You should also be familiar with the general concept of the Rule Builder.

For the attached logic of your custom conditions, you'll use [twig files](https://twig.symfony.com/). Please refer to the App Scripts guide for a general introduction.

## Definition

App Rule Conditions are defined in the `manifest.xml` file of your app:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        <!-- ... -->
    </meta>
    <rule-conditions>
        <rule-condition>
            <!-- The identifier of the rule condition must be unique should not change. Otherwise a separate rule condition is created and uses of the old one are lost. -->
            <identifier>my_custom_condition</identifier>
            <!-- Translatable, a name of your rule condition -->
            <name>Custom condition</name>
            <name lang="de-DE">Eigene Bedingung</name>
            <!-- A thematic group the condition should be assigned too, available groups are: general, customer, cart, item, promotion, misc -->
            <group>misc</group>
            <!-- The *.twig file that contains the corresponding script for the condition. It must be placed in the directory Resources/scripts/rule-conditions starting from your app's root directory -->
            <script>custom-condition.twig</script>
            <!-- Define the fields you want the user to fill out for use as data within your condition -->
            <constraints>
                <!-- the element type, defines the type of the field -->
                <!-- the elements available here are the same as for custom fields -->
                <single-select name="operator">
                    <placeholder>Choose an operator...</placeholder>
                    <placeholder lang="de-DE">Bitte Operatoren wählen</placeholder>
                    <options>
                        <option value="=">
                            <name>Is equal to</name>
                            <name lang="de-DE">Ist gleich</name>
                        </option>
                        <option value="!=">
                            <name>Is not equal to</name>
                            <name lang="de-DE">Ist nicht gleich</name>
                        </option>
                    </options>
                    <required>true</required>
                </single-select>
                <text name="firstName">
                    <placeholder>Enter first name</placeholder>
                    <placeholder lang="de-DE">Bitte Vornamen eingeben</placeholder>
                    <required>true</required>
                </text>
            </constraints>
        </rule-condition>
    </rule-conditions>
</manifest>

```

For a complete reference of the structure of the manifest file, take a look at the [Manifest reference](../../../../resources/references/app-reference/manifest-reference).

The following fields are required:

* `identifier`: A technical name for the condition that should be unique within the scope of the app. The name is being used to identify existing conditions when updating the app, so it should not be changed.
* `name`: A descriptive and translatable name for the condition. The name will be shown within the Rule Builder's selection of conditions in the Administration.
* `script`: The file name and extension of the file that contains the script for the condition. All scripts for rule conditions must be placed inside `Resources/scripts/rule-conditions` within the root directory of the app.

### Constraints

Constraints are optional and may be used to define fields, whose purpose is to provide data for use within the condition's script.

Constraints are a collection of [custom fields](../custom-data/), which allows you to provide a variety of different fields for setting parameters within the administration. Fields may be marked as `required`. The `name` attribute of the field is also the variable the field's value will be exposed as within the condition's script. So it is advisable to use a variable-friendly name and to use unique names within the confines of a single condition.

The above example will add the condition shown below for selection in the Administration:

![App Rule Condition](../../../../assets/app-rule-condition.png)

## Scripts

The corresponding scripts to the defined conditions within `manifest.xml` need to be placed at a specific directory of your app:

```text
└── DemoApp
    ├── Resources
    │   └── scripts                         // all scripts are stored in this folder
    │       ├── rule-conditions             // reserved for scripts of rule conditions
    │       │   └── custom-condition.twig   // the file name may be freely chosen but must be identical to the corresponding `script` element within `rule-conditions` of `manifest.xml`
    │       └── ...
    └── manifest.xml
```

Scripts for rule conditions are [twig files](https://twig.symfony.com/) that are executed in a sandboxed environment. They offer the same extended syntax and debugging options as [App Scripts](../app-scripts/).

Within the script you will have access to the `scope` variable which is an instance of `RuleScope` as described in the [Rule Builder concept](../../../../concepts/framework/rules). The scope instance provides you with the current `SalesChannelContext` and, given the right scope, the current cart. Further available variables depend on the existence of constraints within the definition of your conditions.

A script *must* return a boolean value, stating whether the condition is true or false. Anything but a boolean returned as value may lead to unexpected behavior.

### Compare helper

To keep condition scripts smaller we provide a `compare` helper function which can be used for the most common comparisons of two values.

The function takes three arguments:

```text
compare(operator, value, comparable)
```

The `operator` *must* be one of the following string values: `=`, `!=`, `>`, `>=`, `<`, `<=`, `empty`

If either one or both of `value` and `comparable` are an array, then only `=` and `!=` should be used as operator. It will then compare whether there is at least one occurrence of the value within the other array and return `true` if that is the case. As an example `value` might be an ID, `comparable` an array of IDs and you could use the function to match whether the ID is included in that array.

### Example

```twig
// Resources/scripts/rule-conditions/custom-condition.twig
{% if scope.salesChannelContext.customer is not defined %}
    {% return false %}
{% endif %}

{% return compare(operator, scope.salesChannelContext.customer.firstName, firstName) %}
```

In the example above, we first check whether we can retrieve the current customer from the instance of `RuleScope` and return `false` otherwise.

We then use the variables `operator` and `firstName`, provided by the constraints of the condition, to evaluate whether the first name in question matches the first name of the current customer. To do so, we make use of the `compare` helper function.

### Line item condition example

```html
// manifest.xml
<!-- ... -->
<rule-condition>
    <identifier>line_item_condition</identifier>
    <name>Custom product multi select</name>
    <group>item</group>
    <script>line-item-condition.twig</script>
    <constraints>
        <single-select name="operator">
            <placeholder>Choose an operator...</placeholder>
            <options>
                <option value="=">
                    <name>Is equal to</name>
                </option>
                <option value="!=">
                    <name>Is not equal to</name>
                </option>
            </options>
            <required>true</required>
        </single-select>
        <multi-entity-select name="productIds">
            <placeholder>Choose products...</placeholder>
            <entity>product</entity>
            <required>true</required>
        </multi-entity-select>
    </constraints>
</rule-condition>
<!-- ... -->
```

```twig
// Resources/scripts/rule-conditions/line-item-condition.twig
{% if scope.lineItem is defined %}
    {% return compare(operator, lineItem.referenceId, productIds) %}
{% endif %}

{% if scope.cart is not defined %}
    {% return false %}
{% endif %}

{% for lineItem in scope.cart.lineItems.getFlat() %}
    {% if compare(operator, lineItem.referenceId, productIds) %}
        {% return true %}
    {% endif %}
{% endfor %}

{% return false %}
```

In this example we first check if the current scope is `LineItemScope` and refers to a specific line item. If so, we compare that specific line item. Otherwise we check if the scope has a cart and return false if it doesn't. We have a multi select for product selection in the Administration which provides an array of product IDs in the script. We iterate the current cart's line items to check if the product is included and return `true` if that is the case.

### Date condition example

```html
// manifest.xml
<!-- ... -->
<rule-condition>
    <identifier>date_condition</identifier>
    <name>Custom date condition</name>
    <group>misc</group>
    <script>date-condition.twig</script>
</rule-condition>
<!-- ... -->
```

```twig
// Resources/scripts/rule-conditions/date-condition.twig
{% return compare('=', scope.getCurrentTime()|date_modify('first day of this month')|date_modify('second wednesday of this month')|date('Y-m-d'), scope.getCurrentTime()|date('Y-m-d')) %}
```

For this example, we don't have to define constraints. We retrieve the current date from the scope, calling `getCurrentTime`. We modify the date to set it to the first day of the month, then modify it again to set it to the second wednesday from that point in time. We then compare that date against the current date for a condition that matches only on the second wednesday of each month.

---

---
url: /docs/v6.6/guides/plugins/apps/rule-builder/add-custom-rule-conditions.md
---

# Add custom rule conditions

## Overview

In this guide, you'll learn how to make your app introduce custom conditions for use in the [Rule Builder](../../../../concepts/framework/rules). Custom conditions can be defined with fields to be rendered in the Administration and with their own logic, using the same approach as [App Scripts](../app-scripts/).

::: info
Note that app rule conditions were introduced in Shopware 6.4.12.0, and are not supported in previous versions.
:::

## Prerequisites

If you're not familiar with the app system, please take a look at the concept first.

You should also be familiar with the general concept of the Rule Builder.

For the attached logic of your custom conditions, you'll use [twig files](https://twig.symfony.com/). Please refer to the App Scripts guide for a general introduction.

## Definition

App Rule Conditions are defined in the `manifest.xml` file of your app:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        <!-- ... -->
    </meta>
    <rule-conditions>
        <rule-condition>
            <!-- The identifier of the rule condition must be unique should not change. Otherwise a separate rule condition is created and uses of the old one are lost. -->
            <identifier>my_custom_condition</identifier>
            <!-- Translatable, a name of your rule condition -->
            <name>Custom condition</name>
            <name lang="de-DE">Eigene Bedingung</name>
            <!-- A thematic group the condition should be assigned too, available groups are: general, customer, cart, item, promotion, misc -->
            <group>misc</group>
            <!-- The *.twig file that contains the corresponding script for the condition. It must be placed in the directory Resources/scripts/rule-conditions starting from your app's root directory -->
            <script>custom-condition.twig</script>
            <!-- Define the fields you want the user to fill out for use as data within your condition -->
            <constraints>
                <!-- the element type, defines the type of the field -->
                <!-- the elements available here are the same as for custom fields -->
                <single-select name="operator">
                    <placeholder>Choose an operator...</placeholder>
                    <placeholder lang="de-DE">Bitte Operatoren wählen</placeholder>
                    <options>
                        <option value="=">
                            <name>Is equal to</name>
                            <name lang="de-DE">Ist gleich</name>
                        </option>
                        <option value="!=">
                            <name>Is not equal to</name>
                            <name lang="de-DE">Ist nicht gleich</name>
                        </option>
                    </options>
                    <required>true</required>
                </single-select>
                <text name="firstName">
                    <placeholder>Enter first name</placeholder>
                    <placeholder lang="de-DE">Bitte Vornamen eingeben</placeholder>
                    <required>true</required>
                </text>
            </constraints>
        </rule-condition>
    </rule-conditions>
</manifest>

```

For a complete reference of the structure of the manifest file, take a look at the [Manifest reference](../../../../resources/references/app-reference/manifest-reference).

The following fields are required:

* `identifier`: A technical name for the condition that should be unique within the scope of the app. The name is being used to identify existing conditions when updating the app, so it should not be changed.
* `name`: A descriptive and translatable name for the condition. The name will be shown within the Rule Builder's selection of conditions in the Administration.
* `script`: The file name and extension of the file that contains the script for the condition. All scripts for rule conditions must be placed inside `Resources/scripts/rule-conditions` within the root directory of the app.

### Constraints

Constraints are optional and may be used to define fields, whose purpose is to provide data for use within the condition's script.

Constraints are a collection of [custom fields](../custom-data/), which allows you to provide a variety of different fields for setting parameters within the administration. Fields may be marked as `required`. The `name` attribute of the field is also the variable the field's value will be exposed as within the condition's script. So it is advisable to use a variable-friendly name and to use unique names within the confines of a single condition.

The above example will add the condition shown below for selection in the Administration:

![App Rule Condition](../../../../assets/app-rule-condition.png)

## Scripts

The corresponding scripts to the defined conditions within `manifest.xml` need to be placed at a specific directory of your app:

```text
└── DemoApp
    ├── Resources
    │   └── scripts                         // all scripts are stored in this folder
    │       ├── rule-conditions             // reserved for scripts of rule conditions
    │       │   └── custom-condition.twig   // the file name may be freely chosen but must be identical to the corresponding `script` element within `rule-conditions` of `manifest.xml`
    │       └── ...
    └── manifest.xml
```

Scripts for rule conditions are [twig files](https://twig.symfony.com/) that are executed in a sandboxed environment. They offer the same extended syntax and debugging options as [App Scripts](../app-scripts/).

Within the script you will have access to the `scope` variable which is an instance of `RuleScope` as described in the [Rule Builder concept](../../../../concepts/framework/rules). The scope instance provides you with the current `SalesChannelContext` and, given the right scope, the current cart. Further available variables depend on the existence of constraints within the definition of your conditions.

A script *must* return a boolean value, stating whether the condition is true or false. Anything but a boolean returned as value may lead to unexpected behavior.

### Compare helper

To keep condition scripts smaller we provide a `compare` helper function which can be used for the most common comparisons of two values.

The function takes three arguments:

```text
compare(operator, value, comparable)
```

The `operator` *must* be one of the following string values: `=`, `!=`, `>`, `>=`, `<`, `<=`, `empty`

If either one or both of `value` and `comparable` are an array, then only `=` and `!=` should be used as operator. It will then compare whether there is at least one occurrence of the value within the other array and return `true` if that is the case. As an example `value` might be an ID, `comparable` an array of IDs and you could use the function to match whether the ID is included in that array.

### Example

```twig
// Resources/scripts/rule-conditions/custom-condition.twig
{% if scope.salesChannelContext.customer is not defined %}
    {% return false %}
{% endif %}

{% return compare(operator, scope.salesChannelContext.customer.firstName, firstName) %}
```

In the example above, we first check whether we can retrieve the current customer from the instance of `RuleScope` and return `false` otherwise.

We then use the variables `operator` and `firstName`, provided by the constraints of the condition, to evaluate whether the first name in question matches the first name of the current customer. To do so, we make use of the `compare` helper function.

### Line item condition example

```html
// manifest.xml
<!-- ... -->
<rule-condition>
    <identifier>line_item_condition</identifier>
    <name>Custom product multi select</name>
    <group>item</group>
    <script>line-item-condition.twig</script>
    <constraints>
        <single-select name="operator">
            <placeholder>Choose an operator...</placeholder>
            <options>
                <option value="=">
                    <name>Is equal to</name>
                </option>
                <option value="!=">
                    <name>Is not equal to</name>
                </option>
            </options>
            <required>true</required>
        </single-select>
        <multi-entity-select name="productIds">
            <placeholder>Choose products...</placeholder>
            <entity>product</entity>
            <required>true</required>
        </multi-entity-select>
    </constraints>
</rule-condition>
<!-- ... -->
```

```twig
// Resources/scripts/rule-conditions/line-item-condition.twig
{% if scope.lineItem is defined %}
    {% return compare(operator, lineItem.referenceId, productIds) %}
{% endif %}

{% if scope.cart is not defined %}
    {% return false %}
{% endif %}

{% for lineItem in scope.cart.lineItems.getFlat() %}
    {% if compare(operator, lineItem.referenceId, productIds) %}
        {% return true %}
    {% endif %}
{% endfor %}

{% return false %}
```

In this example we first check if the current scope is `LineItemScope` and refers to a specific line item. If so, we compare that specific line item. Otherwise we check if the scope has a cart and return false if it doesn't. We have a multi select for product selection in the Administration which provides an array of product IDs in the script. We iterate the current cart's line items to check if the product is included and return `true` if that is the case.

### Date condition example

```html
// manifest.xml
<!-- ... -->
<rule-condition>
    <identifier>date_condition</identifier>
    <name>Custom date condition</name>
    <group>misc</group>
    <script>date-condition.twig</script>
</rule-condition>
<!-- ... -->
```

```twig
// Resources/scripts/rule-conditions/date-condition.twig
{% return compare('=', scope.getCurrentTime()|date_modify('first day of this month')|date_modify('second wednesday of this month')|date('Y-m-d'), scope.getCurrentTime()|date('Y-m-d')) %}
```

For this example, we don't have to define constraints. We retrieve the current date from the scope, calling `getCurrentTime`. We modify the date to set it to the first day of the month, then modify it again to set it to the second wednesday from that point in time. We then compare that date against the current date for a condition that matches only on the second wednesday of each month.

---

---
url: /docs/guides/plugins/apps/rule-builder/add-custom-rule-conditions.md
---

# Add Custom Rule Conditions

## Overview

This guide explains how to make your app introduce custom conditions for use in the [Rule Builder](../../../../concepts/framework/rule-system/index.md). Custom conditions can be defined with fields to be rendered in the Administration and with their own logic, using the same approach as [App Scripts](../app-scripts/index.md).

::: info
Note that app rule conditions were introduced in Shopware 6.4.12.0, and are not supported in previous versions.
:::

## Prerequisites

If you're not familiar with the app system, please take a look at the concept first.

You should also be familiar with the general concept of the Rule Builder.

For the attached logic of your custom conditions, you'll use [Twig files](https://twig.symfony.com/). Please refer to the App Scripts guide for a general introduction.

## Definition

App Rule Conditions are defined in the `manifest.xml` file of your app:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        <!-- ... -->
    </meta>
    <rule-conditions>
        <rule-condition>
            <!-- The identifier of the rule condition must be unique should not change. Otherwise a separate rule condition is created and uses of the old one are lost. -->
            <identifier>my_custom_condition</identifier>
            <!-- Translatable, a name of your rule condition -->
            <name>Custom condition</name>
            <name lang="de-DE">Eigene Bedingung</name>
            <!-- A thematic group the condition should be assigned too, available groups are: general, customer, cart, item, promotion, misc -->
            <group>misc</group>
            <!-- The *.twig file that contains the corresponding script for the condition. It must be placed in the directory Resources/scripts/rule-conditions starting from your app's root directory -->
            <script>custom-condition.twig</script>
            <!-- Define the fields you want the user to fill out for use as data within your condition -->
            <constraints>
                <!-- the element type, defines the type of the field -->
                <!-- the elements available here are the same as for custom fields -->
                <single-select name="operator">
                    <placeholder>Choose an operator...</placeholder>
                    <placeholder lang="de-DE">Bitte Operatoren wählen</placeholder>
                    <options>
                        <option value="=">
                            <name>Is equal to</name>
                            <name lang="de-DE">Ist gleich</name>
                        </option>
                        <option value="!=">
                            <name>Is not equal to</name>
                            <name lang="de-DE">Ist nicht gleich</name>
                        </option>
                    </options>
                    <required>true</required>
                </single-select>
                <text name="firstName">
                    <placeholder>Enter first name</placeholder>
                    <placeholder lang="de-DE">Bitte Vornamen eingeben</placeholder>
                    <required>true</required>
                </text>
            </constraints>
        </rule-condition>
    </rule-conditions>
</manifest>

```

For a complete reference of the structure of the manifest file, take a look at the [Manifest reference](../../../../resources/references/app-reference/manifest-reference.md).

The following fields are required:

* `identifier`: A technical name for the condition that should be unique within the scope of the app. The name is being used to identify existing conditions when updating the app, so it should not be changed.
* `name`: A descriptive and translatable name for the condition. The name will be shown within the Rule Builder's selection of conditions in the Administration.
* `script`: The file name and extension of the file that contains the script for the condition. All scripts for rule conditions must be placed inside `Resources/scripts/rule-conditions` within the root directory of the app.

### Constraints

Constraints are optional and may be used to define fields, whose purpose is to provide data for use within the condition's script.

Constraints are a collection of [custom fields](../custom-data/custom-fields.md), which allows you to provide a variety of different fields for setting parameters within the administration. Fields may be marked as `required`. The `name` attribute of the field is also the variable the field's value will be exposed as within the condition's script. So it is advisable to use a variable-friendly name and to use unique names within the confines of a single condition.

The above example will add the condition shown below for selection in the Administration:

![App Rule Condition](../../../../assets/app-rule-condition.png)

## Scripts

The corresponding scripts to the defined conditions within `manifest.xml` need to be placed at a specific directory of your app:

```text
└── DemoApp
    ├── Resources
    │   └── scripts                         // all scripts are stored in this folder
    │       ├── rule-conditions             // reserved for scripts of rule conditions
    │       │   └── custom-condition.twig   // the file name may be freely chosen but must be identical to the corresponding `script` element within `rule-conditions` of `manifest.xml`
    │       └── ...
    └── manifest.xml
```

Scripts for rule conditions are [Twig files](https://twig.symfony.com/) that are executed in a sandboxed environment. They offer the same extended syntax and debugging options as [App Scripts](../app-scripts/index.md).

Within the script you will have access to the `scope` variable which is an instance of `RuleScope` as described in the [Rule Builder concept](../../../../concepts/framework/rule-system/index.md). The scope instance provides you with the current `SalesChannelContext` and, given the right scope, the current cart. Further available variables depend on the existence of constraints within the definition of your conditions.

A script *must* return a boolean value, stating whether the condition is true or false. Anything but a boolean returned as value may lead to unexpected behavior.

### Compare helper

To keep condition scripts smaller we provide a `compare` helper function which can be used for the most common comparisons of two values.

The function takes three arguments:

```text
compare(operator, value, comparable)
```

The `operator` *must* be one of the following string values: `=`, `!=`, `>`, `>=`, `<`, `<=`, `empty`

If either one or both of `value` and `comparable` are an array, then only `=` and `!=` should be used as operator. It will then compare whether there is at least one occurrence of the value within the other array and return `true` if that is the case. As an example `value` might be an ID, `comparable` an array of IDs and you could use the function to match whether the ID is included in that array.

### Example

```twig
// Resources/scripts/rule-conditions/custom-condition.twig
{% if scope.salesChannelContext.customer is not defined %}
    {% return false %}
{% endif %}

{% return compare(operator, scope.salesChannelContext.customer.firstName, firstName) %}
```

In the example above, we first check whether we can retrieve the current customer from the instance of `RuleScope` and return `false` otherwise.

We then use the variables `operator` and `firstName`, provided by the constraints of the condition, to evaluate whether the first name in question matches the first name of the current customer. To do so, we make use of the `compare` helper function.

### Line item condition example

```html
// manifest.xml
<!-- ... -->
<rule-condition>
    <identifier>line_item_condition</identifier>
    <name>Custom product multi select</name>
    <group>item</group>
    <script>line-item-condition.twig</script>
    <constraints>
        <single-select name="operator">
            <placeholder>Choose an operator...</placeholder>
            <options>
                <option value="=">
                    <name>Is equal to</name>
                </option>
                <option value="!=">
                    <name>Is not equal to</name>
                </option>
            </options>
            <required>true</required>
        </single-select>
        <multi-entity-select name="productIds">
            <placeholder>Choose products...</placeholder>
            <entity>product</entity>
            <required>true</required>
        </multi-entity-select>
    </constraints>
</rule-condition>
<!-- ... -->
```

```twig
// Resources/scripts/rule-conditions/line-item-condition.twig
{% if scope.lineItem is defined %}
    {% return compare(operator, lineItem.referenceId, productIds) %}
{% endif %}

{% if scope.cart is not defined %}
    {% return false %}
{% endif %}

{% for lineItem in scope.cart.lineItems.getFlat() %}
    {% if compare(operator, lineItem.referenceId, productIds) %}
        {% return true %}
    {% endif %}
{% endfor %}

{% return false %}
```

In this example we first check if the current scope is `LineItemScope` and refers to a specific line item. If so, we compare that specific line item. Otherwise we check if the scope has a cart and return false if it doesn't. We have a multi select for product selection in the Administration which provides an array of product IDs in the script. We iterate the current cart's line items to check if the product is included and return `true` if that is the case.

### Date condition example

```html
// manifest.xml
<!-- ... -->
<rule-condition>
    <identifier>date_condition</identifier>
    <name>Custom date condition</name>
    <group>misc</group>
    <script>date-condition.twig</script>
</rule-condition>
<!-- ... -->
```

```twig
// Resources/scripts/rule-conditions/date-condition.twig
{% return compare('=', scope.getCurrentTime()|date_modify('first day of this month')|date_modify('second wednesday of this month')|date('Y-m-d'), scope.getCurrentTime()|date('Y-m-d')) %}
```

For this example, we don't have to define constraints. We retrieve the current date from the scope, calling `getCurrentTime`. We modify the date to set it to the first day of the month, then modify it again to set it to the second wednesday from that point in time. We then compare that date against the current date for a condition that matches only on the second wednesday of each month.

---

---
url: /docs/guides/plugins/plugins/framework/rule/add-custom-rules.md
---

# Add Custom Rules

## Overview

The Rule Builder allows users to add custom rules to create dynamic conditions and actions. Using the Rule Builder, you can define specific criteria based on various attributes, such as customer data, cart contents, order details, or other relevant factors. These custom rules can then trigger specific actions, such as applying discounts, displaying personalized content, or adjusting pricing based on specific conditions.

This example will introduce a new rule, which checks if it is the first monday of the month or not. The shop owner is then able to react on this specific day every month with special prices or dispatch methods.

## Prerequisites

In order to add your own custom rules for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../../plugin-base-guide.md).

You also should be familiar with the [Dependency Injection container](../../services/dependency-injection.md) as this is used to register your custom rule.

It might be helpful to gather some general understanding about the concept of [Rules](../../../../../concepts/framework/rule-system/index.md) as well.

## Create custom rule

To create a custom rule, we have to implement both backend (PHP) code and a user interface in the Administration to manage it. Let's start with the PHP part first, which basically handles the main logic of our rule. After that, there will be an example to actually show your new rule in the Administration.

### Creating rule in PHP

First of all, we need a new Rule class. In this example, we name it as `FirstMondayOfTheMonthRule`. It will be placed in the directory `<plugin root>/src/Core/Rule`. Our new class has to extend from the abstract class `Shopware\Core\Framework\Rule\Rule`. Below you can find an example implementation.

```php
// <plugin root>/src/Core/Rule/FirstMondayOfTheMonthRule.php
<?php declare(strict_types=1);

namespace SwagCustomRules\Core\Rule;

use Shopware\Core\Framework\Rule\Rule;
use Shopware\Core\Framework\Rule\RuleScope;
use Symfony\Component\Validator\Constraints\Type;

class FirstMondayOfTheMonthRule extends Rule
{
    protected bool $isFirstMondayOfTheMonth;

    public function __construct()
    {
        parent::__construct();

        // Will be overwritten at runtime. Reflects the expected value.
        $this->isFirstMondayOfTheMonth = false;
    }

    public function getName(): string
    {
        return 'first_monday';
    }

    public function match(RuleScope $scope): bool
    {
        $isFirstMondayOfTheMonth = $this->isCurrentlyFirstMondayOfTheMonth(date("Y-m-d") );

        // Checks if the shop owner set the rule to "First monday => Yes"
        if ($this->isFirstMondayOfTheMonth) {
            // Shop administrator wants the rule to match if there's currently the first monday of the month.
            return $isFirstMondayOfTheMonth;
        }

        // Shop administrator wants the rule to match if there's currently NOT the first monday of the month.
        return !$isFirstMondayOfTheMonth;
    }

    public function getConstraints(): array
    {
        return [
            'isFirstMondayOfTheMonth' => [new Type('bool')]
        ];
    }

    private function isCurrentlyFirstMondayOfTheMonth($dateString)
    {
        $date = new \DateTime($dateString);
        $dayOfWeek = (int) $date->format('w');

        // Check if it's Monday (1 is Monday)
        if ($dayOfWeek !== 1) {
            return false;
        }

        // Check if the date is within the first seven days of the month
        $dayOfMonth = (int) $date->format('j');
        if ($dayOfMonth > 7) {
            return false;
        }

        // If it passed both checks, it's the first Thursday of the month
        return true;
    }
}
```

As you can see, several methods are already implemented:

* `__constructor`: This only defines the default expected value. This is overwritten at runtime with the actual value, that the shop owner set in the Administration.
* `getName`: Returns a unique technical name for your rule.
* `match`: This checks whether the rule applies. Accordingly, a boolean is returned whether the rule applies or not.
* `getConstraints`: This method returns an array of the possible fields and its types. You could also return the `NotBlank` class here, to require this field.

After we've created our rule class, we have to register it in our `services.php` and tag it as `shopware.rule.definition`.
Please keep in mind: The variables to be used in the rule have to be 'protected' and not 'private', otherwise they won't work properly.

::: warning
Never execute database queries or any other time-consuming operations within the `match()` method of your rule, as it will drastically impact the performance of your store. Stick to the rule scope when evaluating whether your rule matches or not.
:::

```php
// Scope usage: Check if the customer is logged in
$customer = $scope->getSalesChannelContext()->getCustomer();
$loggedIn = $customer !== null;
```

It is possible to add config to our rule. This makes it possible to skip the [Custom rule component](#custom-rule-component) and the [Custom rule Administration template](#custom-rule-administration-template) parts.

```php
    public function getConfig(): RuleConfig
    {
        return (new RuleConfig())->booleanField('isFirstMondayOfTheMonth');
    }
```

when [Showing rule in the Administration](#showing-rule-in-the-administration) we would not use a custom component but we would render the `sw-condition-generic` component.

### Active rules

You can access all active rules by using the `getRuleIds` method of the context.

```php
$context->getRuleIds();
```

### Showing rule in the Administration

Now we want to implement our new rule in the Administration so that we can manage it. To achieve this, we have to call the `addCondition` method of the [RuleConditionService](https://github.com/shopware/shopware/blob/v6.6.0.0/src/Administration/Resources/app/administration/src/app/service/rule-condition.service.ts), by decorating this service. The decoration of services in the Administration will be covered in our [Adding services](../../administration/services-utilities/add-custom-service.md#decorating-a-service) guide.

Create a new directory called `<plugin root>/src/Resources/app/administration/src/decorator`. In this directory we create a new file called `rule-condition-service-decoration.js`.

```javascript
// <plugin root>src/Resources/app/administration/src/decorator/rule-condition-service-decoration.js
import '../../core/component/swag-first-monday';

Shopware.Application.addServiceProviderDecorator('ruleConditionDataProviderService', (ruleConditionService) => {
    ruleConditionService.addCondition('first_monday', {
        component: 'swag-first-monday',
        label: 'Is first monday of the month',
        scopes: ['global']
    });

    return ruleConditionService;
});
```

As you can see, this is decorating the `RuleConditionService` by using its name `ruleConditionDataProviderService`. The decoration adds a new condition called `first_monday`. Make sure to match the name we have used in the `getName` method in PHP. Next, we define the component, in our case, `swag-first-monday`, which is responsible for rendering the rule inside the Administration. We will create this component in the next step. Furthermore, we defined a label, which will be displayed in the rule builder selection. The last option is the scope, which in our case is `global`, as we have not specified a specific one in our core class.

We also have to create a `main.js` file in our Administration sources directory and import the decorator file we've created above. The `main.js` file is used as an entry point to load Administration modules from Shopware plugins:

```javascript
// <plugin root>/src/Resources/app/administration/src/main.js
import './decorator/rule-condition-service-decoration';
```

::: info
It may be possible that rules, with your newly created condition, aren't selectable in some places inside the Administration — for example, inside the promotion module. That is because rules are "context-aware". To learn more about that feature [click here](#context-awareness)
:::

#### Creating a new group in the administration

The rule will now be added to the list of rules in the admin. It might be useful to create a new group for your rules. We can create a new group by using the `upsertGroup` method of the [RuleConditionService](https://github.com/shopware/shopware/blob/v6.6.0.0/src/Administration/Resources/app/administration/src/app/service/rule-condition.service.ts).

```javascript
  // <plugin root>src/Resources/app/administration/src/decorator/rule-condition-service-decoration.js
  Shopware.Application.addServiceProviderDecorator('ruleConditionDataProviderService', (ruleConditionService) => {
      ruleConditionService.upsertGroup('days_of_the_month', {
        id: 'days_of_the_month',
        name: 'Days of the month',
      });

      return ruleConditionService;
  });
```

Now that we have our group, we have to link this group to our condition. This is easily done by adding the `group` property to our condition.

```javascript
// <plugin root>src/Resources/app/administration/src/decorator/rule-condition-service-decoration.js
import '../../core/component/swag-first-monday';

Shopware.Application.addServiceProviderDecorator('ruleConditionDataProviderService', (ruleConditionService) => {
    ruleConditionService.addCondition('first_monday', {
        component: 'swag-first-monday',
        label: 'Is first monday of the month',
        scopes: ['global'],
        group: 'days_of_the_month', // [!code focus]
    });

    return ruleConditionService;
});
```

### Custom rule component

Now that you have registered your rule to the Administration, you would still be lacking the actual component `swag-first-monday`. As you have already defined a path for it in your service decoration, create the following directory: `<plugin root>/src/Resources/app/administration/src/core/component/swag-first-monday`. If you are unfamiliar with creating components in Shopware, refer to the [add your own component](../../administration/module-component-management/add-custom-component.md) section.

Here's an example of what this component could look like:

```javascript
// <plugin root>/src/Resources/app/administration/src/core/component/swag-first-monday/index.js
import template from './swag-first-monday.html.twig';

Shopware.Component.extend('swag-first-monday', 'sw-condition-base', {
    template,

    computed: {
        selectValues() {
            return [
                {
                    label: this.$tc('global.sw-condition.condition.yes'),
                    value: true
                },
                {
                    label: this.$tc('global.sw-condition.condition.no'),
                    value: false
                }
            ];
        },

        isFirstMondayOfTheMonth: {
            get() {
                this.ensureValueExist();

                if (this.condition.value.isFirstMondayOfTheMonth == null) {
                    this.condition.value.isFirstMondayOfTheMonth = false;
                }

                return this.condition.value.isFirstMondayOfTheMonth;
            },
            set(isFirstMondayOfTheMonth) {
                this.ensureValueExist();
                this.condition.value = { ...this.condition.value, isFirstMondayOfTheMonth };
            }
        }
    }
});
```

As you can see, our `swag-first-monday` has to extend from the `sw-condition-base` component and has to bring a custom template, which will be explained in the next step. Let's have a look at each property and method. The first computed property is `selectValues`, which returns an array containing the values "true" and "false". Those will be used in the template later on, as they will be the selectable options for the shop administrator. Do not get confused by the call `this.$tc\('global.sw-condition.condition.yes'\)`; it's just loading a translation by its name, in this case, "Yes" and "No".

::: info
When dealing with boolean values, make sure to always return strings here.
:::

The second and last computed property is `isFirstMondayOfTheMonth`, which uses a getter and setter to define the value of the condition.

### Custom rule Administration template

The last step is, creating a template for our condition. We will create a new file called `swag-first-monday.html.twig` in the same directory as the component. In our template, we have to overwrite the block `sw_condition_value_content`. In this example we define a `sw-single-select` in this block.

```twig
// <plugin root>/src/Resources/app/administration/src/core/component/swag-first-monday/swag-first-monday.html.twig
{% block sw_condition_value_content %}
    <sw-single-select name="first-monday"
                      id="first-monday"
                      size="medium"
                      :options="selectValues"
                      v-model="isFirstMondayOfTheMonth"
                      class="field--main">
    </sw-single-select>
{% endblock %}
```

As you can see, our `sw-single-select` uses the previously created computed property `selectValues` as the `options` prop, and the value is saved into the variable `isFirstMondayOfTheMonth`. That's it; your rule is now fully integrated.

## Context awareness

::: info
This feature is available in version 6.5.0.0 or above.
:::

Rules in the Shopware Administration are aware of where users assign them. That means that a user can't add a rule to a promotion when the rule contains the condition "Cart amount". That also works the other way around. If the rule is assigned to a promotion, the user can't use the "Cart amount" condition.

![Select component with disabled rules](../../../../../assets/rule-restrictions-rule-builder.png)

It is possible to define where rules can be assigned inside the Administration.

### Defining restrictions

You have previously added the condition inside `ruleConditionDataProviderService`. This is the place where you define restrictions for the rule. The goal of this example is to restrict the user from adding a rule to advanced prices if the rules contain a specific condition.

First, get the existing definition for the rule relation as below:

```javascript
// <plugin root>src/Resources/app/administration/src/decorator/rule-condition-service-decoration.js
// Inside the addServiceProviderDecorator method
const restrictions = ruleConditionService.getAwarenessConfigurationByAssignmentName('productPrices');
```

::: info
You can find all possible relations in `Shopware\Core\Content\Rule\RuleDefinition`;
:::

Now, add your `awarenessConfiguration` and call the `addAwarenessConfiguration` method.

```javascript
type awarenessConfiguration = {
notEquals?: Array<string>,
equalsAny?: Array<string>,
snippet?: string,
}
```

```javascript
// <plugin root>src/Resources/app/administration/src/decorator/rule-condition-service-decoration.js
Shopware.Application.addServiceProviderDecorator('ruleConditionDataProviderService', (ruleConditionService) => {
    // Your newly added conditions is here

    const restrictions = ruleConditionService.getAwarenessConfigurationByAssignmentName('productPrices');

    ruleConditionService
        .addAwarenessConfiguration('productPrices', {
            notEquals: [
                'first_monday'
            ],
            equalsAny: [ ], // ignore if not needed
            snippet: 'sw-restricted-rules.restrictedAssignment.productPrices',
        });
});
```

What do `notEquals` and `equalsAny` actually mean?
With these two properties, you can define the rules you want to assign to a specific relation, i.e., `productPrices` need to have at least one condition inside `equalsAny` or should not have any condition inside of `notEquals`.

Finally, you just need a snippet, and you can choose an existing one or create one yourself. With that said, you successfully defined restrictions for your custom condition. If you now try to assign a rule with your condition to advanced prices, you should see that it is not possible, and the rule is disabled.

### Restricting rule assignments

When you add a new rule-select component to assign rules somewhere in Shopware, you should use the `sw-select-rule-create` component. With that, you can ensure that the rules you don't want to be selectable aren't selectable.
For that, we need to write some twig code. The important property here is the `rule-aware-group-key` property which should match the assignment name of the rule-aware group we just extended.

::: info
Refer to [customize Administration components](../../administration/module-component-management/customizing-components.md) to know more about it.
:::

```twig
{% block example_twig_blog %}
    <sw-select-rule-create
        rule-aware-group-key="productPrices"
        @save-rule="[YOUR SAVE METHOD]">
{% endblock %}
```

That's it! The component automatically fetches rules and marks them as disabled.

## Multi select and other components

The above guide explains the integration of a boolean and no values. If you want to go more in-depth, for example, search your entity, you can extend and use the different components that Shopware comes with. The multi select example can be found in `shopware/administration/Resources/app/administration/src/app/component/form/select/entity/sw-entity-multi-select`.

## Further reading

For more other information you can refer to [Add rule assignment configuration](../../administration/advanced-configuration/add-rule-assignment-configuration.md) section of the guide.

---

---
url: /docs/v6.5/guides/plugins/plugins/framework/rule/add-custom-rules.md
---

# Add Custom Rules

## Overview

In this guide you will learn how to create rules in Shopware. Rules are used by the rule builder.

This example will introduce a new rule, which checks if it is the first monday of the month or not. The shop owner is then able to react on this specific day every month with special prices or dispatch methods.

## Prerequisites

In order to add your own custom rules for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../../plugin-base-guide).

You also should be familiar with the [Dependency Injection container](../../plugin-fundamentals/dependency-injection) as this is used to register your custom rule.

It might be helpful to gather some general understanding about the concept of [Rules](../../../../../concepts/framework/rules) as well.

## Create custom rule

To create a custom rule, we have to implement both backend (PHP) code and a user interface in the Administration to manage it. Let's start with the PHP part first, which basically handles the main logic of our rule. After that, there will be an example to actually show your new rule in the Administration.

### Creating rule in PHP

First of all, we need a new Rule class. In this example, we name it as `FirstMondayOfTheMonthRule`. It will be placed in the directory `<plugin root>/src/Core/Rule`. Our new class has to extend from the abstract class `Shopware\Core\Framework\Rule\Rule`. Below you can find an example implementation.

```php
// <plugin root>/src/Core/Rule/FirstMondayOfTheMonthRule.php
<?php declare(strict_types=1);

namespace SwagCustomRules\Core\Rule;

use Shopware\Core\Framework\Rule\Rule;
use Shopware\Core\Framework\Rule\RuleScope;
use Symfony\Component\Validator\Constraints\Type;

class FirstMondayOfTheMonthRule extends Rule
{
    protected bool $isFirstMondayOfTheMonth;

    public function __construct()
    {
        parent::__construct();

        // Will be overwritten at runtime. Reflects the expected value.
        $this->isFirstMondayOfTheMonth = false;
    }

    public function getName(): string
    {
        return 'first_monday';
    }

    public function match(RuleScope $scope): bool
    {
        $isFirstMondayOfTheMonth = $this->isCurrentlyFirstMondayOfTheMonth(date("Y-m-d") );

        // Checks if the shop owner set the rule to "First monday => Yes"
        if ($this->isFirstMondayOfTheMonth) {
            // Shop administrator wants the rule to match if there's currently the first monday of the month.
            return $isFirstMondayOfTheMonth;
        }

        // Shop administrator wants the rule to match if there's currently NOT the first monday of the month.
        return !$isFirstMondayOfTheMonth;
    }

    public function getConstraints(): array
    {
        return [
            'isFirstMondayOfTheMonth' => [new Type('bool')]
        ];
    }

    private function isCurrentlyFirstMondayOfTheMonth($dateString)
    {
        $date = new \DateTime($dateString);
        $dayOfWeek = (int) $date->format('w');
        
        // Check if it's Monday (1 is Monday)
        if ($dayOfWeek !== 1) {
            return false;
        }

        // Check if the date is within the first seven days of the month
        $dayOfMonth = (int) $date->format('j');
        if ($dayOfMonth > 7) {
            return false;
        }

        // If it passed both checks, it's the first Thursday of the month
        return true;
    }
}
```

As you can see, several methods are already implemented:

* `__constructor`: This only defines the default expected value. This is overwritten at runtime with the actual value, that the shop owner set in the Administration.
* `getName`: Returns a unique technical name for your rule.
* `match`: This checks whether the rule applies. Accordingly, a boolean is returned whether the rule applies or not.
* `getConstraints`: This method returns an array of the possible fields and its types. You could also return the `NotBlank` class here, to require this field.

After we've created our rule class, we have to register it in our `services.xml` and tag it as `shopware.rule.definition`.
Please keep in mind: The variables to be used in the rule have to be 'protected' and not 'private', otherwise they won't work properly.

::: warning
Never execute database queries or any other time-consuming operations within the `match()` method of your rule, as it will drastically impact the performance of your store. Stick to the rule scope when evaluating whether your rule matches or not.
:::

```php
// Scope usage: Check if the customer is logged in 
$customer = $scope->getSalesChannelContext()->getCustomer();
$loggedIn = $customer !== null;
```

### Active rules

You can access all active rules by using the `getRuleIds` method of the context.

```php
$context->getRuleIds();
```

### Showing rule in the Administration

Now we want to implement our new rule in the Administration so that we can manage it. To achieve this, we have to call the `addCondition` method of the [RuleConditionService](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Administration/Resources/app/administration/src/app/service/rule-condition.service.js), by decorating this service. The decoration of services in the Administration will be covered in our [Adding services](../../administration/add-custom-service#Decorating%20a%20service) guide.

Create a new directory called `<plugin root>/src/Resources/app/administration/src/decorator`. In this directory we create a new file called `rule-condition-service-decoration.js`.

```javascript
// <plugin root>src/Resources/app/administration/src/decorator/rule-condition-service-decoration.js
import '../../core/component/swag-first-monday';

Shopware.Application.addServiceProviderDecorator('ruleConditionDataProviderService', (ruleConditionService) => {
    ruleConditionService.addCondition('first_monday', {
        component: 'swag-first-monday',
        label: 'Is first monday of the month',
        scopes: ['global']
    });

    return ruleConditionService;
});
```

As you can see, this is decorating the `RuleConditionService` by using its name `ruleConditionDataProviderService`. The decoration adds a new condition called `first_monday`. Make sure to match the name we have used in the `getName` method in PHP. Next, we define the component, in our case, `swag-first-monday`, which is responsible for rendering the rule inside the Administration. We will create this component in the next step. Furthermore, we defined a label, which will be displayed in the rule builder selection. The last option is the scope, which in our case is `global`, as we have not specified a specific one in our core class.

We also have to create a `main.js` file in our Administration sources directory and import the decorator file we've created above. The `main.js` file is used as an entry point to load Administration modules from Shopware plugins:

```javascript
// <plugin root>/src/Resources/app/administration/src/main.js
import './decorator/rule-condition-service-decoration';
```

::: info
It may be possible that rules, with your newly created condition, aren't selectable in some places inside the Administration — for example, inside the promotion module. That is because rules are "context-aware". To learn more about that feature [click here](#context-awareness)
:::

### Custom rule component

Now that you have registered your rule to the Administration, you would still be lacking the actual component `swag-first-monday`. As you have already defined a path for it in your service decoration, create the following directory: `<plugin root>/src/Resources/app/administration/src/core/component/swag-first-monday`. If you are unfamiliar with creating components in Shopware, refer to the [add your own component](../../administration/add-custom-component) section.

Here's an example of what this component could look like:

```javascript
// <plugin root>/src/Resources/app/administration/src/core/component/swag-first-monday/index.js
import template from './swag-first-monday.html.twig';

Shopware.Component.extend('swag-first-monday', 'sw-condition-base', {
    template,

    computed: {
        selectValues() {
            return [
                {
                    label: this.$tc('global.sw-condition.condition.yes'),
                    value: true
                },
                {
                    label: this.$tc('global.sw-condition.condition.no'),
                    value: false
                }
            ];
        },

        isFirstMondayOfTheMonth: {
            get() {
                this.ensureValueExist();

                if (this.condition.value.isFirstMondayOfTheMonth == null) {
                    this.condition.value.isFirstMondayOfTheMonth = false;
                }

                return this.condition.value.isFirstMondayOfTheMonth;
            },
            set(isFirstMondayOfTheMonth) {
                this.ensureValueExist();
                this.condition.value = { ...this.condition.value, isFirstMondayOfTheMonth };
            }
        }
    }
});
```

As you can see, our `swag-first-monday` has to extend from the `sw-condition-base` component and has to bring a custom template, which will be explained in the next step. Let's have a look at each property and method. The first computed property is `selectValues`, which returns an array containing the values "true" and "false". Those will be used in the template later on, as they will be the selectable options for the shop administrator. Do not get confused by the call `this.$tc\('global.sw-condition.condition.yes'\)`; it's just loading a translation by its name, in this case, "Yes" and "No".

::: info
When dealing with boolean values, make sure to always return strings here.
:::

The second and last computed property is `isFirstMondayOfTheMonth`, which uses a getter and setter to define the value of the condition.

### Custom rule Administration template

The last step is, creating a template for our condition. We will create a new file called `swag-first-monday.html.twig` in the same directory as the component. In our template, we have to overwrite the block `sw_condition_value_content`. In this example we define a `sw-single-select` in this block.

```twig
// <plugin root>/src/Resources/app/administration/src/core/component/swag-first-monday/swag-first-monday.html.twig
{% block sw_condition_value_content %}
    <sw-single-select name="first-monday"
                      id="first-monday"
                      size="medium"
                      :options="selectValues"
                      v-model="isFirstMondayOfTheMonth"
                      class="field--main">
    </sw-single-select>
{% endblock %}
```

As you can see, our `sw-single-select` uses the previously created computed property `selectValues` as the `options` prop, and the value is saved into the variable `isFirstMondayOfTheMonth`. That's it; your rule is now fully integrated.

## Context awareness

::: info
This feature is available in version 6.5.0.0 or above.
:::

Rules in the Shopware Administration are aware of where users assign them. That means that a user can't add a rule to a promotion when the rule contains the condition "Cart amount". That also works the other way around. If the rule is assigned to a promotion, the user can't use the "Cart amount" condition.

![Select component with disabled rules](../../../../../assets/rule-restrictions-rule-builder.png)

It is possible to define where rules can be assigned inside the Administration.

### Defining restrictions

You have previously added the condition inside `ruleConditionDataProviderService`. This is the place where you define restrictions for the rule. The goal of this example is to restrict the user from adding a rule to advanced prices if the rules contain a specific condition.

First, get the existing definition for the rule relation as below:

```javascript
// <plugin root>src/Resources/app/administration/src/decorator/rule-condition-service-decoration.js
// Inside the addServiceProviderDecorator method
const restrictions = ruleConditionService.getAwarenessConfigurationByAssignmentName('productPrices');
```

::: info
You can find all possible relations in `Shopware\Core\Content\Rule\RuleDefinition`;
:::

Now, add your `awarenessConfiguration` and call the `addAwarenessConfiguration` method.

```javascript
type awarenessConfiguration = {
notEquals?: Array<string>,
equalsAny?: Array<string>,
snippet?: string,
}
```

```javascript
// <plugin root>src/Resources/app/administration/src/decorator/rule-condition-service-decoration.js
Shopware.Application.addServiceProviderDecorator('ruleConditionDataProviderService', (ruleConditionService) => {
    // Your newly added conditions is here

    const restrictions = ruleConditionService.getAwarenessConfigurationByAssignmentName('productPrices');

    ruleConditionService
        .addAwarenessConfiguration('productPrices', {
            notEquals: [
                'first_monday'
            ],
            equalsAny: [ ], // ignore if not needed
            snippet: 'sw-restricted-rules.restrictedAssignment.productPrices',
        });
});
```

What do `notEquals` and `equalsAny` actually mean?
With these two properties, you can define the rules you want to assign to a specific relation, i.e., `productPrices` need to have at least one condition inside `equalsAny` or should not have any condition inside of `notEquals`.

Finally, you just need a snippet, and you can choose an existing one or create one yourself. With that said, you successfully defined restrictions for your custom condition. If you now try to assign a rule with your condition to advanced prices, you should see that it is not possible, and the rule is disabled.

### Restricting rule assignments

When you add a new rule-select component to assign rules somewhere in Shopware, you should use the `sw-select-rule-create` component. With that, you can ensure that the rules you don't want to be selectable aren't selectable.
For that, we need to write some twig code. The important property here is the `rule-aware-group-key` property which should match the assignment name of the rule-aware group we just extended.

::: info
Refer to [customize administration components](../../administration/customizing-components) to know more about it.
:::

```twig
{% block example_twig_blog %}
    <sw-select-rule-create
        rule-aware-group-key="productPrices"
        @save-rule="[YOUR SAVE METHOD]">
{% endblock %}
```

That's it! The component automatically fetches rules and marks them as disabled.

## Multi select and other components

The above guide explains the integration of a boolean and no values. If you want to go more in-depth, for example, search your entity, you can extend and use the different components that Shopware comes with. The multi select example can be found in `shopware/administration/Resources/app/administration/src/app/component/form/select/entity/sw-entity-multi-select`.

## Further reading

For more other information you can refer to [Add rule assignment configuration](../../administration/add-rule-assignment-configuration) section of the guide.

---

---
url: /docs/v6.6/guides/plugins/plugins/framework/rule/add-custom-rules.md
---

# Add Custom Rules

## Overview

In this guide you will learn how to create rules in Shopware. Rules are used by the rule builder.

This example will introduce a new rule, which checks if it is the first monday of the month or not. The shop owner is then able to react on this specific day every month with special prices or dispatch methods.

## Prerequisites

In order to add your own custom rules for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../../plugin-base-guide).

You also should be familiar with the [Dependency Injection container](../../plugin-fundamentals/dependency-injection) as this is used to register your custom rule.

It might be helpful to gather some general understanding about the concept of [Rules](../../../../../concepts/framework/rules) as well.

## Create custom rule

To create a custom rule, we have to implement both backend (PHP) code and a user interface in the Administration to manage it. Let's start with the PHP part first, which basically handles the main logic of our rule. After that, there will be an example to actually show your new rule in the Administration.

### Creating rule in PHP

First of all, we need a new Rule class. In this example, we name it as `FirstMondayOfTheMonthRule`. It will be placed in the directory `<plugin root>/src/Core/Rule`. Our new class has to extend from the abstract class `Shopware\Core\Framework\Rule\Rule`. Below you can find an example implementation.

```php
// <plugin root>/src/Core/Rule/FirstMondayOfTheMonthRule.php
<?php declare(strict_types=1);

namespace SwagCustomRules\Core\Rule;

use Shopware\Core\Framework\Rule\Rule;
use Shopware\Core\Framework\Rule\RuleScope;
use Symfony\Component\Validator\Constraints\Type;

class FirstMondayOfTheMonthRule extends Rule
{
    protected bool $isFirstMondayOfTheMonth;

    public function __construct()
    {
        parent::__construct();

        // Will be overwritten at runtime. Reflects the expected value.
        $this->isFirstMondayOfTheMonth = false;
    }

    public function getName(): string
    {
        return 'first_monday';
    }

    public function match(RuleScope $scope): bool
    {
        $isFirstMondayOfTheMonth = $this->isCurrentlyFirstMondayOfTheMonth(date("Y-m-d") );

        // Checks if the shop owner set the rule to "First monday => Yes"
        if ($this->isFirstMondayOfTheMonth) {
            // Shop administrator wants the rule to match if there's currently the first monday of the month.
            return $isFirstMondayOfTheMonth;
        }

        // Shop administrator wants the rule to match if there's currently NOT the first monday of the month.
        return !$isFirstMondayOfTheMonth;
    }

    public function getConstraints(): array
    {
        return [
            'isFirstMondayOfTheMonth' => [new Type('bool')]
        ];
    }

    private function isCurrentlyFirstMondayOfTheMonth($dateString)
    {
        $date = new \DateTime($dateString);
        $dayOfWeek = (int) $date->format('w');
        
        // Check if it's Monday (1 is Monday)
        if ($dayOfWeek !== 1) {
            return false;
        }

        // Check if the date is within the first seven days of the month
        $dayOfMonth = (int) $date->format('j');
        if ($dayOfMonth > 7) {
            return false;
        }

        // If it passed both checks, it's the first Thursday of the month
        return true;
    }
}
```

As you can see, several methods are already implemented:

* `__constructor`: This only defines the default expected value. This is overwritten at runtime with the actual value, that the shop owner set in the Administration.
* `getName`: Returns a unique technical name for your rule.
* `match`: This checks whether the rule applies. Accordingly, a boolean is returned whether the rule applies or not.
* `getConstraints`: This method returns an array of the possible fields and its types. You could also return the `NotBlank` class here, to require this field.

After we've created our rule class, we have to register it in our `services.xml` and tag it as `shopware.rule.definition`.
Please keep in mind: The variables to be used in the rule have to be 'protected' and not 'private', otherwise they won't work properly.

::: warning
Never execute database queries or any other time-consuming operations within the `match()` method of your rule, as it will drastically impact the performance of your store. Stick to the rule scope when evaluating whether your rule matches or not.
:::

```php
// Scope usage: Check if the customer is logged in 
$customer = $scope->getSalesChannelContext()->getCustomer();
$loggedIn = $customer !== null;
```

It is possible to add config to our rule. This makes it possible to skip the [Custom rule component](#custom-rule-component) and the [Custom rule Administration template](#custom-rule-administration-template) parts.

```php
    public function getConfig(): RuleConfig
    {
        return (new RuleConfig())->booleanField('isFirstMondayOfTheMonth');
    }
```

when [Showing rule in the Administration](#showing-rule-in-the-administration) we would not use a custom component but we would render the `sw-condition-generic` component.

### Active rules

You can access all active rules by using the `getRuleIds` method of the context.

```php
$context->getRuleIds();
```

### Showing rule in the Administration

Now we want to implement our new rule in the Administration so that we can manage it. To achieve this, we have to call the `addCondition` method of the [RuleConditionService](https://github.com/shopware/shopware/blob/v6.6.0.0/src/Administration/Resources/app/administration/src/app/service/rule-condition.service.ts), by decorating this service. The decoration of services in the Administration will be covered in our [Adding services](../../administration/add-custom-service#Decorating%20a%20service) guide.

Create a new directory called `<plugin root>/src/Resources/app/administration/src/decorator`. In this directory we create a new file called `rule-condition-service-decoration.js`.

```javascript
// <plugin root>src/Resources/app/administration/src/decorator/rule-condition-service-decoration.js
import '../../core/component/swag-first-monday';

Shopware.Application.addServiceProviderDecorator('ruleConditionDataProviderService', (ruleConditionService) => {
    ruleConditionService.addCondition('first_monday', {
        component: 'swag-first-monday',
        label: 'Is first monday of the month',
        scopes: ['global']
    });

    return ruleConditionService;
});
```

As you can see, this is decorating the `RuleConditionService` by using its name `ruleConditionDataProviderService`. The decoration adds a new condition called `first_monday`. Make sure to match the name we have used in the `getName` method in PHP. Next, we define the component, in our case, `swag-first-monday`, which is responsible for rendering the rule inside the Administration. We will create this component in the next step. Furthermore, we defined a label, which will be displayed in the rule builder selection. The last option is the scope, which in our case is `global`, as we have not specified a specific one in our core class.

We also have to create a `main.js` file in our Administration sources directory and import the decorator file we've created above. The `main.js` file is used as an entry point to load Administration modules from Shopware plugins:

```javascript
// <plugin root>/src/Resources/app/administration/src/main.js
import './decorator/rule-condition-service-decoration';
```

::: info
It may be possible that rules, with your newly created condition, aren't selectable in some places inside the Administration — for example, inside the promotion module. That is because rules are "context-aware". To learn more about that feature [click here](#context-awareness)
:::

#### Creating a new group in the administration

The rule will now be added to the list of rules in the admin. It might be useful to create a new group for your rules. We can create a new group by using the `upsertGroup` method of the [RuleConditionService](https://github.com/shopware/shopware/blob/v6.6.0.0/src/Administration/Resources/app/administration/src/app/service/rule-condition.service.ts).

```javascript
  // <plugin root>src/Resources/app/administration/src/decorator/rule-condition-service-decoration.js
  Shopware.Application.addServiceProviderDecorator('ruleConditionDataProviderService', (ruleConditionService) => {
      ruleConditionService.upsertGroup('days_of_the_month', {
        id: 'days_of_the_month',
        name: 'Days of the month',
      });
  
      return ruleConditionService;
  });
```

Now that we have our group, we have to link this group to our condition. This is easily done by adding the `group` property to our condition.

```javascript
// <plugin root>src/Resources/app/administration/src/decorator/rule-condition-service-decoration.js
import '../../core/component/swag-first-monday';

Shopware.Application.addServiceProviderDecorator('ruleConditionDataProviderService', (ruleConditionService) => {
    ruleConditionService.addCondition('first_monday', {
        component: 'swag-first-monday',
        label: 'Is first monday of the month',
        scopes: ['global'],
        group: 'days_of_the_month', // [!code focus]
    });

    return ruleConditionService;
});
```

### Custom rule component

Now that you have registered your rule to the Administration, you would still be lacking the actual component `swag-first-monday`. As you have already defined a path for it in your service decoration, create the following directory: `<plugin root>/src/Resources/app/administration/src/core/component/swag-first-monday`. If you are unfamiliar with creating components in Shopware, refer to the [add your own component](../../administration/add-custom-component) section.

Here's an example of what this component could look like:

```javascript
// <plugin root>/src/Resources/app/administration/src/core/component/swag-first-monday/index.js
import template from './swag-first-monday.html.twig';

Shopware.Component.extend('swag-first-monday', 'sw-condition-base', {
    template,

    computed: {
        selectValues() {
            return [
                {
                    label: this.$tc('global.sw-condition.condition.yes'),
                    value: true
                },
                {
                    label: this.$tc('global.sw-condition.condition.no'),
                    value: false
                }
            ];
        },

        isFirstMondayOfTheMonth: {
            get() {
                this.ensureValueExist();

                if (this.condition.value.isFirstMondayOfTheMonth == null) {
                    this.condition.value.isFirstMondayOfTheMonth = false;
                }

                return this.condition.value.isFirstMondayOfTheMonth;
            },
            set(isFirstMondayOfTheMonth) {
                this.ensureValueExist();
                this.condition.value = { ...this.condition.value, isFirstMondayOfTheMonth };
            }
        }
    }
});
```

As you can see, our `swag-first-monday` has to extend from the `sw-condition-base` component and has to bring a custom template, which will be explained in the next step. Let's have a look at each property and method. The first computed property is `selectValues`, which returns an array containing the values "true" and "false". Those will be used in the template later on, as they will be the selectable options for the shop administrator. Do not get confused by the call `this.$tc\('global.sw-condition.condition.yes'\)`; it's just loading a translation by its name, in this case, "Yes" and "No".

::: info
When dealing with boolean values, make sure to always return strings here.
:::

The second and last computed property is `isFirstMondayOfTheMonth`, which uses a getter and setter to define the value of the condition.

### Custom rule Administration template

The last step is, creating a template for our condition. We will create a new file called `swag-first-monday.html.twig` in the same directory as the component. In our template, we have to overwrite the block `sw_condition_value_content`. In this example we define a `sw-single-select` in this block.

```twig
// <plugin root>/src/Resources/app/administration/src/core/component/swag-first-monday/swag-first-monday.html.twig
{% block sw_condition_value_content %}
    <sw-single-select name="first-monday"
                      id="first-monday"
                      size="medium"
                      :options="selectValues"
                      v-model="isFirstMondayOfTheMonth"
                      class="field--main">
    </sw-single-select>
{% endblock %}
```

As you can see, our `sw-single-select` uses the previously created computed property `selectValues` as the `options` prop, and the value is saved into the variable `isFirstMondayOfTheMonth`. That's it; your rule is now fully integrated.

## Context awareness

::: info
This feature is available in version 6.5.0.0 or above.
:::

Rules in the Shopware Administration are aware of where users assign them. That means that a user can't add a rule to a promotion when the rule contains the condition "Cart amount". That also works the other way around. If the rule is assigned to a promotion, the user can't use the "Cart amount" condition.

![Select component with disabled rules](../../../../../assets/rule-restrictions-rule-builder.png)

It is possible to define where rules can be assigned inside the Administration.

### Defining restrictions

You have previously added the condition inside `ruleConditionDataProviderService`. This is the place where you define restrictions for the rule. The goal of this example is to restrict the user from adding a rule to advanced prices if the rules contain a specific condition.

First, get the existing definition for the rule relation as below:

```javascript
// <plugin root>src/Resources/app/administration/src/decorator/rule-condition-service-decoration.js
// Inside the addServiceProviderDecorator method
const restrictions = ruleConditionService.getAwarenessConfigurationByAssignmentName('productPrices');
```

::: info
You can find all possible relations in `Shopware\Core\Content\Rule\RuleDefinition`;
:::

Now, add your `awarenessConfiguration` and call the `addAwarenessConfiguration` method.

```javascript
type awarenessConfiguration = {
notEquals?: Array<string>,
equalsAny?: Array<string>,
snippet?: string,
}
```

```javascript
// <plugin root>src/Resources/app/administration/src/decorator/rule-condition-service-decoration.js
Shopware.Application.addServiceProviderDecorator('ruleConditionDataProviderService', (ruleConditionService) => {
    // Your newly added conditions is here

    const restrictions = ruleConditionService.getAwarenessConfigurationByAssignmentName('productPrices');

    ruleConditionService
        .addAwarenessConfiguration('productPrices', {
            notEquals: [
                'first_monday'
            ],
            equalsAny: [ ], // ignore if not needed
            snippet: 'sw-restricted-rules.restrictedAssignment.productPrices',
        });
});
```

What do `notEquals` and `equalsAny` actually mean?
With these two properties, you can define the rules you want to assign to a specific relation, i.e., `productPrices` need to have at least one condition inside `equalsAny` or should not have any condition inside of `notEquals`.

Finally, you just need a snippet, and you can choose an existing one or create one yourself. With that said, you successfully defined restrictions for your custom condition. If you now try to assign a rule with your condition to advanced prices, you should see that it is not possible, and the rule is disabled.

### Restricting rule assignments

When you add a new rule-select component to assign rules somewhere in Shopware, you should use the `sw-select-rule-create` component. With that, you can ensure that the rules you don't want to be selectable aren't selectable.
For that, we need to write some twig code. The important property here is the `rule-aware-group-key` property which should match the assignment name of the rule-aware group we just extended.

::: info
Refer to [customize administration components](../../administration/customizing-components) to know more about it.
:::

```twig
{% block example_twig_blog %}
    <sw-select-rule-create
        rule-aware-group-key="productPrices"
        @save-rule="[YOUR SAVE METHOD]">
{% endblock %}
```

That's it! The component automatically fetches rules and marks them as disabled.

## Multi select and other components

The above guide explains the integration of a boolean and no values. If you want to go more in-depth, for example, search your entity, you can extend and use the different components that Shopware comes with. The multi select example can be found in `shopware/administration/Resources/app/administration/src/app/component/form/select/entity/sw-entity-multi-select`.

## Further reading

For more other information you can refer to [Add rule assignment configuration](../../administration/add-rule-assignment-configuration) section of the guide.

---

---
url: /docs/v6.5/guides/plugins/plugins/content/seo/add-custom-seo-url.md
---

# Add custom SEO URLs

## Overview

Every good website had to deal with it at some point: SEO URLs. Of course Shopware supports the usage of SEO URLs, e.g. for products or categories.

This guide however will cover the question on how you can define your own SEO URLs, e.g. for your own custom entities. This will include both static SEO URLs, as well as dynamic SEO URLs.

## Prerequisites

As every almost every guide in the plugins section, this guide as well is built upon the plugin base guide.

Furthermore, we're going to use a [Custom storefront controller](../../storefront/add-custom-controller) for the static SEO URL example, as well as [Custom entities](../../framework/data-handling/add-custom-complex-data) for the dynamic SEO URLs. Make sure you know and understand those two as well before diving deeper into this guide. Those come with two different solutions:

* Using [plugin migrations](../../plugin-fundamentals/database-migrations) for static SEO URLs
* Using [DAL events](../../framework/data-handling/using-database-events) to react on entity changes and therefore generating a dynamic SEO URL

## Custom SEO URLs

As already mentioned in the overview, this guide will be divided into two parts: Static and dynamic SEO URLs.

### Static SEO URLs

A static SEO URL doesn't have to change every now and then. Imagine a custom controller, which is accessible via the link `yourShop.com/example`.

Now if you want this URL to be translatable, you'll have to add a custom SEO URL to your controller route, so it is accessible using both `Example-Page` in English, as well as e.g. `Beispiel-Seite` in German.

#### Example controller

For this example, the controller from the [Add custom controller guide](../../storefront/add-custom-controller) is being used. It creates a controller with a route like the example mentioned above: `/example`

Let's now have a look at our example controller:

```php
// <plugin root>/src/Storefront/Controller/ExampleController.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Controller\StorefrontController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

#[Route(defaults: ['_routeScope' => ['storefront']])]
class ExampleController extends StorefrontController
{
    #[Route(path: '/example', name: 'frontend.example.example', methods: ['GET'])]
    public function showExample(): Response
    {
        return $this->renderStorefront('@SwagBasicExample/storefront/page/example/index.html.twig', [
            'example' => 'Hello world'
        ]);
    }
}
```

The important information you'll need here is the route name, `frontend.example.example`, as well as the route itself: `/example`. Make sure to remember those for the next step.

#### Example migration

Creating a SEO URL in this scenario can be achieved by creating a [plugin migration](../../plugin-fundamentals/database-migrations).

The migration has to insert an entry for each sales channel and language into the `seo_url` table. For this case, we're making use of the `ImportTranslationsTrait`, which comes with a helper method `importTranslation`.

Don't be confused here, we'll just treat the `seo_url` table like a translation table, since it also needs a `language_id` and respective translated SEO URLs. You'll have to pass a German and an English array into an instance of the `Translations` class, which is then the second parameter for the `importTranslation` method.

Let's have a look at an example:

```php
// <plugin root>/src/Migration/Migration1619094740AddStaticSeoUrl.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Framework\Uuid\Uuid;
use Shopware\Core\Migration\Traits\ImportTranslationsTrait;
use Shopware\Core\Migration\Traits\Translations;

class Migration1619094740AddStaticSeoUrl extends MigrationStep
{
    use ImportTranslationsTrait;

    public function getCreationTimestamp(): int
    {
        return 1619094740;
    }

    public function update(Connection $connection): void
    {
        $this->importTranslation('seo_url', new Translations(
            // German array
            array_merge($this->getSeoMetaArray($connection), ['seo_path_info' => 'Beispiel-Seite']),
            // English array
            array_merge($this->getSeoMetaArray($connection), ['seo_path_info' => 'Example-Page']),

        ), $connection);
    }

    public function updateDestructive(Connection $connection): void
    {
    }

    private function getSeoMetaArray(Connection $connection): array
    {
        return [
            'id' => Uuid::randomBytes(),
            'sales_channel_id' => $this->getStorefrontSalesChannelId($connection),
            'foreign_key' => Uuid::randomBytes(),
            'route_name' => 'frontend.example.example',
            'path_info' => '/example',
            'is_canonical' => 1,
            'is_modified' => 0,
            'is_deleted' => 0,
        ];
    }

    private function getStorefrontSalesChannelId(Connection $connection): ?string
    {
        $sql = <<<SQL
            SELECT id
            FROM sales_channel
            WHERE type_id = :typeId
SQL;
        $salesChannelId = $connection->fetchOne($sql, [
            ':typeId' => Uuid::fromHexToBytes(Defaults::SALES_CHANNEL_TYPE_STOREFRONT)
        ]);

        if (!$salesChannelId) {
            return null;
        }

        return $salesChannelId;
    }
}
```

You might want to have a look at the `getSeoMetaArray` method, that we implemented here. Most important for you are the columns `route_name` and `path_info` here, which represent the values you've defined in your controller's route annotation.

By using the default PHP method `array_merge`, we're then also adding our translated SEO URL to the column `seo_path_info`.

And that's it! After installing our plugin, you should now be able to access your controller's route with the given SEO URLs.

::: info
You can only access the German SEO URL if you've configured a German domain in your respective sales channel first.
:::

### Dynamic SEO URLs

Dynamic SEO URLs are URLs, that have to change every now and then. Yet, there's another separation necessary.

If you're going to generate custom SEO URLs for your custom entities, you'll have to follow the section about [Dynamic SEO URLs for entities](add-custom-seo-url#dynamic-seo-urls-for-entities). For all other kinds of dynamic content, that are not DAL entities, the section about [Dynamic SEO URLs for other content](add-custom-seo-url#dynamic-seo-urls-for-custom-content) is your way to go.

#### Dynamic SEO URLs for entities

This scenario will be about a custom entity, to be specific we're going to use the entity from our guide about [adding custom complex data](../../framework/data-handling/add-custom-complex-data), which then would have a custom Storefront route for each entity.

Each entity comes with a name, which eventually should be the SEO URL. Thus, your entity named `Foo` should be accessible using the route `yourShop.com/Foo` or `yourShop.com/Entities/Foo` or whatever you'd like. Now, everytime you create a new entity, a SEO URL has to be automatically created as well. When you update your entities' name, guess what, you'll have to change the SEO URL as well.

For this scenario, you can make use of the Shopware built-in `SeoUrlRoute` classes, which hold all necessary information about your dynamic route and will then create the respective `seo_url` entries automatically.

Let's first have a look at such an example class:

```php
// <plugin root>/src/Storefront/Framework/Seo/SeoUrlRoute/ExamplePageSeoUrlRoute.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Framework\Seo\SeoUrlRoute;

use Shopware\Core\Content\Seo\SeoUrlRoute\SeoUrlMapping;
use Shopware\Core\Content\Seo\SeoUrlRoute\SeoUrlRouteConfig;
use Shopware\Core\Content\Seo\SeoUrlRoute\SeoUrlRouteInterface;
use Shopware\Core\Framework\DataAbstractionLayer\Entity;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\System\SalesChannel\SalesChannelEntity;
use Swag\BasicExample\Core\Content\Example\ExampleDefinition;
use Swag\BasicExample\Core\Content\Example\ExampleEntity;

class ExamplePageSeoUrlRoute implements SeoUrlRouteInterface
{
    public const ROUTE_NAME = 'frontend.example.example';
    public const DEFAULT_TEMPLATE = '{{ example.name }}';

    private ExampleDefinition $exampleDefinition;

    public function __construct(ExampleDefinition $exampleDefinition)
    {
        $this->exampleDefinition = $exampleDefinition;
    }

    public function getConfig(): SeoUrlRouteConfig
    {
        return new SeoUrlRouteConfig(
            $this->exampleDefinition,
            self::ROUTE_NAME,
            self::DEFAULT_TEMPLATE,
            true
        );
    }

    public function prepareCriteria(Criteria $criteria): void
    {
    }

    public function getMapping(Entity $example, ?SalesChannelEntity $salesChannel): SeoUrlMapping
    {
        if (!$example instanceof ExampleEntity) {
            throw new \InvalidArgumentException('Expected ExampleEntity');
        }

        $exampleJson = $example->jsonSerialize();

        return new SeoUrlMapping(
            $example,
            ['exampleId' => $example->getId()],
            [
                'example' => $exampleJson,
            ]
        );
    }
}
```

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Storefront\Framework\Seo\SeoUrlRoute\ExamplePageSeoUrlRoute">
            <argument type="service" id="Swag\BasicExample\Core\Content\Example\ExampleDefinition"/>

            <tag name="shopware.seo_url.route"/>
        </service>
    </services>
</container>
```

Okay, so let's look through this step by step.

Your custom "SeoUrlRoute" class has to implement the `SeoUrlRouteInterface`, which comes with three necessary methods:

* `getConfig`: Here you have to return an instance of `SeoUrlRouteConfig`, containing your entity's definition,

  the technical name of the route to be used, and the desired SEO path.

* `prepareCriteria`: Here you can adjust the criteria instance, which will be used to fetch your entities.

  Here you can e.g. narrow down which entities may be used for the SEO URL generation. For example you could add a filter

  on an `active` field and therefore only generate SEO URLs for active entities. Also you can add associations here,

  which will then be available with the entity provided in the `getMapping` method.

* `getMapping`: In this method you have to return an instance of `SeoUrlMapping`. It has to contain the actually

  available data for the SEO URL template. If you're using a variable `example.name` in the SEO URL template, you have to

  provide the data for the key `example` here.

Make sure to check which kind of entity has been applied to the `getMapping` method, since you don't want to provide mappings for other entities than your custom one.

It then has to be registered to the container using the tag `shopware.seo_url.route`.

Now that you've set up this class, there are two more things to be done, which are covered in the next sections.

**Example subscriber**

Every time your entity is written now, you have to let Shopware know, that you want to generate the SEO URLs for those entities now. This is done by reacting to the [DAL events](../../framework/data-handling/using-database-events) of your custom entity, to be specific we're going to use the `written` event. Everytime your entity is written, you then have to execute the `update` method of the `Shopware\Core\Content\Seo\SeoUrlUpdater` class.

Once again, let's have a look at an example subscriber here:

```php
// <plugin root>/src/Service/DynamicSeoUrlPageSubscriber.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Content\Seo\SeoUrlUpdater;
use Shopware\Core\Framework\DataAbstractionLayer\Event\EntityWrittenEvent;
use Swag\BasicExample\Storefront\Framework\Seo\SeoUrlRoute\ExamplePageSeoUrlRoute;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class DynamicSeoUrlPageSubscriber implements EventSubscriberInterface
{
    private SeoUrlUpdater $seoUrlUpdater;

    public function __construct(SeoUrlUpdater $seoUrlUpdater) {
        $this->seoUrlUpdater = $seoUrlUpdater;
    }

    public static function getSubscribedEvents(): array
    {
        return [
            'swag_example.written' => 'onEntityWritten'
        ];
    }

    public function onEntityWritten(EntityWrittenEvent $event): void
    {
        $this->seoUrlUpdater->update(ExamplePageSeoUrlRoute::ROUTE_NAME, $event->getIds());
    }
}
```

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <!-- ... -->
        <service id="Swag\BasicExample\Service\DynamicSeoUrlPageSubscriber" >
            <argument type="service" id="Shopware\Core\Content\Seo\SeoUrlUpdater" />

            <tag name="kernel.event_subscriber" />
        </service>
    </services>
</container>
```

As already said, we're using the `written` event of our custom entity by providing the entities' technical name with the `.written` suffix. Everytime it is executed, we're just using the said `update` method of the `SeoUrlUpdater`. Here you'll have to provide the technical route name and the IDs of the entities, that need to be updated. And that's it for the subscriber.

The `SeoUrlUpdater` will need one more thing in order to work properly: An entry in the table `seo_url_template`, which is done in the next step.

**Example SeoUrlTemplate migration**

Now we need to add an entry to the `seo_url_template` table for our new dynamic SEO URL template. This is done by adding a [database migration](../../plugin-fundamentals/database-migrations) to our plugin.

The most important values you'll have to set in the migration are:

* `route_name`: We've defined this multiple times already. Use the constant from your `ExamplePageSeoUrlRoute` class
* `entity_name`: The technical name of your custom entity. In this guide it's `swag_example`
* `template`: Once again use the constant `DEFAULT_TEMPLATE` from your `ExamplePageSeoUrlRoute` class

Now here is the said example migration:

```php
// <plugin root>/src/Migration/Migration1619514731AddExampleSeoUrlTemplate.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Framework\Uuid\Uuid;
use Swag\BasicExample\Storefront\Framework\Seo\SeoUrlRoute\ExamplePageSeoUrlRoute;

class Migration1619514731AddExampleSeoUrlTemplate extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1619514731;
    }

    public function update(Connection $connection): void
    {
        $connection->insert('seo_url_template', [
            'id' => Uuid::randomBytes(),
            'sales_channel_id' => null,
            'route_name' => ExamplePageSeoUrlRoute::ROUTE_NAME,
            'entity_name' => 'swag_example',
            'template' => ExamplePageSeoUrlRoute::DEFAULT_TEMPLATE,
            'created_at' => (new \DateTimeImmutable())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
        ]);
    }

    public function updateDestructive(Connection $connection): void
    {
    }
}
```

And that's it! Every time your entity is written now, you'll automatically generate a SEO URL for it.

::: info
This guide will not cover creating an actual controller with the used example route. Learn how that is done in our guide about [creating a storefront controller](../../storefront/add-custom-controller).
:::

**Reacting to entity deletion**

If your entity is deleted, you want the SEO URL to be updated as well. In detail, the column `is_deleted` of the respective entry in the `seo_url` table has to be set to `1`.

This can be achieved by using the DAL event `.deleted` and then executing the `update` method again.

```php
// <plugin root>/src/Service/DynamicSeoUrlPageSubscriber.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Content\Seo\SeoUrlUpdater;
use Shopware\Core\Framework\DataAbstractionLayer\Event\EntityDeletedEvent;
use Shopware\Core\Framework\DataAbstractionLayer\Event\EntityWrittenEvent;
use Swag\BasicExample\Storefront\Framework\Seo\SeoUrlRoute\ExamplePageSeoUrlRoute;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class DynamicSeoUrlPageSubscriber implements EventSubscriberInterface
{
    // ...

    public static function getSubscribedEvents(): array
    {
        return [
            'swag_example.written' => 'onEntityWritten',
            'swag_example.deleted' => 'onEntityDeleted'
        ];
    }

    // ...

    public function onEntityDeleted(EntityDeletedEvent $event): void
    {
        $this->seoUrlUpdater->update(ExamplePageSeoUrlRoute::ROUTE_NAME, $event->getIds());
    }
}
```

#### Dynamic SEO URLs for custom content

This section is specifically about dynamic content other than custom entities. This could be e.g. data from an external resource, maybe external APIs.

You'll need some kind of event or some other way to execute code once your dynamic content changes, like once a new instance of that content is created or once it is updated.

In this example, we'll assume you've got a class called `DynamicSeoUrlsService` with a method `writeSeoEntries`. This method will get an array of entries to be written, including their respective payload, such as a name for the SEO URL. It also needs the current context.

Calling this method is up to you, depending on your set up and the type of "dynamic content" you're having.

This method will then use the `SeoUrlPersister` and its method `updateSeoUrls` in order to write entries to the `seo_url` table.

Here's an example of such a class:

```php
// <plugin root>/src/Service/DynamicSeoUrlsService.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Cocur\Slugify\SlugifyInterface;
use Shopware\Core\Content\Seo\SeoUrlPersister;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Filter\EqualsFilter;

class DynamicSeoUrlsService
{
    public const ROUTE_NAME = 'example.route.name';

    private SeoUrlPersister $seoUrlPersister;

    private EntityRepository $salesChannelRepository;

    private SlugifyInterface $slugify;

    public function __construct(
        SeoUrlPersister $seoUrlPersister,
        EntityRepository $salesChannelRepository,
        SlugifyInterface $slugify
    ) {
        $this->seoUrlPersister = $seoUrlPersister;
        $this->salesChannelRepository = $salesChannelRepository;
        $this->slugify = $slugify;
    }

    public function writeSeoEntries(array $entries, Context $context): void
    {
        $urls = [];

        $salesChannelId = $this->getStorefrontSalesChannelId($context);
        if (!$salesChannelId) {
            // Might want to throw an error here
            return;
        }

        foreach ($entries as $entry) {
            $urls[] = [
                'salesChannelId' => $salesChannelId,
                'foreignKey' => $entry->getId(),
                // The name of the route in the respective controller
                'routeName' => self::ROUTE_NAME,
                // The technical path of your custom route, using a given parameter
                'pathInfo' => '/example-path/' . $entry->getId(),
                'isCanonical' => true,
                // The SEO URL that you want to use here, in this case just the name
                'seoPathInfo' => '/' . $this->slugify->slugify($entry->getName()),
            ];
        }

        // You might have to create a new context using another specific language ID
        $this->seoUrlPersister->updateSeoUrls($context, self::ROUTE_NAME, array_column($urls, 'foreignKey') , $urls);
    }

    private function getStorefrontSalesChannelId(Context $context): ?string
    {
        $criteria = new Criteria();
        $criteria->addFilter(new EqualsFilter('typeId', Defaults::SALES_CHANNEL_TYPE_STOREFRONT));

        return $this->salesChannelRepository->searchIds($criteria, $context)->firstId();
    }
}
```

The method `writeSeoEntries` will look for a Storefront sales channel and return its ID. It's then iterating over each provided entry, which in this example will need a method called `getId` and method called `getName`. Using this data, an array of URLs to be written is created. Make sure to change the values of the following keys:

* `routeName`: The technical name of your route, configured in your controller
* `pathInfo`: The technical, non-SEO, path of your route, also configured in your controller
* `seoPathInfo`: The actual SEO path you want to use - in this case the name of the said content

::: info
This guide will not cover creating an actual controller with the used example route. Learn how that is done in our guide about [creating a storefront controller](../../storefront/add-custom-controller).
:::

It will then use the built array and all of the other information like the context, the route name and an array of foreign keys for the method `updateSeoUrls` of the `SeoUrlPersister`. And that's it for your dynamic content.

#### Reacting to deletion of the content

If your custom dynamic content is deleted, you have to set the column `is_deleted` to `1` of the respective `seo_url` entry. This can be achieved with a new method, in this example we'll call it `deleteSeoEntries`. It will receive an array of IDs to be deleted. Those IDs have to match the value of the column `foreign_key` in the `seo_url` table. Also it needs the current context. It will take care of setting the generated SEO URLs to `deleted`. It will **not** delete an entry from the table `seo_url`.

```php
public function deleteSeoEntries(array $ids, Context $context): void
{
    $this->seoUrlPersister->updateSeoUrls($context, self::ROUTE_NAME, $ids, []);
}
```

This way the respective SEO URLs will be marked as `is_deleted` for the system. However, this SEO route will remain accessible, so make sure to implement a check whether or not the content still exists in your controller.

#### Writing SEO URLs for another language

In the example mentioned above, we're just using a `Context` instance, for whichever language that is. You can be more specific here though, in order to properly define the language ID yourself here and therefore ensuring it is written for the right language.

```php
$context = new Context(
    $event->getContext()->getSource(),
    $event->getContext()->getRuleIds(),
    $event->getContext()->getCurrencyId(),
    [$languageId]
);
```

You can then pass this context to the `updateSeoUrls` method.

---

---
url: /docs/v6.6/guides/plugins/plugins/content/seo/add-custom-seo-url.md
---

# Add custom SEO URLs

## Overview

Every good website had to deal with it at some point: SEO URLs. Of course Shopware supports the usage of SEO URLs, e.g. for products or categories.

This guide however will cover the question on how you can define your own SEO URLs, e.g. for your own custom entities. This will include both static SEO URLs, as well as dynamic SEO URLs.

## Prerequisites

As every almost every guide in the plugins section, this guide as well is built upon the plugin base guide.

Furthermore, we're going to use a [Custom storefront controller](../../storefront/add-custom-controller) for the static SEO URL example, as well as [Custom entities](../../framework/data-handling/add-custom-complex-data) for the dynamic SEO URLs. Make sure you know and understand those two as well before diving deeper into this guide. Those come with two different solutions:

* Using [plugin migrations](../../plugin-fundamentals/database-migrations) for static SEO URLs
* Using [DAL events](../../framework/data-handling/using-database-events) to react on entity changes and therefore generating a dynamic SEO URL

## Custom SEO URLs

As already mentioned in the overview, this guide will be divided into two parts: Static and dynamic SEO URLs.

### Static SEO URLs

A static SEO URL doesn't have to change every now and then. Imagine a custom controller, which is accessible via the link `yourShop.com/example`.

Now if you want this URL to be translatable, you'll have to add a custom SEO URL to your controller route, so it is accessible using both `Example-Page` in English, as well as e.g. `Beispiel-Seite` in German.

#### Example controller

For this example, the controller from the [Add custom controller guide](../../storefront/add-custom-controller) is being used. It creates a controller with a route like the example mentioned above: `/example`

Let's now have a look at our example controller:

```php
// <plugin root>/src/Storefront/Controller/ExampleController.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Controller\StorefrontController;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

#[Route(defaults: ['_routeScope' => ['storefront']])]
class ExampleController extends StorefrontController
{
    #[Route(path: '/example', name: 'frontend.example.example', methods: ['GET'])]
    public function showExample(): Response
    {
        return $this->renderStorefront('@SwagBasicExample/storefront/page/example/index.html.twig', [
            'example' => 'Hello world'
        ]);
    }
}
```

The important information you'll need here is the route name, `frontend.example.example`, as well as the route itself: `/example`. Make sure to remember those for the next step.

#### Example migration

Creating a SEO URL in this scenario can be achieved by creating a [plugin migration](../../plugin-fundamentals/database-migrations).

The migration has to insert an entry for each sales channel and language into the `seo_url` table. For this case, we're making use of the `ImportTranslationsTrait`, which comes with a helper method `importTranslation`.

Don't be confused here, we'll just treat the `seo_url` table like a translation table, since it also needs a `language_id` and respective translated SEO URLs. You'll have to pass a German and an English array into an instance of the `Translations` class, which is then the second parameter for the `importTranslation` method.

Let's have a look at an example:

```php
// <plugin root>/src/Migration/Migration1619094740AddStaticSeoUrl.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Framework\Uuid\Uuid;
use Shopware\Core\Migration\Traits\ImportTranslationsTrait;
use Shopware\Core\Migration\Traits\Translations;

class Migration1619094740AddStaticSeoUrl extends MigrationStep
{
    use ImportTranslationsTrait;

    public function getCreationTimestamp(): int
    {
        return 1619094740;
    }

    public function update(Connection $connection): void
    {
        $this->importTranslation('seo_url', new Translations(
            // German array
            array_merge($this->getSeoMetaArray($connection), ['seo_path_info' => 'Beispiel-Seite']),
            // English array
            array_merge($this->getSeoMetaArray($connection), ['seo_path_info' => 'Example-Page']),

        ), $connection);
    }

    public function updateDestructive(Connection $connection): void
    {
    }

    private function getSeoMetaArray(Connection $connection): array
    {
        return [
            'id' => Uuid::randomBytes(),
            'sales_channel_id' => $this->getStorefrontSalesChannelId($connection),
            'foreign_key' => Uuid::randomBytes(),
            'route_name' => 'frontend.example.example',
            'path_info' => '/example',
            'is_canonical' => 1,
            'is_modified' => 0,
            'is_deleted' => 0,
        ];
    }

    private function getStorefrontSalesChannelId(Connection $connection): ?string
    {
        $sql = <<<SQL
            SELECT id
            FROM sales_channel
            WHERE type_id = :typeId
SQL;
        $salesChannelId = $connection->fetchOne($sql, [
            ':typeId' => Uuid::fromHexToBytes(Defaults::SALES_CHANNEL_TYPE_STOREFRONT)
        ]);

        if (!$salesChannelId) {
            return null;
        }

        return $salesChannelId;
    }
}
```

You might want to have a look at the `getSeoMetaArray` method, that we implemented here. Most important for you are the columns `route_name` and `path_info` here, which represent the values you've defined in your controller's route attributes.

By using the default PHP method `array_merge`, we're then also adding our translated SEO URL to the column `seo_path_info`.

And that's it! After installing our plugin, you should now be able to access your controller's route with the given SEO URLs.

::: info
You can only access the German SEO URL if you've configured a German domain in your respective sales channel first.
:::

### Dynamic SEO URLs

Dynamic SEO URLs are URLs, that have to change every now and then. Yet, there's another separation necessary.

If you're going to generate custom SEO URLs for your custom entities, you'll have to follow the section about [Dynamic SEO URLs for entities](add-custom-seo-url#dynamic-seo-urls-for-entities). For all other kinds of dynamic content, that are not DAL entities, the section about [Dynamic SEO URLs for other content](add-custom-seo-url#dynamic-seo-urls-for-custom-content) is your way to go.

#### Dynamic SEO URLs for entities

This scenario will be about a custom entity, to be specific we're going to use the entity from our guide about [adding custom complex data](../../framework/data-handling/add-custom-complex-data), which then would have a custom Storefront route for each entity.

Each entity comes with a name, which eventually should be the SEO URL. Thus, your entity named `Foo` should be accessible using the route `yourShop.com/Foo` or `yourShop.com/Entities/Foo` or whatever you'd like. Now, everytime you create a new entity, a SEO URL has to be automatically created as well. When you update your entities' name, guess what, you'll have to change the SEO URL as well.

For this scenario, you can make use of the Shopware built-in `SeoUrlRoute` classes, which hold all necessary information about your dynamic route and will then create the respective `seo_url` entries automatically.

Let's first have a look at such an example class:

```php
// <plugin root>/src/Storefront/Framework/Seo/SeoUrlRoute/ExamplePageSeoUrlRoute.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Framework\Seo\SeoUrlRoute;

use Shopware\Core\Content\Seo\SeoUrlRoute\SeoUrlMapping;
use Shopware\Core\Content\Seo\SeoUrlRoute\SeoUrlRouteConfig;
use Shopware\Core\Content\Seo\SeoUrlRoute\SeoUrlRouteInterface;
use Shopware\Core\Framework\DataAbstractionLayer\Entity;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\System\SalesChannel\SalesChannelEntity;
use Swag\BasicExample\Core\Content\Example\ExampleDefinition;
use Swag\BasicExample\Core\Content\Example\ExampleEntity;

class ExamplePageSeoUrlRoute implements SeoUrlRouteInterface
{
    public const ROUTE_NAME = 'frontend.example.example';
    public const DEFAULT_TEMPLATE = '{{ example.name }}';

    private ExampleDefinition $exampleDefinition;

    public function __construct(ExampleDefinition $exampleDefinition)
    {
        $this->exampleDefinition = $exampleDefinition;
    }

    public function getConfig(): SeoUrlRouteConfig
    {
        return new SeoUrlRouteConfig(
            $this->exampleDefinition,
            self::ROUTE_NAME,
            self::DEFAULT_TEMPLATE,
            true
        );
    }

    public function prepareCriteria(Criteria $criteria): void
    {
    }

    public function getMapping(Entity $example, ?SalesChannelEntity $salesChannel): SeoUrlMapping
    {
        if (!$example instanceof ExampleEntity) {
            throw new \InvalidArgumentException('Expected ExampleEntity');
        }

        $exampleJson = $example->jsonSerialize();

        return new SeoUrlMapping(
            $example,
            ['exampleId' => $example->getId()],
            [
                'example' => $exampleJson,
            ]
        );
    }
}
```

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Storefront\Framework\Seo\SeoUrlRoute\ExamplePageSeoUrlRoute">
            <argument type="service" id="Swag\BasicExample\Core\Content\Example\ExampleDefinition"/>

            <tag name="shopware.seo_url.route"/>
        </service>
    </services>
</container>
```

Okay, so let's look through this step by step.

Your custom "SeoUrlRoute" class has to implement the `SeoUrlRouteInterface`, which comes with three necessary methods:

* `getConfig`: Here you have to return an instance of `SeoUrlRouteConfig`, containing your entity's definition,

  the technical name of the route to be used, and the desired SEO path.

* `prepareCriteria`: Here you can adjust the criteria instance, which will be used to fetch your entities.

  Here you can e.g. narrow down which entities may be used for the SEO URL generation. For example you could add a filter

  on an `active` field and therefore only generate SEO URLs for active entities. Also you can add associations here,

  which will then be available with the entity provided in the `getMapping` method.

* `getMapping`: In this method you have to return an instance of `SeoUrlMapping`. It has to contain the actually

  available data for the SEO URL template. If you're using a variable `example.name` in the SEO URL template, you have to

  provide the data for the key `example` here.

Make sure to check which kind of entity has been applied to the `getMapping` method, since you don't want to provide mappings for other entities than your custom one.

It then has to be registered to the container using the tag `shopware.seo_url.route`.

Now that you've set up this class, there are two more things to be done, which are covered in the next sections.

**Example subscriber**

Every time your entity is written now, you have to let Shopware know, that you want to generate the SEO URLs for those entities now. This is done by reacting to the [DAL events](../../framework/data-handling/using-database-events) of your custom entity, to be specific we're going to use the `written` event. Everytime your entity is written, you then have to execute the `update` method of the `Shopware\Core\Content\Seo\SeoUrlUpdater` class.

Once again, let's have a look at an example subscriber here:

```php
// <plugin root>/src/Service/DynamicSeoUrlPageSubscriber.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Content\Seo\SeoUrlUpdater;
use Shopware\Core\Framework\DataAbstractionLayer\Event\EntityWrittenEvent;
use Swag\BasicExample\Storefront\Framework\Seo\SeoUrlRoute\ExamplePageSeoUrlRoute;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class DynamicSeoUrlPageSubscriber implements EventSubscriberInterface
{
    private SeoUrlUpdater $seoUrlUpdater;

    public function __construct(SeoUrlUpdater $seoUrlUpdater) {
        $this->seoUrlUpdater = $seoUrlUpdater;
    }

    public static function getSubscribedEvents(): array
    {
        return [
            'swag_example.written' => 'onEntityWritten'
        ];
    }

    public function onEntityWritten(EntityWrittenEvent $event): void
    {
        $this->seoUrlUpdater->update(ExamplePageSeoUrlRoute::ROUTE_NAME, $event->getIds());
    }
}
```

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <!-- ... -->
        <service id="Swag\BasicExample\Service\DynamicSeoUrlPageSubscriber" >
            <argument type="service" id="Shopware\Core\Content\Seo\SeoUrlUpdater" />

            <tag name="kernel.event_subscriber" />
        </service>
    </services>
</container>
```

As already said, we're using the `written` event of our custom entity by providing the entities' technical name with the `.written` suffix. Everytime it is executed, we're just using the said `update` method of the `SeoUrlUpdater`. Here you'll have to provide the technical route name and the IDs of the entities, that need to be updated. And that's it for the subscriber.

The `SeoUrlUpdater` will need one more thing in order to work properly: An entry in the table `seo_url_template`, which is done in the next step.

**Example SeoUrlTemplate migration**

Now we need to add an entry to the `seo_url_template` table for our new dynamic SEO URL template. This is done by adding a [database migration](../../plugin-fundamentals/database-migrations) to our plugin.

The most important values you'll have to set in the migration are:

* `route_name`: We've defined this multiple times already. Use the constant from your `ExamplePageSeoUrlRoute` class
* `entity_name`: The technical name of your custom entity. In this guide it's `swag_example`
* `template`: Once again use the constant `DEFAULT_TEMPLATE` from your `ExamplePageSeoUrlRoute` class

Now here is the said example migration:

```php
// <plugin root>/src/Migration/Migration1619514731AddExampleSeoUrlTemplate.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Framework\Uuid\Uuid;
use Swag\BasicExample\Storefront\Framework\Seo\SeoUrlRoute\ExamplePageSeoUrlRoute;

class Migration1619514731AddExampleSeoUrlTemplate extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1619514731;
    }

    public function update(Connection $connection): void
    {
        $connection->insert('seo_url_template', [
            'id' => Uuid::randomBytes(),
            'sales_channel_id' => null,
            'route_name' => ExamplePageSeoUrlRoute::ROUTE_NAME,
            'entity_name' => 'swag_example',
            'template' => ExamplePageSeoUrlRoute::DEFAULT_TEMPLATE,
            'created_at' => (new \DateTimeImmutable())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
        ]);
    }

    public function updateDestructive(Connection $connection): void
    {
    }
}
```

And that's it! Every time your entity is written now, you'll automatically generate a SEO URL for it.

::: info
This guide will not cover creating an actual controller with the used example route. Learn how that is done in our guide about [creating a storefront controller](../../storefront/add-custom-controller).
:::

**Reacting to entity deletion**

If your entity is deleted, you want the SEO URL to be updated as well. In detail, the column `is_deleted` of the respective entry in the `seo_url` table has to be set to `1`.

This can be achieved by using the DAL event `.deleted` and then executing the `update` method again.

```php
// <plugin root>/src/Service/DynamicSeoUrlPageSubscriber.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Content\Seo\SeoUrlUpdater;
use Shopware\Core\Framework\DataAbstractionLayer\Event\EntityDeletedEvent;
use Shopware\Core\Framework\DataAbstractionLayer\Event\EntityWrittenEvent;
use Swag\BasicExample\Storefront\Framework\Seo\SeoUrlRoute\ExamplePageSeoUrlRoute;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class DynamicSeoUrlPageSubscriber implements EventSubscriberInterface
{
    // ...

    public static function getSubscribedEvents(): array
    {
        return [
            'swag_example.written' => 'onEntityWritten',
            'swag_example.deleted' => 'onEntityDeleted'
        ];
    }

    // ...

    public function onEntityDeleted(EntityDeletedEvent $event): void
    {
        $this->seoUrlUpdater->update(ExamplePageSeoUrlRoute::ROUTE_NAME, $event->getIds());
    }
}
```

#### Dynamic SEO URLs for custom content

This section is specifically about dynamic content other than custom entities. This could be e.g. data from an external resource, maybe external APIs.

You'll need some kind of event or some other way to execute code once your dynamic content changes, like once a new instance of that content is created or once it is updated.

In this example, we'll assume you've got a class called `DynamicSeoUrlsService` with a method `writeSeoEntries`. This method will get an array of entries to be written, including their respective payload, such as a name for the SEO URL. It also needs the current context.

Calling this method is up to you, depending on your set up and the type of "dynamic content" you're having.

This method will then use the `SeoUrlPersister` and its method `updateSeoUrls` in order to write entries to the `seo_url` table.

Here's an example of such a class:

```php
// <plugin root>/src/Service/DynamicSeoUrlsService.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Cocur\Slugify\SlugifyInterface;
use Shopware\Core\Content\Seo\SeoUrlPersister;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Filter\EqualsFilter;

class DynamicSeoUrlsService
{
    public const ROUTE_NAME = 'example.route.name';

    private SeoUrlPersister $seoUrlPersister;

    private EntityRepository $salesChannelRepository;

    private SlugifyInterface $slugify;

    public function __construct(
        SeoUrlPersister $seoUrlPersister,
        EntityRepository $salesChannelRepository,
        SlugifyInterface $slugify
    ) {
        $this->seoUrlPersister = $seoUrlPersister;
        $this->salesChannelRepository = $salesChannelRepository;
        $this->slugify = $slugify;
    }

    public function writeSeoEntries(array $entries, Context $context): void
    {
        $urls = [];

        $salesChannelId = $this->getStorefrontSalesChannelId($context);
        if (!$salesChannelId) {
            // Might want to throw an error here
            return;
        }

        foreach ($entries as $entry) {
            $urls[] = [
                'salesChannelId' => $salesChannelId,
                'foreignKey' => $entry->getId(),
                // The name of the route in the respective controller
                'routeName' => self::ROUTE_NAME,
                // The technical path of your custom route, using a given parameter
                'pathInfo' => '/example-path/' . $entry->getId(),
                'isCanonical' => true,
                // The SEO URL that you want to use here, in this case just the name
                'seoPathInfo' => '/' . $this->slugify->slugify($entry->getName()),
            ];
        }

        // You might have to create a new context using another specific language ID
        $this->seoUrlPersister->updateSeoUrls($context, self::ROUTE_NAME, array_column($urls, 'foreignKey') , $urls);
    }

    private function getStorefrontSalesChannelId(Context $context): ?string
    {
        $criteria = new Criteria();
        $criteria->addFilter(new EqualsFilter('typeId', Defaults::SALES_CHANNEL_TYPE_STOREFRONT));

        return $this->salesChannelRepository->searchIds($criteria, $context)->firstId();
    }
}
```

The method `writeSeoEntries` will look for a Storefront sales channel and return its ID. It's then iterating over each provided entry, which in this example will need a method called `getId` and method called `getName`. Using this data, an array of URLs to be written is created. Make sure to change the values of the following keys:

* `routeName`: The technical name of your route, configured in your controller
* `pathInfo`: The technical, non-SEO, path of your route, also configured in your controller
* `seoPathInfo`: The actual SEO path you want to use - in this case the name of the said content

::: info
This guide will not cover creating an actual controller with the used example route. Learn how that is done in our guide about [creating a storefront controller](../../storefront/add-custom-controller).
:::

It will then use the built array and all of the other information like the context, the route name and an array of foreign keys for the method `updateSeoUrls` of the `SeoUrlPersister`. And that's it for your dynamic content.

#### Reacting to deletion of the content

If your custom dynamic content is deleted, you have to set the column `is_deleted` to `1` of the respective `seo_url` entry. This can be achieved with a new method, in this example we'll call it `deleteSeoEntries`. It will receive an array of IDs to be deleted. Those IDs have to match the value of the column `foreign_key` in the `seo_url` table. Also it needs the current context. It will take care of setting the generated SEO URLs to `deleted`. It will **not** delete an entry from the table `seo_url`.

```php
public function deleteSeoEntries(array $ids, Context $context): void
{
    $this->seoUrlPersister->updateSeoUrls($context, self::ROUTE_NAME, $ids, []);
}
```

This way the respective SEO URLs will be marked as `is_deleted` for the system. However, this SEO route will remain accessible, so make sure to implement a check whether or not the content still exists in your controller.

#### Writing SEO URLs for another language

In the example mentioned above, we're just using a `Context` instance, for whichever language that is. You can be more specific here though, in order to properly define the language ID yourself here and therefore ensuring it is written for the right language.

```php
$context = new Context(
    $event->getContext()->getSource(),
    $event->getContext()->getRuleIds(),
    $event->getContext()->getCurrencyId(),
    [$languageId]
);
```

You can then pass this context to the `updateSeoUrls` method.

---

---
url: /docs/guides/plugins/plugins/content/seo/add-custom-seo-url.md
---

# Add Custom SEO URLs

## Overview

Shopware supports SEO URL usage for products, categories, and other entities. This guide covers how to define both static and dynamic custom SEO URLs for custom entities.

## Prerequisites

Review the plugin base guide:

It is also important to understand [Custom storefront controllers](../../storefront/controllers/add-custom-controller.md) and [plugin migrations](../../database/database-migrations.md), which are relevant to the static SEO URL example, and [Custom entities](../../framework/data-handling/add-custom-complex-data.md) and [DAL event](../../framework/data-handling/replacing-associated-data.md) usage for dynamic SEO URLs.

## Static SEO URLs

A static SEO URL doesn't have to change every now and then. Imagine a custom controller, which is accessible via the link `yourShop.com/example`.

To make this URL translatable, add a custom SEO URL to the controller route so it is accessible using both `Example-Page` in English and`Beispiel-Seite` in German.

### Example controller

This example uses the controller from the [Add custom controller guide](../../storefront/controllers/add-custom-controller.md). It creates a controller with a route like the example mentioned above: `/example`

Let's now have a look at our example controller:

```php
// <plugin root>/src/Storefront/Controller/ExampleController.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

use Shopware\Core\PlatformRequest;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Controller\StorefrontController;
use Shopware\Storefront\Framework\Routing\StorefrontRouteScope;
use Symfony\Component\HttpFoundation\Request;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

#[Route(defaults: [PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [StorefrontRouteScope::ID]])]
class ExampleController extends StorefrontController
{
    #[Route(path: '/example', name: 'frontend.example.example', methods: ['GET'])]
    public function showExample(): Response
    {
        return $this->renderStorefront('@SwagBasicExample/storefront/page/example/index.html.twig', [
            'example' => 'Hello world'
        ]);
    }
}
```

The important information you'll need here is the route name, `frontend.example.example`, as well as the route itself: `/example`. Make sure to remember those for the next step.

### Example migration

Creating a SEO URL in this scenario can be achieved by creating a [plugin migration](../../database/database-migrations.md).

The migration has to insert an entry for each sales channel and language into the `seo_url` table. For this case, we're making use of the `ImportTranslationsTrait`, which comes with a helper method `importTranslation`.

Don't be confused here, we'll just treat the `seo_url` table like a translation table, since it also needs a `language_id` and respective translated SEO URLs. You'll have to pass a German and an English array into an instance of the `Translations` class, which is then the second parameter for the `importTranslation` method.

Let's have a look at an example:

```php
// <plugin root>/src/Migration/Migration1619094740AddStaticSeoUrl.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Framework\Uuid\Uuid;
use Shopware\Core\Migration\Traits\ImportTranslationsTrait;
use Shopware\Core\Migration\Traits\Translations;

class Migration1619094740AddStaticSeoUrl extends MigrationStep
{
    use ImportTranslationsTrait;

    public function getCreationTimestamp(): int
    {
        return 1619094740;
    }

    public function update(Connection $connection): void
    {
        $this->importTranslation('seo_url', new Translations(
            // German array
            array_merge($this->getSeoMetaArray($connection), ['seo_path_info' => 'Beispiel-Seite']),
            // English array
            array_merge($this->getSeoMetaArray($connection), ['seo_path_info' => 'Example-Page']),

        ), $connection);
    }

    private function getSeoMetaArray(Connection $connection): array
    {
        return [
            'id' => Uuid::randomBytes(),
            'sales_channel_id' => $this->getStorefrontSalesChannelId($connection),
            'foreign_key' => Uuid::randomBytes(),
            'route_name' => 'frontend.example.example',
            'path_info' => '/example',
            'is_canonical' => 1,
            'is_modified' => 0,
            'is_deleted' => 0,
        ];
    }

    private function getStorefrontSalesChannelId(Connection $connection): ?string
    {
        $sql = <<<SQL
            SELECT id
            FROM sales_channel
            WHERE type_id = :typeId
SQL;
        $salesChannelId = $connection->fetchOne($sql, [
            ':typeId' => Uuid::fromHexToBytes(Defaults::SALES_CHANNEL_TYPE_STOREFRONT)
        ]);

        if (!$salesChannelId) {
            return null;
        }

        return $salesChannelId;
    }
}
```

Consider reviewing the `getSeoMetaArray` method, implemented here. Most important are the columns `route_name` and `path_info`, which represent the values you've defined in your controller's route attributes.

By using the default PHP method `array_merge`, we're then also adding our translated SEO URL to the column `seo_path_info`.

And that's it! After installing the plugin, you should be able to access your controller's route with the given SEO URLs.

::: info
You can only access the German SEO URL if you've configured a German domain in your respective sales channel first.
:::

## Dynamic SEO URLs

Dynamic SEO URLs are URLs, that have to change every now and then. Yet, there's another separation necessary.

If you're going to generate custom SEO URLs for your custom entities, you'll have to follow the section about [Dynamic SEO URLs for entities](add-custom-seo-url#dynamic-seo-urls-for-entities). For all other kinds of dynamic content, that are not DAL entities, the section about [Dynamic SEO URLs for other content](add-custom-seo-url#dynamic-seo-urls-for-custom-content) is your way to go.

### Dynamic SEO URLs for entities

This scenario will be about a custom entity, to be specific we're going to use the entity from our guide about [adding custom complex data](../../framework/data-handling/add-custom-complex-data.md), which then would have a custom Storefront route for each entity.

Each entity comes with a name, which eventually should be the SEO URL. Thus, your entity named `Foo` should be accessible using the route `yourShop.com/Foo` or `yourShop.com/Entities/Foo` or whatever you'd like. Now, everytime you create a new entity, a SEO URL has to be automatically created as well. When you update your entities' name, guess what, you'll have to change the SEO URL as well.

For this scenario, you can make use of the Shopware built-in `SeoUrlRoute` classes, which hold all necessary information about your dynamic route and will then create the respective `seo_url` entries automatically.

Let's first have a look at such an example class:

```php
// <plugin root>/src/Storefront/Framework/Seo/SeoUrlRoute/ExamplePageSeoUrlRoute.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Framework\Seo\SeoUrlRoute;

use Shopware\Core\Content\Seo\SeoUrlRoute\SeoUrlMapping;
use Shopware\Core\Content\Seo\SeoUrlRoute\SeoUrlRouteConfig;
use Shopware\Core\Content\Seo\SeoUrlRoute\SeoUrlRouteInterface;
use Shopware\Core\Framework\DataAbstractionLayer\Entity;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\System\SalesChannel\SalesChannelEntity;
use Swag\BasicExample\Core\Content\Example\ExampleDefinition;
use Swag\BasicExample\Core\Content\Example\ExampleEntity;

class ExamplePageSeoUrlRoute implements SeoUrlRouteInterface
{
    public const ROUTE_NAME = 'frontend.example.example';
    public const DEFAULT_TEMPLATE = '{{ example.name }}';

    private ExampleDefinition $exampleDefinition;

    public function __construct(ExampleDefinition $exampleDefinition)
    {
        $this->exampleDefinition = $exampleDefinition;
    }

    public function getConfig(): SeoUrlRouteConfig
    {
        return new SeoUrlRouteConfig(
            $this->exampleDefinition,
            self::ROUTE_NAME,
            self::DEFAULT_TEMPLATE,
            true
        );
    }

    public function prepareCriteria(Criteria $criteria): void
    {
    }

    public function getMapping(Entity $example, ?SalesChannelEntity $salesChannel): SeoUrlMapping
    {
        if (!$example instanceof ExampleEntity) {
            throw new \InvalidArgumentException('Expected ExampleEntity');
        }

        $exampleJson = $example->jsonSerialize();

        return new SeoUrlMapping(
            $example,
            ['exampleId' => $example->getId()],
            [
                'example' => $exampleJson,
            ]
        );
    }
}
```

```php
// <plugin root>/src/Resources/config/services.php
<?php declare(strict_types=1);

use Swag\BasicExample\Core\Content\Example\ExampleDefinition;
use Swag\BasicExample\Storefront\Framework\Seo\SeoUrlRoute\ExamplePageSeoUrlRoute;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(ExamplePageSeoUrlRoute::class)
        ->args([
            service(ExampleDefinition::class),
        ])
        ->tag('shopware.seo_url.route');
};
```

Okay, so let's look through this step by step.

Your custom "SeoUrlRoute" class has to implement the `SeoUrlRouteInterface`, which comes with three necessary methods:

* `getConfig`: Here you have to return an instance of `SeoUrlRouteConfig`, containing your entity's definition,

  the technical name of the route to be used, and the desired SEO path.

* `prepareCriteria`: Here you can adjust the criteria instance, which will be used to fetch your entities.

  Here you can e.g. narrow down which entities may be used for the SEO URL generation. For example you could add a filter

  on an `active` field and therefore only generate SEO URLs for active entities. Also you can add associations here,

  which will then be available with the entity provided in the `getMapping` method.

* `getMapping`: In this method you have to return an instance of `SeoUrlMapping`. It has to contain the actually

  available data for the SEO URL template. If you're using a variable `example.name` in the SEO URL template, you have to

  provide the data for the key `example` here.

Make sure to check which kind of entity has been applied to the `getMapping` method, since you don't want to provide mappings for other entities than your custom one.

It then has to be registered to the container using the tag `shopware.seo_url.route`.

Now that you've set up this class, there are two more things to be done, which are covered in the next sections.

### Example subscriber

Every time your entity is written now, you have to let Shopware know, that you want to generate the SEO URLs for those entities now. This is done by reacting to the [DAL events](../../framework/data-handling/using-database-events.md) of your custom entity, to be specific we're going to use the `written` event. Everytime your entity is written, you then have to execute the `update` method of the `Shopware\Core\Content\Seo\SeoUrlUpdater` class.

Once again, let's have a look at an example subscriber here:

```php
// <plugin root>/src/Service/DynamicSeoUrlPageSubscriber.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Content\Seo\SeoUrlUpdater;
use Shopware\Core\Framework\DataAbstractionLayer\Event\EntityWrittenEvent;
use Swag\BasicExample\Storefront\Framework\Seo\SeoUrlRoute\ExamplePageSeoUrlRoute;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class DynamicSeoUrlPageSubscriber implements EventSubscriberInterface
{
    private SeoUrlUpdater $seoUrlUpdater;

    public function __construct(SeoUrlUpdater $seoUrlUpdater) {
        $this->seoUrlUpdater = $seoUrlUpdater;
    }

    public static function getSubscribedEvents(): array
    {
        return [
            'swag_example.written' => 'onEntityWritten'
        ];
    }

    public function onEntityWritten(EntityWrittenEvent $event): void
    {
        $this->seoUrlUpdater->update(ExamplePageSeoUrlRoute::ROUTE_NAME, $event->getIds());
    }
}
```

```php
// <plugin root>/src/Resources/config/services.php
<?php declare(strict_types=1);

use Shopware\Core\Content\Seo\SeoUrlUpdater;
use Swag\BasicExample\Service\DynamicSeoUrlPageSubscriber;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(DynamicSeoUrlPageSubscriber::class)
        ->args([
            service(SeoUrlUpdater::class),
        ])
        ->tag('kernel.event_subscriber');
};
```

As already said, we're using the `written` event of our custom entity by providing the entities' technical name with the `.written` suffix. Everytime it is executed, we're just using the said `update` method of the `SeoUrlUpdater`. Here you'll have to provide the technical route name and the IDs of the entities, that need to be updated. And that's it for the subscriber.

The `SeoUrlUpdater` will need one more thing in order to work properly: An entry in the table `seo_url_template`, which is done in the next step.

### Example `SeoUrlTemplate` migration

Now we need to add an entry to the `seo_url_template` table for our new dynamic SEO URL template. This is done by adding a [database migration](../../database/database-migrations.md) to our plugin.

The most important values you'll have to set in the migration are:

* `route_name`: We've defined this multiple times already. Use the constant from your `ExamplePageSeoUrlRoute` class
* `entity_name`: The technical name of your custom entity. In this guide it's `swag_example`
* `template`: Once again use the constant `DEFAULT_TEMPLATE` from your `ExamplePageSeoUrlRoute` class

Now here is the said example migration:

```php
// <plugin root>/src/Migration/Migration1619514731AddExampleSeoUrlTemplate.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Framework\Uuid\Uuid;
use Swag\BasicExample\Storefront\Framework\Seo\SeoUrlRoute\ExamplePageSeoUrlRoute;

class Migration1619514731AddExampleSeoUrlTemplate extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1619514731;
    }

    public function update(Connection $connection): void
    {
        $connection->insert('seo_url_template', [
            'id' => Uuid::randomBytes(),
            'sales_channel_id' => null,
            'route_name' => ExamplePageSeoUrlRoute::ROUTE_NAME,
            'entity_name' => 'swag_example',
            'template' => ExamplePageSeoUrlRoute::DEFAULT_TEMPLATE,
            'created_at' => (new \DateTimeImmutable())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
        ]);
    }
}
```

And that's it! Every time your entity is written now, you'll automatically generate a SEO URL for it.

::: info
Review the guide on [creating a storefront controller](../../storefront/controllers/add-custom-controller.md) to learn how to create a controller with the used example route.
:::

### Reacting to entity deletion

If your entity is deleted, you want the SEO URL to be updated as well. In detail, the column `is_deleted` of the respective entry in the `seo_url` table has to be set to `1`.

This can be achieved by using the DAL event `.deleted` and then executing the `update` method again.

```php
// <plugin root>/src/Service/DynamicSeoUrlPageSubscriber.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Content\Seo\SeoUrlUpdater;
use Shopware\Core\Framework\DataAbstractionLayer\Event\EntityDeletedEvent;
use Shopware\Core\Framework\DataAbstractionLayer\Event\EntityWrittenEvent;
use Swag\BasicExample\Storefront\Framework\Seo\SeoUrlRoute\ExamplePageSeoUrlRoute;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class DynamicSeoUrlPageSubscriber implements EventSubscriberInterface
{
    // ...

    public static function getSubscribedEvents(): array
    {
        return [
            'swag_example.written' => 'onEntityWritten',
            'swag_example.deleted' => 'onEntityDeleted'
        ];
    }

    // ...

    public function onEntityDeleted(EntityDeletedEvent $event): void
    {
        $this->seoUrlUpdater->update(ExamplePageSeoUrlRoute::ROUTE_NAME, $event->getIds());
    }
}
```

### Dynamic SEO URLs for custom content

This section is specifically about dynamic content other than custom entities. This could be e.g. data from an external resource, maybe external APIs.

You'll need some kind of event or some other way to execute code once your dynamic content changes, like once a new instance of that content is created or once it is updated.

In this example, we'll assume you've got a class called `DynamicSeoUrlsService` with a method `writeSeoEntries`. This method will get an array of entries to be written, including their respective payload, such as a name for the SEO URL. It also needs the current context.

Calling this method depends on your setup and the type of "dynamic content."

This method will then use the `SeoUrlPersister` and its method `updateSeoUrls` in order to write entries to the `seo_url` table.

Here's an example of such a class:

```php
// <plugin root>/src/Service/DynamicSeoUrlsService.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Cocur\Slugify\SlugifyInterface;
use Shopware\Core\Content\Seo\SeoUrlPersister;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Filter\EqualsFilter;

class DynamicSeoUrlsService
{
    public const ROUTE_NAME = 'example.route.name';

    private SeoUrlPersister $seoUrlPersister;

    private EntityRepository $salesChannelRepository;

    private SlugifyInterface $slugify;

    public function __construct(
        SeoUrlPersister $seoUrlPersister,
        EntityRepository $salesChannelRepository,
        SlugifyInterface $slugify
    ) {
        $this->seoUrlPersister = $seoUrlPersister;
        $this->salesChannelRepository = $salesChannelRepository;
        $this->slugify = $slugify;
    }

    public function writeSeoEntries(array $entries, Context $context): void
    {
        $urls = [];

        $salesChannelId = $this->getStorefrontSalesChannelId($context);
        if (!$salesChannelId) {
            // Might want to throw an error here
            return;
        }

        foreach ($entries as $entry) {
            $urls[] = [
                'salesChannelId' => $salesChannelId,
                'foreignKey' => $entry->getId(),
                // The name of the route in the respective controller
                'routeName' => self::ROUTE_NAME,
                // The technical path of your custom route, using a given parameter
                'pathInfo' => '/example-path/' . $entry->getId(),
                'isCanonical' => true,
                // The SEO URL that you want to use here, in this case just the name
                'seoPathInfo' => '/' . $this->slugify->slugify($entry->getName()),
            ];
        }

        // You might have to create a new context using another specific language ID
        $this->seoUrlPersister->updateSeoUrls($context, self::ROUTE_NAME, array_column($urls, 'foreignKey') , $urls);
    }

    private function getStorefrontSalesChannelId(Context $context): ?string
    {
        $criteria = new Criteria();
        $criteria->addFilter(new EqualsFilter('typeId', Defaults::SALES_CHANNEL_TYPE_STOREFRONT));

        return $this->salesChannelRepository->searchIds($criteria, $context)->firstId();
    }
}
```

The method `writeSeoEntries` will look for a Storefront sales channel and return its ID. It's then iterating over each provided entry, which in this example will need a method called `getId` and method called `getName`. Using this data, an array of URLs to be written is created. Make sure to change the values of the following keys:

* `routeName`: The technical name of your route, configured in your controller
* `pathInfo`: The technical, non-SEO, path of your route, also configured in your controller
* `seoPathInfo`: The actual SEO path you want to use - in this case the name of the said content

::: info
The [creating a storefront controller](../../storefront/controllers/add-custom-controller.md) guide covers how to create a controller with the example route used here.
:::

It will then use the built array and all of the other information like the context, the route name and an array of foreign keys for the method `updateSeoUrls` of the `SeoUrlPersister`. And that's it for your dynamic content.

## Reacting to content deletion

If your custom dynamic content is deleted, you have to set the column `is_deleted` to `1` of the respective `seo_url` entry. This can be achieved with a new method, in this example we'll call it `deleteSeoEntries`. It will receive an array of IDs to be deleted. Those IDs have to match the value of the column `foreign_key` in the `seo_url` table. Also it needs the current context. It will take care of setting the generated SEO URLs to `deleted`. It will **not** delete an entry from the table `seo_url`.

```php
public function deleteSeoEntries(array $ids, Context $context): void
{
    $this->seoUrlPersister->updateSeoUrls($context, self::ROUTE_NAME, $ids, []);
}
```

This way the respective SEO URLs will be marked as `is_deleted` for the system. However, this SEO route will remain accessible, so make sure to implement a check whether or not the content still exists in your controller.

## Writing SEO URLs for another language

In the example mentioned above, we're just using a `Context` instance, for whichever language that is. You can be more specific here though, in order to properly define the language ID yourself here and therefore ensuring it is written for the right language.

```php
$context = new Context(
    $event->getContext()->getSource(),
    $event->getContext()->getRuleIds(),
    $event->getContext()->getCurrencyId(),
    [$languageId]
);
```

You can then pass this context to the `updateSeoUrls` method.

---

---
url: /docs/guides/plugins/plugins/services/add-custom-service.md
---

# Add Custom Service

In this guide you'll learn how to create a custom service using the Symfony [DI Container](https://symfony.com/doc/current/service_container.html).

## Prerequisites

This guide builds on the [Plugin Base Guide](../plugin-base-guide.md).

## Register a service

Create a `services.php` file at `src/Resources/config/services.php` in your plugin.

::: code-group

```php [PLUGIN_ROOT/src/Resources/config/services.php]
<?php declare(strict_types=1);

use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();
};
```

:::

There are two approaches:

### Using autowire and autoconfigure

Set `autowire` and `autoconfigure` to `true` in your `services.php` file.
Symfony will then automatically register your service.
Read more about it in the [Symfony docs](https://symfony.com/doc/current/service_container.html#creating-configuring-services-in-the-container).

::: code-group

```php [PLUGIN_ROOT/src/Resources/config/services.php]
<?php declare(strict_types=1);

use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services()
        ->defaults()
            ->autowire()
            ->autoconfigure();

    $services->load('Swag\\BasicExample\\', '../../')
        ->exclude('../../{Resources,Migration,*.php}');
};
```

:::

Now every PHP class in the `src` directory of your plugin will be registered as a service.
The directory `Resources` and `Migration` are excluded, as they usually should not contain services.

### Explicit declaration

Instead of autowiring and autoconfiguring, you can also declare your service explicitly.
Use this option if you want to have more control over your service.

::: code-group

```php [PLUGIN_ROOT/src/Resources/config/services.php]
<?php declare(strict_types=1);

use Swag\BasicExample\Service\ExampleService;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(ExampleService::class);
};
```

:::

### Actual service class

Example service class:

::: code-group

```php [PLUGIN_ROOT/src/Service/ExampleService.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

class ExampleService
{
    public function doSomething(): void
    {
        ...
    }
}
```

:::

::: info
By default, all services in Shopware 6 are marked as *private*.
Read more about [private and public services](https://symfony.com/doc/current/service_container.html#public-versus-private-services).
:::

## Alternatives to PHP configuration

Symfony supports two other file formats to define your services: YAML and XML.
However, starting with Symfony 7.4, XML service configuration has been deprecated, and it will no longer be supported in Symfony 8.0.

## Next steps

You can apply the same approach to register other plugin classes, such as [commands](../plugin-fundamentals/add-custom-commands.md), [scheduled tasks](../plugin-fundamentals/add-scheduled-task.md), or a [subscriber to listen to events](../framework/event/listening-to-events.md).

See also: [Adjusting a service](../services/adjusting-service.md).

---

---
url: /docs/v6.5/guides/plugins/plugins/plugin-fundamentals/add-custom-service.md
---

# Add Custom Service

## Overview

In this guide you'll learn how to create a custom service using the Symfony [DI Container](https://symfony.com/doc/current/service_container.html).

## Prerequisites

In order to add your own custom service for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide).

## Adding service

Adding a custom service requires to load a `services.xml` file with your plugin. This is done by placing a file with name `services.xml` into a directory called `src/Resources/config/`.

Here's our example `services.xml`:

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Service\ExampleService" />
    </services>
</container>
```

Therefore, this is how your service could then look like:

```php
// <plugin root>/src/Service/ExampleService.php
// SwagBasicExample/src/Service/ExampleService.php

<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

class ExampleService
{
    public function doSomething(): void
    {
        ...
    }
}
```

::: info
By default, all services in Shopware 6 are marked as *private*. Read more about [private and public services](https://symfony.com/doc/current/service_container.html#public-versus-private-services).
:::

## Next steps

You have now created your own custom service. In the same manner, you can create other important plugin classes, such as [commands](add-custom-commands), [scheduled tasks](add-scheduled-task) or a [subscriber to listen to events](listening-to-events).

Furthermore, we also have a guide explaining how to [customize an existing service](adjusting-service) instead.

---

---
url: /docs/v6.6/guides/plugins/plugins/plugin-fundamentals/add-custom-service.md
---

# Add Custom Service

## Overview

In this guide you'll learn how to create a custom service using the Symfony [DI Container](https://symfony.com/doc/current/service_container.html).

## Prerequisites

In order to add your own custom service for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide).

## Adding service

Adding a custom service requires to load a `services.xml` file with your plugin. This is done by placing a file with name `services.xml` into a directory called `src/Resources/config/`.

Here's our example `services.xml`:

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Service\ExampleService" />
    </services>
</container>
```

Therefore, this is how your service could then look like:

```php
// <plugin root>/src/Service/ExampleService.php
// SwagBasicExample/src/Service/ExampleService.php

<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

class ExampleService
{
    public function doSomething(): void
    {
        ...
    }
}
```

::: info
By default, all services in Shopware 6 are marked as *private*. Read more about [private and public services](https://symfony.com/doc/current/service_container.html#public-versus-private-services).
:::

## Next steps

You have now created your own custom service. In the same manner, you can create other important plugin classes, such as [commands](add-custom-commands), [scheduled tasks](add-scheduled-task) or a [subscriber to listen to events](listening-to-events).

Furthermore, we also have a guide explaining how to [customize an existing service](adjusting-service) instead.

---

---
url: /docs/guides/plugins/plugins/content/sitemap/add-custom-sitemap-entries.md
---

# Add Custom Sitemap Entries

## Overview

Shopware includes built-in sitemap generation for products, categories, and other core URLs. This guide explains how to
extend it by adding your own custom URLs to the sitemap.

## Ways to add custom URLs to the sitemap

There are two approaches to adding custom URLs to the sitemap, depending on your use case. For static URLs that rarely
change, use the configuration method. For dynamic URLs based on custom entities or database content, implement a custom
URL provider.

### By using the configuration

To add a custom URL to the sitemap, use the configuration setting `shopware.sitemap.custom_urls`

```yaml
shopware:
    sitemap:
        custom_urls:
            -   url: 'custom-url'
                salesChannelId: '98432def39fc4624b33213a56b8c944d'
                changeFreq: 'weekly'
                priority: 0.5
                lastMod: '2024-09-19 12:19:00'
            -   url: 'custom-url-2'
                salesChannelId: '98432def39fc4624b33213a56b8c944d'
                changeFreq: 'weekly'
                priority: 0.5
                lastMod: '2024-09-18 12:18:00'
```

The `salesChannelId` is the ID of the sales channel you want to add the URL to.

### By adding a URL provider

This part of the guide is mainly built upon the guide about [Adding a custom SEO URL](../seo/add-custom-seo-url.md#dynamic-seo-urls-for-custom-content),
so you might want to have a look at that.
The said guide comes with a custom entity, a controller with a technical route to display each entity, and a custom SEO URL.
All of this will be needed for this guide, as we're going to add the custom entity SEO URLs to the sitemap here.

So let's get started.
Adding custom URLs to the sitemap is done by adding a so-called "URL provider" to the system.

This is done by adding a new class, which is extending from `Shopware\Core\Content\Sitemap\Provider\AbstractUrlProvider`.
It then has to be registered to the [service container](../../services/dependency-injection.md) using the tag
`shopware.sitemap_url_provider`.

It has to provide three methods:

* `getDecorated`: Just throw an exception of type `DecorationPatternException` here. This is done for the sake of extending
  a class via decoration. Learn more about this [here](../../services/adjusting-service.md).
* `getName`: A technical name for your custom URLs
* `getUrls`: The main method to take care of. It has to return an instance of `Shopware\Core\Content\Sitemap\Struct\UrlResult`,
  containing an array of all URLs to be added.

Let's have a look at the example class:

```php
// <plugin root>/src/Core/Content/Sitemap/Provider/CustomUrlProvider.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Sitemap\Provider;

use Doctrine\DBAL\Connection;
use Shopware\Core\Content\Sitemap\Provider\AbstractUrlProvider;
use Shopware\Core\Content\Sitemap\Struct\Url;
use Shopware\Core\Content\Sitemap\Struct\UrlResult;
use Shopware\Core\Framework\DataAbstractionLayer\Doctrine\FetchModeHelper;
use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\Framework\Plugin\Exception\DecorationPatternException;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Swag\BasicExample\Core\Content\Example\ExampleEntity;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
use Symfony\Component\Routing\RouterInterface;

class CustomUrlProvider extends AbstractUrlProvider
{
    public const CHANGE_FREQ = 'daily';
    public const PRIORITY = 1.0;

    private EntityRepository $exampleRepository;

    private Connection $connection;

    private RouterInterface $router;

    public function __construct(
        EntityRepository $exampleRepository,
        Connection $connection,
        RouterInterface $router
    ) {
        $this->exampleRepository = $exampleRepository;
        $this->connection = $connection;
        $this->router = $router;
    }

    public function getDecorated(): AbstractUrlProvider
    {
        throw new DecorationPatternException(self::class);
    }

    public function getName(): string
    {
        return 'custom';
    }

    /**
     * {@inheritdoc}
     */
    public function getUrls(SalesChannelContext $context, int $limit, ?int $offset = null): UrlResult
    {
        $criteria = new Criteria();
        $criteria->setLimit($limit);
        $criteria->setOffset($offset);

        $exampleEntities = $this->exampleRepository->search($criteria, $context->getContext());

        if ($exampleEntities->count() === 0) {
            return new UrlResult([], null);
        }

        $seoUrls = $this->getSeoUrls($exampleEntities->getIds(), 'frontend.example.example', $context, $this->connection);
        $seoUrls = FetchModeHelper::groupUnique($seoUrls);

        $urls = [];

        /** @var ExampleEntity $exampleEntity */
        foreach ($exampleEntities as $exampleEntity) {
            $exampleUrl = new Url();
            $exampleUrl->setLastmod($exampleEntity->getUpdatedAt() ?? new \DateTime());
            $exampleUrl->setChangefreq(self::CHANGE_FREQ);
            $exampleUrl->setPriority(self::PRIORITY);
            $exampleUrl->setResource(ExampleEntity::class);
            $exampleUrl->setIdentifier($exampleEntity->getId());

            if (isset($seoUrls[$exampleEntity->getId()])) {
                $exampleUrl->setLoc($seoUrls[$exampleEntity->getId()]['seo_path_info']);
            } else {
                $exampleUrl->setLoc(
                    $this->router->generate(
                        'frontend.example.example',
                        ['exampleId' => $exampleEntity->getId()],
                        UrlGeneratorInterface::ABSOLUTE_PATH
                    )
                );
            }

            $urls[] = $exampleUrl;
        }

        return new UrlResult($urls, null);
    }
}
```

```php
// <plugin root>/src/Resources/config/services.php
<?php declare(strict_types=1);

use Doctrine\DBAL\Connection;
use Swag\BasicExample\Core\Content\Sitemap\Provider\CustomUrlProvider;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(CustomUrlProvider::class)
        ->args([
            service('swag_example.repository'),
            service(Connection::class),
            service('router'),
        ])
        ->tag('shopware.sitemap_url_provider');
};
```

Let's go through this step by step.
Start by creating a new class `CustomUrlProvider`, which is extending from the `AbstractUrlProvider`.
Following are the constants `CHANGE_FREQ` and `priority` - you don't have to add those values as constants of course.
They're going to be used later in the generation of the sitemap URLs.

Passed into the constructor are the repository for our [custom entity](../../framework/data-handling/add-custom-complex-data.md),
the DBAL connection used for actually fetching SEO URLs from the database, and the Symfony router to generate SEO URLs
that have not yet been written to the database.

Now let's get to the main method `getUrls`.
We start off by fetching all custom entities, using the provided `$limit` and `$offset` values.
Make sure to always use those values, as the sitemap supports "paging" and therefore you do not want to simply fetch all
of your entities.
If there aren't any entities to be fetched, there is nothing more to be done here.

Afterward we fetch all already existing SEO URLs for our custom entities. Once again, have a look at our guide about
[adding a custom SEO URL](../seo/add-custom-seo-url.md) if you don't know how to add custom
SEO URLs in the first place.

We're then iterating over all of our fetched entities, and we create an instance of `Shopware\Core\Content\Sitemap\Struct\Url`
for each iteration.
This struct requests each of the typical sitemap information:

* `lastMod`: The last time this entry was modified. Use the `updatedAt` value here, if available
* `changeFreq`: How often will the entry most likely change?
  Possible values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly` and `never`
* `priority`: Has to have a value between 0 and 1. URLs with higher priority are considered to be "more important" by
  common search engines.
* `resource`: Just a name for your entry, in this example we're just using the entity class name
* `identifier`: The ID of the entry, if available

The most important entry is set afterward, which is the `location`: The actual SEO URL to be indexed.
We're setting this value by checking if the SEO URL for the given entity was already generated, and if not, we're
generating it on the fly.

All of those instances are then stored in an array, which in return is passed to the `UrlResult`.
This completes the implementation. Your custom URLs will now be included in the generated sitemap.

---

---
url: >-
  /docs/v6.5/guides/plugins/plugins/content/sitemap/add-custom-sitemap-entries.md
---

# Add Custom Sitemap Entries

## Overview

Of course Shopware comes with a sitemap generation feature, including products and categories, as well as some more URLs.
This guide however will cover how you can add your own custom URLs to the sitemap.

## Prerequisites

This guide is mostly built upon the guide about \[Adding a custom SEO URL]\(../seo/add-custom-seo-url#Dynamic SEO URLs for entities),
so you might want to have a look at that.
The said guide comes with a custom entity, a controller with a technical route to display each entity, and a custom SEO URL.
All of this will be needed for this guide, as we're going to add the custom entity SEO URLs to the sitemap here.

## Adding an URL provider

So let's get started.
Adding custom URLs to the sitemap is done by adding a so called "URL provider" to the system.

This is done by adding a new class, which is extending from `Shopware\Core\Content\Sitemap\Provider\AbstractUrlProvider`.
It then has to be registered to the [service container](../../plugin-fundamentals/dependency-injection) using the tag
`shopware.sitemap_url_provider`.

It has to provide three methods:

* `getDecorated`: Just throw an exception of type `DecorationPatternException` here. This is done for the sake of extending
  a class via decoration. Learn more about this [here](../../plugin-fundamentals/adjusting-service).
* `getName`: A technical name for your custom URLs
* `getUrls`: The main method to take care of. It has to return an instance of `Shopware\Core\Content\Sitemap\Struct\UrlResult`,
  containing an array of all URLs to be added.

Let's have a look at the example class:

```php
// <plugin root>/src/Core/Content/Sitemap/Provider/CustomUrlProvider.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Sitemap\Provider;

use Doctrine\DBAL\Connection;
use Shopware\Core\Content\Sitemap\Provider\AbstractUrlProvider;
use Shopware\Core\Content\Sitemap\Struct\Url;
use Shopware\Core\Content\Sitemap\Struct\UrlResult;
use Shopware\Core\Framework\DataAbstractionLayer\Doctrine\FetchModeHelper;
use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\Framework\Plugin\Exception\DecorationPatternException;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Swag\BasicExample\Core\Content\Example\ExampleEntity;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
use Symfony\Component\Routing\RouterInterface;

class CustomUrlProvider extends AbstractUrlProvider
{
    public const CHANGE_FREQ = 'daily';
    public const PRIORITY = 1.0;

    private EntityRepository $exampleRepository;

    private Connection $connection;

    private RouterInterface $router;

    public function __construct(
        EntityRepository $exampleRepository,
        Connection $connection,
        RouterInterface $router
    ) {
        $this->exampleRepository = $exampleRepository;
        $this->connection = $connection;
        $this->router = $router;
    }

    public function getDecorated(): AbstractUrlProvider
    {
        throw new DecorationPatternException(self::class);
    }

    public function getName(): string
    {
        return 'custom';
    }

    /**
     * {@inheritdoc}
     */
    public function getUrls(SalesChannelContext $context, int $limit, ?int $offset = null): UrlResult
    {
        $criteria = new Criteria();
        $criteria->setLimit($limit);
        $criteria->setOffset($offset);

        $exampleEntities = $this->exampleRepository->search($criteria, $context->getContext());

        if ($exampleEntities->count() === 0) {
            return new UrlResult([], null);
        }

        $seoUrls = $this->getSeoUrls($exampleEntities->getIds(), 'frontend.example.example', $context, $this->connection);
        $seoUrls = FetchModeHelper::groupUnique($seoUrls);

        $urls = [];

        /** @var ExampleEntity $exampleEntity */
        foreach ($exampleEntities as $exampleEntity) {
            $exampleUrl = new Url();
            $exampleUrl->setLastmod($exampleEntity->getUpdatedAt() ?? new \DateTime());
            $exampleUrl->setChangefreq(self::CHANGE_FREQ);
            $exampleUrl->setPriority(self::PRIORITY);
            $exampleUrl->setResource(ExampleEntity::class);
            $exampleUrl->setIdentifier($exampleEntity->getId());

            if (isset($seoUrls[$exampleEntity->getId()])) {
                $exampleUrl->setLoc($seoUrls[$exampleEntity->getId()]['seo_path_info']);
            } else {
                $exampleUrl->setLoc(
                    $this->router->generate(
                        'frontend.example.example',
                        ['exampleId' => $exampleEntity->getId()],
                        UrlGeneratorInterface::ABSOLUTE_PATH
                    )
                );
            }

            $urls[] = $exampleUrl;
        }

        return new UrlResult($urls, null);
    }
}
```

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Core\Content\Sitemap\Provider\CustomUrlProvider" >
            <argument type="service" id="swag_example.repository" />
            <argument type="service" id="Doctrine\DBAL\Connection"/>
            <argument type="service" id="router"/>

            <tag name="shopware.sitemap_url_provider" />
        </service>
    </services>
</container>
```

Let's go through this step by step.
First of all we created a new class `CustomUrlProvider`, which is extending from the `AbstractUrlProvider`.
Following are the constants `CHANGE_FREQ` and `priority` - you don't have to add those values as constants of course.
They're going to be used later in the generation of the sitemap URLs.

Passed into the constructor are the repository for our [custom entity](../../framework/data-handling/add-custom-complex-data),
the DBAL connection used for actually fetching SEO URLs from the database, and the Symfony router in order to generate SEO URLs
that have not yet been written to the database.

Now let's get to the main method `getUrls`.
Here we start of with fetching all custom entities, using the provided `$limit` and `$offset` values.
Make sure to always use those values, as the sitemap support "paging" and therefore you do not want to simply fetch all
of your entities.
If there aren't any entities to be fetched, there is nothing more to be done here.

Afterwards we fetch all already existing SEO URLs for our custom entities. Once again, have a look at our guide about
\[adding a custom SEO URL]\(../seo/add-custom-seo-url#Dynamic SEO URLs for entities) if you don't know how to add custom
SEO URLs in the first place.

We're then iterating over all of our fetched entities and we create an instance of `Shopware\Core\Content\Sitemap\Struct\Url`
for each iteration.
This struct requests each of the typical sitemap information:

* `lastMod`: The last time this entry was modified. Just use the `updatedAt` value here, if available
* `changeFreq`: How often will the entry most likely change?
  Possible values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly` and `never`
* `priority`: Has to have a value between 0 and 1. URLs with higher priority are considered to be "more important" by common
  search engines.
* `resource`: Just a name for your entry, in this example we're just using the entity class name
* `identifier`: The ID of the entry, if available

The most important entry is set afterwards, which is the `location`: The actual SEO URL to be indexed.
We're setting this value by checking if the SEO URL for the given entity was already generated, and if not, we're generating it on the fly.

All of those instances are then stored in array, which in return is passed to the `UrlResult`.
And that's it already!

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/content/sitemap/add-custom-sitemap-entries.md
---

# Add Custom Sitemap Entries

## Overview

Of course Shopware comes with a sitemap generation feature, including products and categories, as well as some more URLs.
This guide however will cover how you can add your own custom URLs to the sitemap.

## By using the configuration

To add a custom URL to the sitemap, use the configuration setting `shopware.sitemap.custom_urls`

```yaml
shopware:
    sitemap:
        custom_urls:
            -   url: 'custom-url'
                salesChannelId: '98432def39fc4624b33213a56b8c944d'
                changeFreq: 'weekly'
                priority: 0.5
                lastMod: '2024-09-19 12:19:00'
            -   url: 'custom-url-2'
                salesChannelId: '98432def39fc4624b33213a56b8c944d'
                changeFreq: 'weekly'
                priority: 0.5
                lastMod: '2024-09-18 12:18:00'
```

The `salesChannelId` is the ID of the sales channel you want to add the URL to.

## By adding a URL provider

This part of the guide is mainly built upon the guide about \[Adding a custom SEO URL]\(../seo/add-custom-seo-url#Dynamic SEO URLs for entities),
so you might want to have a look at that.
The said guide comes with a custom entity, a controller with a technical route to display each entity, and a custom SEO URL.
All of this will be needed for this guide, as we're going to add the custom entity SEO URLs to the sitemap here.

So let's get started.
Adding custom URLs to the sitemap is done by adding a so-called "URL provider" to the system.

This is done by adding a new class, which is extending from `Shopware\Core\Content\Sitemap\Provider\AbstractUrlProvider`.
It then has to be registered to the [service container](../../plugin-fundamentals/dependency-injection) using the tag
`shopware.sitemap_url_provider`.

It has to provide three methods:

* `getDecorated`: Just throw an exception of type `DecorationPatternException` here. This is done for the sake of extending
  a class via decoration. Learn more about this [here](../../plugin-fundamentals/adjusting-service).
* `getName`: A technical name for your custom URLs
* `getUrls`: The main method to take care of. It has to return an instance of `Shopware\Core\Content\Sitemap\Struct\UrlResult`,
  containing an array of all URLs to be added.

Let's have a look at the example class:

```php
// <plugin root>/src/Core/Content/Sitemap/Provider/CustomUrlProvider.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Sitemap\Provider;

use Doctrine\DBAL\Connection;
use Shopware\Core\Content\Sitemap\Provider\AbstractUrlProvider;
use Shopware\Core\Content\Sitemap\Struct\Url;
use Shopware\Core\Content\Sitemap\Struct\UrlResult;
use Shopware\Core\Framework\DataAbstractionLayer\Doctrine\FetchModeHelper;
use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\Framework\Plugin\Exception\DecorationPatternException;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Swag\BasicExample\Core\Content\Example\ExampleEntity;
use Symfony\Component\Routing\Generator\UrlGeneratorInterface;
use Symfony\Component\Routing\RouterInterface;

class CustomUrlProvider extends AbstractUrlProvider
{
    public const CHANGE_FREQ = 'daily';
    public const PRIORITY = 1.0;

    private EntityRepository $exampleRepository;

    private Connection $connection;

    private RouterInterface $router;

    public function __construct(
        EntityRepository $exampleRepository,
        Connection $connection,
        RouterInterface $router
    ) {
        $this->exampleRepository = $exampleRepository;
        $this->connection = $connection;
        $this->router = $router;
    }

    public function getDecorated(): AbstractUrlProvider
    {
        throw new DecorationPatternException(self::class);
    }

    public function getName(): string
    {
        return 'custom';
    }

    /**
     * {@inheritdoc}
     */
    public function getUrls(SalesChannelContext $context, int $limit, ?int $offset = null): UrlResult
    {
        $criteria = new Criteria();
        $criteria->setLimit($limit);
        $criteria->setOffset($offset);

        $exampleEntities = $this->exampleRepository->search($criteria, $context->getContext());

        if ($exampleEntities->count() === 0) {
            return new UrlResult([], null);
        }

        $seoUrls = $this->getSeoUrls($exampleEntities->getIds(), 'frontend.example.example', $context, $this->connection);
        $seoUrls = FetchModeHelper::groupUnique($seoUrls);

        $urls = [];

        /** @var ExampleEntity $exampleEntity */
        foreach ($exampleEntities as $exampleEntity) {
            $exampleUrl = new Url();
            $exampleUrl->setLastmod($exampleEntity->getUpdatedAt() ?? new \DateTime());
            $exampleUrl->setChangefreq(self::CHANGE_FREQ);
            $exampleUrl->setPriority(self::PRIORITY);
            $exampleUrl->setResource(ExampleEntity::class);
            $exampleUrl->setIdentifier($exampleEntity->getId());

            if (isset($seoUrls[$exampleEntity->getId()])) {
                $exampleUrl->setLoc($seoUrls[$exampleEntity->getId()]['seo_path_info']);
            } else {
                $exampleUrl->setLoc(
                    $this->router->generate(
                        'frontend.example.example',
                        ['exampleId' => $exampleEntity->getId()],
                        UrlGeneratorInterface::ABSOLUTE_PATH
                    )
                );
            }

            $urls[] = $exampleUrl;
        }

        return new UrlResult($urls, null);
    }
}
```

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Core\Content\Sitemap\Provider\CustomUrlProvider" >
            <argument type="service" id="swag_example.repository" />
            <argument type="service" id="Doctrine\DBAL\Connection"/>
            <argument type="service" id="router"/>

            <tag name="shopware.sitemap_url_provider" />
        </service>
    </services>
</container>
```

Let's go through this step by step.
First of all we created a new class `CustomUrlProvider`, which is extending from the `AbstractUrlProvider`.
Following are the constants `CHANGE_FREQ` and `priority` - you don't have to add those values as constants of course.
They're going to be used later in the generation of the sitemap URLs.

Passed into the constructor are the repository for our [custom entity](../../framework/data-handling/add-custom-complex-data),
the DBAL connection used for actually fetching SEO URLs from the database, and the Symfony router in order to generate SEO URLs
that have not yet been written to the database.

Now let's get to the main method `getUrls`.
Here we start of with fetching all custom entities, using the provided `$limit` and `$offset` values.
Make sure to always use those values, as the sitemap support "paging" and therefore you do not want to simply fetch all
of your entities.
If there aren't any entities to be fetched, there is nothing more to be done here.

Afterwards we fetch all already existing SEO URLs for our custom entities. Once again, have a look at our guide about
\[adding a custom SEO URL]\(../seo/add-custom-seo-url#Dynamic SEO URLs for entities) if you don't know how to add custom
SEO URLs in the first place.

We're then iterating over all of our fetched entities and we create an instance of `Shopware\Core\Content\Sitemap\Struct\Url`
for each iteration.
This struct requests each of the typical sitemap information:

* `lastMod`: The last time this entry was modified. Just use the `updatedAt` value here, if available
* `changeFreq`: How often will the entry most likely change?
  Possible values are `always`, `hourly`, `daily`, `weekly`, `monthly`, `yearly` and `never`
* `priority`: Has to have a value between 0 and 1. URLs with higher priority are considered to be "more important" by common
  search engines.
* `resource`: Just a name for your entry, in this example we're just using the entity class name
* `identifier`: The ID of the entry, if available

The most important entry is set afterwards, which is the `location`: The actual SEO URL to be indexed.
We're setting this value by checking if the SEO URL for the given entity was already generated, and if not, we're generating it on the fly.

All of those instances are then stored in array, which in return is passed to the `UrlResult`.
And that's it already!

---

---
url: >-
  /docs/guides/plugins/plugins/storefront/howto/add-custom-sorting-product-listing.md
---

# Add Custom Sorting for Product Listing

## Overview

Individual sortings are groups of sorting options which you can use to sort product listings. The sortings are available in the Storefront.

This guide will show you how to add individual sorting options using a migration (manageable) or at runtime (non-manageable).

## Prerequisites

A running plugin is required. Read the [Plugin Base Guide](../../plugin-base-guide.md) for guidance on creating one.

Reviewing the [Database migrations](../../database/database-migrations.md) guide is also advisable.

## Create individual sorting with migration

In order to make your sorting manageable in the Administration by the user, you will need to migrate the data to the database.

Create a new Migration in your plugin:

::: info
Note: Do not change an existing migration if your plugin is already in use by someone. In that case, create a new Migration instead! This also means, that you have to re-install or update your plugin if you adjust the migration.
:::

```php
// <plugin root>/src/Migration/Migration1615470599ExampleSorting.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Content\Product\SalesChannel\Sorting\ProductSortingDefinition;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Framework\Uuid\Uuid;

class Migration1615470599ExampleSorting extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1615470599;
    }

    public function update(Connection $connection): void
    {
        $myCustomSorting = [
            'id' => Uuid::randomBytes(),
            'url_key' => 'my-custom-sort',  // shown in url - must be unique system wide
            'priority' => 5,                // the higher the priority, the further upwards it will be shown in the sortings dropdown in Storefront
            'active' => 1,                  // activate / deactivate the sorting
            'locked' => 0,                  // you can lock the sorting here to prevent it from being edited in the Administration
            'fields' => json_encode([
                [
                    'field' => 'product.name',  // field to sort by
                    'order' => 'desc',          // asc or desc
                    'priority' => 1,            // in which order the sorting is to applied (higher priority comes first)
                    'naturalSorting' => 0       // apply natural sorting logic to this field
                ],
                // ... more fields
            ]),
            'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
        ];

        // insert the product sorting
        $connection->insert(ProductSortingDefinition::ENTITY_NAME, $myCustomSorting);

        // insert the translation for the translatable label
        // if you use multiple languages, you will need to update all of them
        $connection->executeStatement(
            'REPLACE INTO product_sorting_translation
             (`language_id`, `product_sorting_id`, `label`, `created_at`)
             VALUES
             (:language_id, :product_sorting_id, :label, :created_at)',
            [
                'language_id' => Uuid::fromHexToBytes(Defaults::LANGUAGE_SYSTEM),
                'product_sorting_id' => $myCustomSorting['id'],
                'label' => 'My Custom Sorting',
                'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
            ]
        );
    }
}
```

## Create individual sorting at runtime

You can subscribe to the `ProductListingCriteriaEvent` to add a `ProductSortingEntity` as available sorting on the fly. If you don't know how to do this, head over to our [Listening to events](../../framework/event/listening-to-events.md) guide.

::: info
While possible, it is not recommended adding an individual sorting at runtime. If you just wish for your individual sorting to be not editable by users in the Administration, create a migration and set the parameter `locked` to be `true`.
:::

Here's an example how your subscriber could look like:

```php
// <plugin root>/src/Subscriber/ExampleListingSubscriber.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Subscriber;

use Shopware\Core\Content\Product\Events\ProductListingCriteriaEvent;
use Shopware\Core\Content\Product\SalesChannel\Sorting\ProductSortingCollection;
use Shopware\Core\Content\Product\SalesChannel\Sorting\ProductSortingEntity;
use Shopware\Core\Framework\Uuid\Uuid;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class ExampleListingSubscriber implements EventSubscriberInterface
{

    public static function getSubscribedEvents(): array
    {
        return [
            // be sure to subscribe with high priority to add you sorting before the default shopware logic applies
            // otherwise storefront will throw a ProductSortingNotFoundException
            ProductListingCriteriaEvent::class => ['addMyCustomSortingToStorefront', 500],
        ];
    }

    public function addMyCustomSortingToStorefront(ProductListingCriteriaEvent $event): void
    {
        /** @var ProductSortingCollection $availableSortings */
        $availableSortings = $event->getCriteria()->getExtension('sortings') ?? new ProductSortingCollection();

        $myCustomSorting = new ProductSortingEntity();
        $myCustomSorting->setId(Uuid::randomHex());
        $myCustomSorting->setActive(true);
        $myCustomSorting->setTranslated(['label' => 'My Custom Sorting at runtime']);
        $myCustomSorting->setKey('my-custom-runtime-sort');
        $myCustomSorting->setPriority(5);
        $myCustomSorting->setFields([
            [
                'field' => 'product.name',
                'order' => 'desc',
                'priority' => 1,
                'naturalSorting' => 0,
            ],
        ]);

        $availableSortings->add($myCustomSorting);

        $event->getCriteria()->addExtension('sortings', $availableSortings);
    }
}
```

## Next steps

To [add a custom filter](./add-listing-filters.md) to your listing in the Storefront head over to the corresponding guide.

---

---
url: >-
  /docs/v6.5/guides/plugins/plugins/storefront/add-custom-sorting-product-listing.md
---

# Add Custom Sorting for Product Listing

## Overview

Individual sortings are groups of sorting options which you can use to sort product listings. The sortings are available in the Storefront.

This guide will show you how to add individual sorting options using a migration (manageable) or at runtime (non-manageable).

## Prerequisites

In order to add your own custom sorting for product listings for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide).

You should also have a look at our [Database migrations](../plugin-fundamentals/database-migrations) guide, as we use one in this guide.

## Create individual sorting with migration

In order to make your sorting manageable in the Administration by the user, you will need to migrate the data to the database.

Create a new Migration in your plugin:

::: info
Note: Do not change an existing migration if your plugin is already in use by someone. In that case, create a new Migration instead! This also means, that you have to re-install or update your plugin if you adjust the migration.
:::

```php
// <plugin root>/src/Migration/Migration1615470599ExampleSorting.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Content\Product\SalesChannel\Sorting\ProductSortingDefinition;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Framework\Uuid\Uuid;

class Migration1615470599ExampleSorting extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1615470599;
    }

    public function update(Connection $connection): void
    {
        $myCustomSorting = [
            'id' => Uuid::randomBytes(),
            'url_key' => 'my-custom-sort',  // shown in url - must be unique system wide
            'priority' => 5,                // the higher the priority, the further upwards it will be shown in the sortings dropdown in Storefront
            'active' => 1,                  // activate / deactivate the sorting
            'locked' => 0,                  // you can lock the sorting here to prevent it from being edited in the Administration
            'fields' => json_encode([
                [
                    'field' => 'product.name',  // field to sort by
                    'order' => 'desc',          // asc or desc
                    'priority' => 1,            // in which order the sorting is to applied (higher priority comes first)
                    'naturalSorting' => 0       // apply natural sorting logic to this field
                ],
                // ... more fields
            ]),
            'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
        ];

        // insert the product sorting
        $connection->insert(ProductSortingDefinition::ENTITY_NAME, $myCustomSorting);

        // insert the translation for the translatable label
        // if you use multiple languages, you will need to update all of them
        $connection->executeStatement(
            'REPLACE INTO product_sorting_translation
             (`language_id`, `product_sorting_id`, `label`, `created_at`)
             VALUES
             (:language_id, :product_sorting_id, :label, :created_at)',
            [
                'language_id' => Uuid::fromHexToBytes(Defaults::LANGUAGE_SYSTEM),
                'product_sorting_id' => $myCustomSorting['id'],
                'label' => 'My Custom Sorting',
                'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
            ]
        );
    }

    public function updateDestructive(Connection $connection): void
    {
    }
}
```

## Create individual sorting at runtime

You can subscribe to the `ProductListingCriteriaEvent` to add a `ProductSortingEntity` as available sorting on the fly. If you don't know how to do this, head over to our [Listening to events](../plugin-fundamentals/listening-to-events) guide.

::: info
While possible, it is not recommended adding an individual sorting at runtime. If you just wish for your individual sorting to be not editable by users in the Administration, create a migration and set the parameter `locked` to be `true`.
:::

Here's an example how your subscriber could look like:

```php
// <plugin root>/src/Subscriber/ExampleListingSubscriber.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Subscriber;

use Shopware\Core\Content\Product\Events\ProductListingCriteriaEvent;
use Shopware\Core\Content\Product\SalesChannel\Sorting\ProductSortingCollection;
use Shopware\Core\Content\Product\SalesChannel\Sorting\ProductSortingEntity;
use Shopware\Core\Framework\Uuid\Uuid;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class ExampleListingSubscriber implements EventSubscriberInterface
{

    public static function getSubscribedEvents(): array
    {
        return [
            // be sure to subscribe with high priority to add you sorting before the default shopware logic applies
            // otherwise storefront will throw a ProductSortingNotFoundException
            ProductListingCriteriaEvent::class => ['addMyCustomSortingToStorefront', 500],
        ];
    }

    public function addMyCustomSortingToStorefront(ProductListingCriteriaEvent $event): void
    {
        /** @var ProductSortingCollection $availableSortings */
        $availableSortings = $event->getCriteria()->getExtension('sortings') ?? new ProductSortingCollection();

        $myCustomSorting = new ProductSortingEntity();
        $myCustomSorting->setId(Uuid::randomHex());
        $myCustomSorting->setActive(true);
        $myCustomSorting->setTranslated(['label' => 'My Custom Sorting at runtime']);
        $myCustomSorting->setKey('my-custom-runtime-sort');
        $myCustomSorting->setPriority(5);
        $myCustomSorting->setFields([
            [
                'field' => 'product.name',
                'order' => 'desc',
                'priority' => 1,
                'naturalSorting' => 0,
            ],
        ]);

        $availableSortings->add($myCustomSorting);

        $event->getCriteria()->addExtension('sortings', $availableSortings);
    }
}
```

## Next steps

To [add a custom filter](add-listing-filters) to your listing in the Storefront head over to the corresponding guide.

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/storefront/add-custom-sorting-product-listing.md
---

# Add Custom Sorting for Product Listing

## Overview

Individual sortings are groups of sorting options which you can use to sort product listings. The sortings are available in the Storefront.

This guide will show you how to add individual sorting options using a migration (manageable) or at runtime (non-manageable).

## Prerequisites

In order to add your own custom sorting for product listings for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide).

You should also have a look at our [Database migrations](../plugin-fundamentals/database-migrations) guide, as we use one in this guide.

## Create individual sorting with migration

In order to make your sorting manageable in the Administration by the user, you will need to migrate the data to the database.

Create a new Migration in your plugin:

::: info
Note: Do not change an existing migration if your plugin is already in use by someone. In that case, create a new Migration instead! This also means, that you have to re-install or update your plugin if you adjust the migration.
:::

```php
// <plugin root>/src/Migration/Migration1615470599ExampleSorting.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Content\Product\SalesChannel\Sorting\ProductSortingDefinition;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Framework\Uuid\Uuid;

class Migration1615470599ExampleSorting extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1615470599;
    }

    public function update(Connection $connection): void
    {
        $myCustomSorting = [
            'id' => Uuid::randomBytes(),
            'url_key' => 'my-custom-sort',  // shown in url - must be unique system wide
            'priority' => 5,                // the higher the priority, the further upwards it will be shown in the sortings dropdown in Storefront
            'active' => 1,                  // activate / deactivate the sorting
            'locked' => 0,                  // you can lock the sorting here to prevent it from being edited in the Administration
            'fields' => json_encode([
                [
                    'field' => 'product.name',  // field to sort by
                    'order' => 'desc',          // asc or desc
                    'priority' => 1,            // in which order the sorting is to applied (higher priority comes first)
                    'naturalSorting' => 0       // apply natural sorting logic to this field
                ],
                // ... more fields
            ]),
            'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
        ];

        // insert the product sorting
        $connection->insert(ProductSortingDefinition::ENTITY_NAME, $myCustomSorting);

        // insert the translation for the translatable label
        // if you use multiple languages, you will need to update all of them
        $connection->executeStatement(
            'REPLACE INTO product_sorting_translation
             (`language_id`, `product_sorting_id`, `label`, `created_at`)
             VALUES
             (:language_id, :product_sorting_id, :label, :created_at)',
            [
                'language_id' => Uuid::fromHexToBytes(Defaults::LANGUAGE_SYSTEM),
                'product_sorting_id' => $myCustomSorting['id'],
                'label' => 'My Custom Sorting',
                'created_at' => (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
            ]
        );
    }

    public function updateDestructive(Connection $connection): void
    {
    }
}
```

## Create individual sorting at runtime

You can subscribe to the `ProductListingCriteriaEvent` to add a `ProductSortingEntity` as available sorting on the fly. If you don't know how to do this, head over to our [Listening to events](../plugin-fundamentals/listening-to-events) guide.

::: info
While possible, it is not recommended adding an individual sorting at runtime. If you just wish for your individual sorting to be not editable by users in the Administration, create a migration and set the parameter `locked` to be `true`.
:::

Here's an example how your subscriber could look like:

```php
// <plugin root>/src/Subscriber/ExampleListingSubscriber.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Subscriber;

use Shopware\Core\Content\Product\Events\ProductListingCriteriaEvent;
use Shopware\Core\Content\Product\SalesChannel\Sorting\ProductSortingCollection;
use Shopware\Core\Content\Product\SalesChannel\Sorting\ProductSortingEntity;
use Shopware\Core\Framework\Uuid\Uuid;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class ExampleListingSubscriber implements EventSubscriberInterface
{

    public static function getSubscribedEvents(): array
    {
        return [
            // be sure to subscribe with high priority to add you sorting before the default shopware logic applies
            // otherwise storefront will throw a ProductSortingNotFoundException
            ProductListingCriteriaEvent::class => ['addMyCustomSortingToStorefront', 500],
        ];
    }

    public function addMyCustomSortingToStorefront(ProductListingCriteriaEvent $event): void
    {
        /** @var ProductSortingCollection $availableSortings */
        $availableSortings = $event->getCriteria()->getExtension('sortings') ?? new ProductSortingCollection();

        $myCustomSorting = new ProductSortingEntity();
        $myCustomSorting->setId(Uuid::randomHex());
        $myCustomSorting->setActive(true);
        $myCustomSorting->setTranslated(['label' => 'My Custom Sorting at runtime']);
        $myCustomSorting->setKey('my-custom-runtime-sort');
        $myCustomSorting->setPriority(5);
        $myCustomSorting->setFields([
            [
                'field' => 'product.name',
                'order' => 'desc',
                'priority' => 1,
                'naturalSorting' => 0,
            ],
        ]);

        $availableSortings->add($myCustomSorting);

        $event->getCriteria()->addExtension('sortings', $availableSortings);
    }
}
```

## Next steps

To [add a custom filter](add-listing-filters) to your listing in the Storefront head over to the corresponding guide.

---

---
url: /docs/v6.5/guides/plugins/plugins/administration/add-custom-styles.md
---

# Add custom styles

## Overview

All components contain own templates and some style. Of course, you may want to use your custom styles in your component or module. In this guide, we got you covered on how to add those custom styles to your components.

## Prerequisites

However, this guide does not explain how to create a custom component, so head over to the official guide about creating a custom component to learn this first.

In addition, you need to have a basic knowledge of CSS and SCSS in order to use custom styles. This is though considered a basic requirement and won't be taught in this guide.

### Example: Custom cms block

We will base our guide on an example: Let's use a custom component printing out "Hello world!". So first of all, create a new directory for your`sw-hello-world`. As said before, more information about that topic, such as where to create this directory, can be found in [Add a custom component](add-custom-component).

In your component's directory, create a new `index.js` file and register your custom component `sw-hello-world`:

```javascript
Shopware.Component.register('sw-hello-world', {
    template
});
```

Just like most components, it has a custom template. First we create the template file named `sw-hello-world.html.twig`:

This template now has to define the basic structure of your component. In this simple case, you only need a parent container and two sub-elements, whatever those are.

```html
{% block example_block %}
    <div class="sw-hello-world">
        <p>Hello world!</p>
    </div>
{% endblock %}
```

You've got a parent `div` containing the content of your template, an abstract with the text "Hello world!" in this case. Next up, you need to import that template in your `index.js` file of your component:

```javascript
// Import for your template
import template from './sw-hello-world.html.twig';

Shopware.Component.register('sw-sw-hello-world', {
    template
});
```

## Add custom styles to your component

Your component should come with a custom `.scss` file, which you need to create now. Don't forget to import it in your `index.js` file, if not done yet:

```javascript
import template from './sw-hello-world.html.twig';

// Import for your custom styles
import './sw-hello-world.scss';

Shopware.Component.register('sw-sw-hello-world', {
    template
});
```

In there, simply use a grid to display your elements next to each other. You set a CSS class for your block, which is named after the component. In there, you can set your styles as you need. To mention an example, we want the text in the `div` with the class `sw-hello-world` to have a blue color:

```css
.sw-hello-world {
    color: blue;
}
```

That's it for this component! This way, you're able to add your own styles to your component now.

### Import variables

Because of [Sass](https://sass-lang.com/) usage, you are able to import external variables and use them in your classes. Below you see an example which uses Shopware's SCSS variables to color the text of the component in shopware's shade of blue.

```css
/* Import statement */
@import "~scss/variables";

.sw-hello-world {
  /* Usage of variable */
  color: $color-shopware-brand-500;
}
```

## More interesting topics

* [Writing templates](writing-templates)
* [Add shortcuts](https://github.com/shopware/docs/tree/575c2fa12ef272dc25744975e2f1e4d44721f0f1/guides/plugins/plugins/administration/add-shortcuts.md)

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/administration/templates-styling/add-custom-styles.md
---

# Add custom styles

## Overview

All components contain own templates and some style. Of course, you may want to use your custom styles in your component or module. In this guide, we got you covered on how to add those custom styles to your components.

## Prerequisites

However, this guide does not explain how to create a custom component, so head over to the official guide about creating a custom component to learn this first.

In addition, you need to have a basic knowledge of CSS and SCSS in order to use custom styles. This is though considered a basic requirement and won't be taught in this guide.

### Example: Custom cms block

We will base our guide on an example: Let's use a custom component printing out "Hello world!". So first of all, create a new directory for your`sw-hello-world`. As said before, more information about that topic, such as where to create this directory, can be found in [Add a custom component](../module-component-management/add-custom-component.md).

In your component's directory, create a new `index.js` file and register your custom component `sw-hello-world`:

```javascript
Shopware.Component.register('sw-hello-world', {
    template
});
```

Just like most components, it has a custom template. First we create the template file named `sw-hello-world.html.twig`:

This template now has to define the basic structure of your component. In this simple case, you only need a parent container and two sub-elements, whatever those are.

```html
{% block example_block %}
    <div class="sw-hello-world">
        <p>Hello world!</p>
    </div>
{% endblock %}
```

You've got a parent `div` containing the content of your template, an abstract with the text "Hello world!" in this case. Next up, you need to import that template in your `index.js` file of your component:

```javascript
// Import for your template
import template from './sw-hello-world.html.twig';

Shopware.Component.register('sw-sw-hello-world', {
    template
});
```

## Add custom styles to your component

Your component should come with a custom `.scss` file, which you need to create now. Don't forget to import it in your `index.js` file, if not done yet:

```javascript
import template from './sw-hello-world.html.twig';

// Import for your custom styles
import './sw-hello-world.scss';

Shopware.Component.register('sw-sw-hello-world', {
    template
});
```

In there, simply use a grid to display your elements next to each other. You set a CSS class for your block, which is named after the component. In there, you can set your styles as you need. To mention an example, we want the text in the `div` with the class `sw-hello-world` to have a blue color:

```css
.sw-hello-world {
    color: blue;
}
```

That's it for this component! This way, you're able to add your own styles to your component now.

### Import variables

Because of [Sass](https://sass-lang.com/) usage, you are able to import external variables and use them in your classes. Below you see an example which uses Shopware's SCSS variables to color the text of the component in shopware's shade of blue.

```css
/* Import statement */
@import "~scss/variables";

.sw-hello-world {
  /* Usage of variable */
  color: $color-shopware-brand-500;
}
```

## More interesting topics

* [Writing templates](../templates-styling/writing-templates.md)
* [Add shortcuts](https://github.com/shopware/docs/tree/575c2fa12ef272dc25744975e2f1e4d44721f0f1/guides/plugins/plugins/administration/add-shortcuts.md)

---

---
url: >-
  /docs/guides/plugins/plugins/administration/templates-styling/add-custom-styles.md
---

# Add Custom Styles

## Overview

All components contain own templates and some style. Of course, you may want to use your custom styles in your component or module. In this guide, we got you covered on how to add those custom styles to your components.

## Prerequisites

However, this guide does not explain how to create a custom component, so head over to the official guide about creating a custom component to learn this first.

In addition, you need to have a basic knowledge of CSS and SCSS in order to use custom styles. This is though considered a basic requirement and won't be taught in this guide.

### Example: Custom cms block

We will base our guide on an example: Let's use a custom component printing out "Hello world!". So first of all, create a new directory for your`sw-hello-world`. As said before, more information about that topic, such as where to create this directory, can be found in [Add a custom component](../module-component-management/add-custom-component.md).

In your component's directory, create a new `index.js` file and register your custom component `sw-hello-world`:

```javascript
Shopware.Component.register('sw-hello-world', {
    template
});
```

Just like most components, it has a custom template. First we create the template file named `sw-hello-world.html.twig`:

This template now has to define the basic structure of your component. In this simple case, you only need a parent container and two sub-elements, whatever those are.

```html
{% block example_block %}
    <div class="sw-hello-world">
        <p>Hello world!</p>
    </div>
{% endblock %}
```

You've got a parent `div` containing the content of your template, an abstract with the text "Hello world!" in this case. Next up, you need to import that template in your `index.js` file of your component:

```javascript
// Import for your template
import template from './sw-hello-world.html.twig';

Shopware.Component.register('sw-sw-hello-world', {
    template
});
```

## Add custom styles to your component

Your component should come with a custom `.scss` file, which you need to create now. Don't forget to import it in your `index.js` file, if not done yet:

```javascript
import template from './sw-hello-world.html.twig';

// Import for your custom styles
import './sw-hello-world.scss';

Shopware.Component.register('sw-sw-hello-world', {
    template
});
```

In there, simply use a grid to display your elements next to each other. You set a CSS class for your block, which is named after the component. In there, you can set your styles as you need. To mention an example, we want the text in the `div` with the class `sw-hello-world` to have a blue color:

```css
.sw-hello-world {
    color: blue;
}
```

That's it for this component! This way, you're able to add your own styles to your component now.

### Import variables

Because of [Sass](https://sass-lang.com/) usage, you are able to import external variables and use them in your classes. Below you see an example which uses Shopware's SCSS variables to color the text of the component in shopware's shade of blue.

```css
/* Import statement */
@import "~scss/variables";

.sw-hello-world {
  /* Usage of variable */
  color: $color-shopware-brand-500;
}
```

## More interesting topics

* [Writing templates](../templates-styling/writing-templates.md)
* [Add shortcuts](https://github.com/shopware/docs/blob/575c2fa12ef272dc25744975e2f1e4d44721f0f1/guides/plugins/plugins/administration/add-shortcuts.md)

---

---
url: /docs/guides/plugins/plugins/storefront/styling/add-custom-styling.md
---

# Add Custom Styling

## Overview

Quite often your plugin will have to change a few templates for the Storefront. Those might require custom styling to look neat, which will be explained in this guide.

## Prerequisites

You won't learn to create a plugin in this guide, head over to our [Plugin base guide](../../plugin-base-guide.md) to create a plugin first, if you don't know how it is done yet. Also knowing and understanding [SCSS](https://sass-lang.com/documentation/) will be quite mandatory to fully understand what is going on here.

Other than having those two requirements, nothing else is necessary for this guide.

## Adding (S)CSS files

By default, Shopware 6 is looking for a `base.scss` file in your plugin. To be precise, this file has to be inside the directory `<plugin root>/src/Resources/app/storefront/src/scss` in order to be properly found and loaded by Shopware.

So just try it out, create a `base.scss` file in the directory mentioned above.

Inside of the `.scss` file, we add some basic styles to see if it's actually working. In this example, the background of the `body` will be changed.

```css
// <plugin root>/src/Resources/app/storefront/src/scss/base.scss
body {
    background: blue;
}
```

### Adding variables

In case you want to use the same color in several places, but want to define it just one time, you can use variables for this.

Create a `abstract/variables.scss` file inside your `<plugin root>/src/Resources/app/storefront/src/scss` directory and define your background color variable.

```css
// <plugin root>/src/Resources/app/storefront/src/scss/abstract/variables.scss
// in variables.scss
$sw-storefront-assets-color-background: blue;
```

Inside your `base.scss` file you can now import your previously defined variables and use them:

```css
// <plugin root>/src/Resources/app/storefront/src/scss/base.scss
@import 'abstract/variables.scss';

body {
    background: $sw-storefront-assets-color-background;
}
```

This comes with the advantage that when you want to change this color for all occurrences, you only have to change this variable once and the hard coded values are not cluttered all over the codebase.

::: info
Refer to the theme guide **[Override Bootstrap Variables in a Theme](../../../themes/styling/override-bootstrap-variables-in-a-theme.md)** if you want to override some of the default Shopware variables.
:::

### Testing its functionality

Now you want to test if your custom styles actually apply to the Storefront. For this, you have to execute the compiling and building of the `.scss` files first. This is done by using the following command:

```bash
shopware-cli project storefront-build
```

```bash
composer run build:js:storefront
```

If you want to see all style changes made by you live, you can also use our Storefront hot-proxy for that case:

```bash
shopware-cli project storefront-watch
```

```bash
composer run watch:storefront
```

Using the hot-proxy command, you will have to access your store with the port `9998`, e.g. `domainToYourEnvironment.in:9998`.

That's it! Open the Storefront and see it turning blue due to your custom styles!

---

---
url: /docs/v6.5/guides/plugins/plugins/storefront/add-custom-styling.md
---

# Add Custom Styling

## Overview

Quite often your plugin will have to change a few templates for the Storefront. Those might require custom styling to look neat, which will be explained in this guide.

## Prerequisites

You won't learn to create a plugin in this guide, head over to our [Plugin base guide](../plugin-base-guide) to create a plugin first, if you don't know how it is done yet. Also knowing and understanding [SCSS](https://sass-lang.com/documentation) will be quite mandatory to fully understand what is going on here.

Other than having those two requirements, nothing else is necessary for this guide.

## Adding (S)CSS files

By default, Shopware 6 is looking for a `base.scss` file in your plugin. To be precise, this file has to be inside the directory `<plugin root>/src/Resources/app/storefront/src/scss` in order to be properly found and loaded by Shopware.

So just try it out, create a `base.scss` file in the directory mentioned above.

Inside of the `.scss` file, we add some basic styles to see if it's actually working. In this example, the background of the `body` will be changed.

```css
// <plugin root>/src/Resources/app/storefront/src/scss/base.scss
body {
    background: blue;
}
```

### Adding variables

In case you want to use the same color in several places, but want to define it just one time, you can use variables for this.

Create a `abstract/variables.scss` file inside your `<plugin root>/src/Resources/app/storefront/src/scss` directory and define your background color variable.

```css
// <plugin root>/src/Resources/app/storefront/src/scss/abstract/variables.scss
// in variables.scss
$sw-storefront-assets-color-background: blue;
```

Inside your `base.scss` file you can now import your previously defined variables and use them:

```css
// <plugin root>/src/Resources/app/storefront/src/scss/base.scss
@import 'abstract/variables.scss';

body {
    background: $sw-storefront-assets-color-background;
}
```

This comes with the advantage that when you want to change this color for all occurrences, you only have to change this variable once and the hard coded values are not cluttered all over the codebase.

::: info
Refer to the theme guide **[Override Bootstrap Variables in a Theme](../../themes/override-bootstrap-variables-in-a-theme.html)** if you want to override some of the default Shopware variables.
:::

### Testing its functionality

Now you want to test if your custom styles actually apply to the Storefront. For this, you have to execute the compiling and building of the `.scss` files first. This is done by using the following command:

```bash
./bin/build-storefront.sh
```

```bash
composer run build:js:storefront
```

If you want to see all style changes made by you live, you can also use our Storefront hot-proxy for that case:

```bash
./bin/watch-storefront.sh
```

```bash
composer run watch:storefront
```

Using the hot-proxy command, you will have to access your store with the port `9998`, e.g. `domainToYourEnvironment.in:9998`.

That's it! Open the Storefront and see it turning blue due to your custom styles!

---

---
url: /docs/v6.6/guides/plugins/plugins/storefront/add-custom-styling.md
---

# Add Custom Styling

## Overview

Quite often your plugin will have to change a few templates for the Storefront. Those might require custom styling to look neat, which will be explained in this guide.

## Prerequisites

You won't learn to create a plugin in this guide, head over to our [Plugin base guide](../plugin-base-guide) to create a plugin first, if you don't know how it is done yet. Also knowing and understanding [SCSS](https://sass-lang.com/documentation) will be quite mandatory to fully understand what is going on here.

Other than having those two requirements, nothing else is necessary for this guide.

## Adding (S)CSS files

By default, Shopware 6 is looking for a `base.scss` file in your plugin. To be precise, this file has to be inside the directory `<plugin root>/src/Resources/app/storefront/src/scss` in order to be properly found and loaded by Shopware.

So just try it out, create a `base.scss` file in the directory mentioned above.

Inside of the `.scss` file, we add some basic styles to see if it's actually working. In this example, the background of the `body` will be changed.

```css
// <plugin root>/src/Resources/app/storefront/src/scss/base.scss
body {
    background: blue;
}
```

### Adding variables

In case you want to use the same color in several places, but want to define it just one time, you can use variables for this.

Create a `abstract/variables.scss` file inside your `<plugin root>/src/Resources/app/storefront/src/scss` directory and define your background color variable.

```css
// <plugin root>/src/Resources/app/storefront/src/scss/abstract/variables.scss
// in variables.scss
$sw-storefront-assets-color-background: blue;
```

Inside your `base.scss` file you can now import your previously defined variables and use them:

```css
// <plugin root>/src/Resources/app/storefront/src/scss/base.scss
@import 'abstract/variables.scss';

body {
    background: $sw-storefront-assets-color-background;
}
```

This comes with the advantage that when you want to change this color for all occurrences, you only have to change this variable once and the hard coded values are not cluttered all over the codebase.

::: info
Refer to the theme guide **[Override Bootstrap Variables in a Theme](../../themes/override-bootstrap-variables-in-a-theme.html)** if you want to override some of the default Shopware variables.
:::

### Testing its functionality

Now you want to test if your custom styles actually apply to the Storefront. For this, you have to execute the compiling and building of the `.scss` files first. This is done by using the following command:

```bash
./bin/build-storefront.sh
```

```bash
composer run build:js:storefront
```

If you want to see all style changes made by you live, you can also use our Storefront hot-proxy for that case:

```bash
./bin/watch-storefront.sh
```

```bash
composer run watch:storefront
```

Using the hot-proxy command, you will have to access your store with the port `9998`, e.g. `domainToYourEnvironment.in:9998`.

That's it! Open the Storefront and see it turning blue due to your custom styles!

---

---
url: /docs/guides/plugins/plugins/storefront/templates/add-custom-twig-function.md
---

# Add Custom Twig Functions

## Overview

Create your own Twig function to call a PHP script from the Twig template during theme development. Pass a string to the `TwigFunction` and return a `MD5-Hash`.

::: info
It is not recommended to use Twig functions in order to retrieve data from the database. In such a case, `DataResolver` could come in handy.
:::

## Prerequisites

In order to create your own Twig function for your plugin, you first need a plugin as base.
Refer to the [Plugin Base Guide](../../plugin-base-guide.md).

In the following sections, we will create and expand all necessary files for the Twig function to work. There are two such files:

* PHP file with the twig functions itself and
* services.php

## Creating the Twig function

For clarity, create a folder named `Twig` within the `src` folder.
Then create a new php file with desired file name within the `Twig` folder.
Refer to the below example :

::: code-group

```php [PLUGIN_ROOT/src/Twig/SwagCreateMd5Hash.php]
<?php declare(strict_types=1);

namespace SwagBasicExample\Twig;

use Shopware\Core\Framework\Context;
use Twig\Extension\AbstractExtension;
use Twig\TwigFunction;

class SwagCreateMd5Hash extends AbstractExtension
{
    public function getFunctions()
    {
        return [
            new TwigFunction('createMd5Hash', [$this, 'createMd5Hash']),
        ];
    }

    public function createMd5Hash(string $str)
    {
        return md5($str);
    }
}
```

:::

Of course, you can do everything in the `createMd5Hash` function that PHP can do, but the `services.php` handles registration of the service in the DI container.

::: code-group

```php [PLUGIN_ROOT/src/Resources/config/services.php]
$services->set(SwagCreateMd5Hash::class)
        ->public()
        ->tag('twig.extension'); // Required
```

:::

Once done, you can access this `TwigFunction` within your plugin.

## Use Twig function in template

The created function is now available in all your templates. Call it like each other function.

```twig
{% sw_extends '@Storefront/storefront/page/content/product-detail.html.twig' %}

{% set md5Hash = createMd5Hash('Shopware is awesome') %}

{% block page_content %}
    {{ parent() }}

    {{ md5Hash }}
{% endblock %}
```

---

---
url: /docs/v6.5/guides/plugins/plugins/storefront/add-custom-twig-function.md
---

# Add Custom Twig Functions

## Overview

Let us consider, for instance, you want to call a PHP script from the twig template during the theme development to create a `MD5-hash`. In such a case, you can create your own twig functions. For this example, pass a string to the `TwigFunction` and return a `MD5-Hash`.

::: info
It is not recommended to use twig functions in order to retrieve data from the database. In such a case, DataResolver could come in handy.
:::

## Prerequisites

In order to create your own twig function for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide).

## Creating twig function

In the following sections, we will create and expand all necessary files for the twig function to work. There are two such files:

* PHP file with the twig functions itself and
* Services.xml

### Creating the twig function

For clarity, create a folder named `Twig` within the `src` folder. Then create a new php file with desired file name within the `Twig` folder. Refer to the below example :

```php
// <plugin root>/src/Twig/SwagCreateMd5Hash.php
<?php declare(strict_types=1);

namespace SwagBasicExample\Twig;

use Shopware\Core\Framework\Context;
use Twig\Extension\AbstractExtension;
use Twig\TwigFunction;

class SwagCreateMd5Hash extends AbstractExtension
{
    public function getFunctions()
    {
        return [
            new TwigFunction('createMd5Hash', [$this, 'createMd5Hash']),
        ];
    }

    public function createMd5Hash(string $str)
    {
        return md5($str);
    }
}
```

Of course, you can do everything in the `createMd5Hash` function that PHP can do, but the `service.xml` handles registration of the service in the DI container.

```html
// <plugin root>/src/Resources/config/services.xml
...
    <services>
        <service id="SwagBasicExample\Twig\SwagCreateMd5Hash" public="true">
            <tag name="twig.extension"/> <!--Required-->
        </service>
    </services>
...
```

Once done, you can access this `TwigFunction` within your plugin.

### Use twig function in template

The created function is now available in all your templates. You can call it like each other function.

```twig
{% sw_extends '@Storefront/storefront/layout/header/header.html.twig' %}

{% set md5Hash = createMd5Hash('Shopware is awesome') %}

{% block layout_header_logo %}
    {{ parent() }}

    {{ md5Hash }}
{% endblock %}
```

---

---
url: /docs/v6.6/guides/plugins/plugins/storefront/add-custom-twig-function.md
---

# Add Custom Twig Functions

## Overview

Let us consider, for instance, you want to call a PHP script from the twig template during the theme development to create a `MD5-hash`. In such a case, you can create your own twig functions. For this example, pass a string to the `TwigFunction` and return a `MD5-Hash`.

::: info
It is not recommended to use twig functions in order to retrieve data from the database. In such a case, DataResolver could come in handy.
:::

## Prerequisites

In order to create your own twig function for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide).

## Creating twig function

In the following sections, we will create and expand all necessary files for the twig function to work. There are two such files:

* PHP file with the twig functions itself and
* Services.xml

### Creating the twig function

For clarity, create a folder named `Twig` within the `src` folder. Then create a new php file with desired file name within the `Twig` folder. Refer to the below example :

```php
// <plugin root>/src/Twig/SwagCreateMd5Hash.php
<?php declare(strict_types=1);

namespace SwagBasicExample\Twig;

use Shopware\Core\Framework\Context;
use Twig\Extension\AbstractExtension;
use Twig\TwigFunction;

class SwagCreateMd5Hash extends AbstractExtension
{
    public function getFunctions()
    {
        return [
            new TwigFunction('createMd5Hash', [$this, 'createMd5Hash']),
        ];
    }

    public function createMd5Hash(string $str)
    {
        return md5($str);
    }
}
```

Of course, you can do everything in the `createMd5Hash` function that PHP can do, but the `service.xml` handles registration of the service in the DI container.

```html
// <plugin root>/src/Resources/config/services.xml
...
    <services>
        <service id="SwagBasicExample\Twig\SwagCreateMd5Hash" public="true">
            <tag name="twig.extension"/> <!--Required-->
        </service>
    </services>
...
```

Once done, you can access this `TwigFunction` within your plugin.

### Use twig function in template

The created function is now available in all your templates. You can call it like each other function.

```twig
{% sw_extends '@Storefront/storefront/layout/header/header.html.twig' %}

{% set md5Hash = createMd5Hash('Shopware is awesome') %}

{% block layout_header_logo %}
    {{ parent() }}

    {{ md5Hash }}
{% endblock %}
```

---

---
url: /docs/guides/plugins/plugins/content/cms/add-data-to-cms-elements.md
---

# Add Data to CMS Element

## Overview

When creating custom CMS elements,
you sometimes want to use more complex data types than text or boolean values, e.g., other entities such as media or products.
In those cases you can implement a custom `CmsElementResolver` to resolve the configuration data.

## Prerequisites

This guide will not explain how to create custom CMS elements in general,
so head over to the official guide about [Adding a custom CMS element](add-cms-element.md) to learn this first.

## Create a data resolver

To manipulate the data of these elements during the loading of the configuration,
we create a `DailyMotionCmsElementResolver` resolver in our plugin.

```php
// <plugin root>/src/DataResolver/DailyMotionCmsElementResolver.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\DataResolver;

use Shopware\Core\Content\Cms\Aggregate\CmsSlot\CmsSlotEntity;
use Shopware\Core\Content\Cms\DataResolver\Element\AbstractCmsElementResolver;
use Shopware\Core\Content\Cms\DataResolver\Element\ElementDataCollection;
use Shopware\Core\Content\Cms\DataResolver\ResolverContext\ResolverContext;
use Shopware\Core\Content\Cms\DataResolver\CriteriaCollection;

class DailyMotionCmsElementResolver extends AbstractCmsElementResolver
{
    public function getType(): string
    {
        return 'dailymotion';
    }

    public function collect(CmsSlotEntity $slot, ResolverContext $resolverContext): ?CriteriaCollection
    {
        return null;
    }

    public function enrich(CmsSlotEntity $slot, ResolverContext $resolverContext, ElementDataCollection $result): void
    {

    }
}
```

Our custom resolver extends from the `AbstractCmsElementResolver` which forces us to implement the methods `getType`, `collect` and `enrich`.

In the previous [example](add-cms-element.md) we added a CMS element with the name `dailymotion`.
As you can see the `getType` method of our custom resolver reflects that name by returning the `dailymotion` string.
This resolver is called every time for an element of the type `dailymotion`.

To register our custom resolver to the service container, we have to register it in the `services.php` file in our plugin.

::: code-group

```php [PLUGIN_ROOT/src/Resources/config/services.php]
<?php declare(strict_types=1);

use Swag\BasicExample\DataResolver\DailyMotionCmsElementResolver;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(DailyMotionCmsElementResolver::class)
        ->tag('shopware.cms.data_resolver');
};
```

:::

### Collect data

The `collect` method prepares the criteria object.
This is useful if, for example, you have a media entity `ID` stored in your configuration.
As in the following example, you can retrieve the configuration for the current CMS element with the call `$slot->getFieldConfig()` and then have access to the individual fields.
In this case we read out `myCustomMedia` field which may contain a mediaId.
If a `mediaId` exists, we create a new `CriteriaCollection` for it.
Now we are able to use this media object later on.
If you want to add data from an [attribute entity](../../framework/data-handling/entities-via-attributes.md), you do not have an explicit definition class.
Instead, you pass `example_entity.definition` as second parameter to the `CriteriaCollection::add()` method.

::: code-group

```php [PLUGIN_ROOT/src/DataResolver/DailyMotionCmsElementResolver.php]
<?php declare(strict_types=1);

// ...
use Shopware\Core\Content\Media\MediaDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
// ...

    public function collect(CmsSlotEntity $slot, ResolverContext $resolverContext): ?CriteriaCollection
    {
        $config = $slot->getFieldConfig();
        $myCustomMedia = $config->get('myCustomMedia');

        if (!$myCustomMedia) {
            return null;
        }

        $mediaId = $myCustomMedia->getValue();

        $criteria = new Criteria([$mediaId]);

        $criteriaCollection = new CriteriaCollection();
        $criteriaCollection->add('media_' . $slot->getUniqueIdentifier(), MediaDefinition::class, $criteria);

        return $criteriaCollection;
    }

// ...
```

:::

### Enrich data

Inside the `enrich` you can perform additional logic on the data that has been resolved.
Like in the `collect` method, we have access to our configuration fields and their values.
Imagine you have stored some information in the element configuration and want to perform an external `Api` call to fetch some additional data.
After that you can add the response information to the current slot data by calling `$slot->setData()`.

This could be a possible solution for that:

::: code-group

```php [PLUGIN_ROOT/src/DataResolver/DailyMotionCmsElementResolver.php]
<?php declare(strict_types=1);

// ...

    public function enrich(CmsSlotEntity $slot, ResolverContext $resolverContext, ElementDataCollection $result): void
    {
        $config = $slot->getFieldConfig();
        $myCustomApiPayload = $config->get('myCustomApiPayload');

        // perform some external api call with the payload `myCustomApiPayload`
        $myCustomAPI = new MyCustomAPI();

        $response = $myCustomAPI->query($myCustomApiPayload);

        if ($response) {
            $slot->setData($response);
        }
    }

// ...
```

:::

### Event-based extensibility

In Shopware’s CMS flow, CMS Elements are not “live bound” to the original entity (e.g. a product).
Instead, during the slot-resolution, resolvers copy values from the entity into internal CMS structs
(for example, `ProductNameCmsElementResolver` takes the string `name` from the `product` entity and writes it into the CMS text element).
Once that copy is done, the storefront rendering reads from the CMS structs — not from the original entity.
Therefore: if you wait until a “page loaded” event (e.g. `ProductPageLoadedEvent`) after the copying happened, changing the underlying entity has no effect on what is displayed in the CMS output.
To make modifications effective (e.g. change product name, adjust a field, override some data), you must intervene before or after the resolver runs — i.e. at a point in the CMS resolution pipeline where the entity is still used for populating the CMS slots.

#### Available Extensions / Events

Shopware exposes three CMS extension classes under `Shopware\Core\Content\Cms\Extension`.
These extension classes follow the common Extension Point Pattern in Shopware and publish named hooks that you can subscribe to (the classes usually expose a `NAME` constant used as the event identifier).
All three extension points are dispatched with lifecycle suffixes such as `.pre` and `.post`, so you will typically see event names like `cms-slots-data.resolve.pre` or `cms-slots-data.resolve.post`.
Using the `.pre` hook lets you intervene before the respective phase runs; `.post` runs after the phase finished.

* `CmsSlotsDataCollectExtension` - This event (`cms-slots-data.collect` + suffix) allows interception of the collection process, where a criteria list is populated using the respective CMS resolver.
  The resulting criteria list is then used to load CMS elements during the CMS page resolution process.

* `CmsSlotsDataEnrichExtension` - This event (`cms-slots-data.enrich` + suffix) allows interception of the enrichment process, during which CMS slots used in a rendered CMS page are populated with data loaded by the respective CMS resolver from the search results.

* `CmsSlotsDataResolveExtension` - This event (`cms-slots-data.resolve` + suffix) enables interception of the resolution process, allowing the collection of CMS slot data and enrichment of slots by their respective CMS resolvers.

#### Example Workflow: Modifying Product Data Before CMS Rendering

Here is a rough outline of how you would implement a subscriber to change some product properties before they end up in CMS elements:

1. Create an event subscriber for the CMS slot resolution event.
2. In the listener method, inspect the `ResolverContext` (or event payload) and check whether the entity is an instance of the type you care about (e.g. `ProductEntity`).
3. Modify the entity (e.g. `$entity->setName(...)`, set custom fields, translations, etc.).
4. Let execution continue, so the built-in resolvers pick up your modified entity and fill CMS elements accordingly.
5. Test frontend — changes should be visible.

#### PHP example (simplified)

```PHP
<?php declare(strict_types=1);

namespace Swag\BasicExample\Subscriber;

// ...

class CmsPreResolveSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            'cms-slots-data.resolve.pre' => 'onCmsSlotsResolvePre',
        ];
    }

    public function onCmsSlotsResolvePre(CmsSlotsDataResolveExtension $event): void
    {
        $resolverContext = $event->getResolverContext();
        $entity = $resolverContext->getEntity();

        if ($entity instanceof ProductEntity) {
            // modify e.g. the name
            $entity->setName('New custom name');
            // optionally modify other fields
        }
    }
}

// ...
```

---

---
url: /docs/v6.5/guides/plugins/plugins/content/cms/add-data-to-cms-elements.md
---

# Add Data to CMS Element

## Overview

When creating custom CMS elements, you sometimes want to use more complex data types than text or boolean values, e.g. other entities such as media or products. In those cases you can implement a custom `CmsElementResolver` to resolve the configuration data.

## Prerequisites

This guide will not explain how to create custom CMS elements in general, so head over to the official guide about [Adding a custom CMS element](add-cms-element) to learn this first.

## Create a data resolver

To manipulate the data of these elements during the loading of the configuration, we create a `DailyMotionCmsElementResolver` resolver in our plugin.

```php
// <plugin root>/src/DataResolver/DailyMotionCmsElementResolver.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\DataResolver;

use Shopware\Core\Content\Cms\Aggregate\CmsSlot\CmsSlotEntity;
use Shopware\Core\Content\Cms\DataResolver\Element\AbstractCmsElementResolver;
use Shopware\Core\Content\Cms\DataResolver\Element\ElementDataCollection;
use Shopware\Core\Content\Cms\DataResolver\ResolverContext\ResolverContext;
use Shopware\Core\Content\Cms\DataResolver\CriteriaCollection;

class DailyMotionCmsElementResolver extends AbstractCmsElementResolver
{
    public function getType(): string
    {
        return 'dailymotion';
    }

    public function collect(CmsSlotEntity $slot, ResolverContext $resolverContext): ?CriteriaCollection
    {
        return null;
    }

    public function enrich(CmsSlotEntity $slot, ResolverContext $resolverContext, ElementDataCollection $result): void
    {

    }
}
```

Our custom resolver extends from the `AbstractCmsElementResolver` which forces us to implement the methods `getType`, `collect` and `enrich`.

In the previous [example](add-cms-element) we added a cms element with the name `dailymotion`. As you can see the `getType` method of our custom resolver reflects that name by returning the `dailymotion` string. This resolver is called every time for an element of the type `dailymotion`.

To register our custom resolver to the service container we have to register it in the `services.xml` file in our plugin.

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\DataResolver\DailyMotionCmsElementResolver">
            <tag name="shopware.cms.data_resolver" />
        </service>
    </services>
</container>
```

### Collect data

The `collect` method prepares the criteria object. This is useful if, for example, you have a media entity `ID` stored in your configuration. As in the following example, you can retrieve the configuration for the current cms element with the call `$slot->getFieldConfig()` and then have access to the individual fields. In this case we read out `myCustomMedia` field which may contain a mediaId. If a `mediaId` exists, we create a new `CriteriaCollection` for it. Now we are able to use this media-object later on.

```php
// <plugin root>/src/DataResolver/DailyMotionCmsElementResolver.php
<?php declare(strict_types=1);

// ...
use Shopware\Core\Content\Media\MediaDefinition;
use Shopware\Core\Content\Media\MediaEntity;
// ...

    public function collect(CmsSlotEntity $slot, ResolverContext $resolverContext): ?CriteriaCollection
    {
        $config = $slot->getFieldConfig();
        $myCustomMedia = $config->get('myCustomMedia');

        if (!$myCustomMedia) {
            return null;
        }

        $mediaId = $myCustomMedia->getValue();

        $criteria = new Criteria([$mediaId]);

        $criteriaCollection = new CriteriaCollection();
        $criteriaCollection->add('media_' . $slot->getUniqueIdentifier(), MediaDefinition::class, $criteria);

        return $criteriaCollection;
    }

// ...
```

### Enrich data

Inside the `enrich` you can perform additional logic on the data that has been resolved. Like in the `collect` method, we have access to our configuration fields and their values. Imagine you have stored some information in the element configuration and want to perform an external `Api` call to fetch some additional data. After that you can add the response information to the current slot data by calling `$slot->setData()`.

This could be a possible solution for that:

```php
// <plugin root>/src/DataResolver/DailyMotionCmsElementResolver.php
<?php declare(strict_types=1);
// ...

    public function enrich(CmsSlotEntity $slot, ResolverContext $resolverContext, ElementDataCollection $result): void
    {
        $config = $slot->getFieldConfig();
        $myCustomApiPayload = $config->get('myCustomApiPayload');

        // perform some external api call with the payload `myCustomApiPayload`
        $myCustomAPI = new MyCustomAPI();

        $response = $myCustomAPI->query($myCustomApiPayload);

        if ($response) {
            $slot->setData($response);
        }
    }

// ...
```

---

---
url: /docs/v6.6/guides/plugins/plugins/content/cms/add-data-to-cms-elements.md
---

# Add Data to CMS Element

## Overview

When creating custom CMS elements, you sometimes want to use more complex data types than text or boolean values, e.g. other entities such as media or products. In those cases you can implement a custom `CmsElementResolver` to resolve the configuration data.

## Prerequisites

This guide will not explain how to create custom CMS elements in general, so head over to the official guide about [Adding a custom CMS element](add-cms-element) to learn this first.

## Create a data resolver

To manipulate the data of these elements during the loading of the configuration, we create a `DailyMotionCmsElementResolver` resolver in our plugin.

```php
// <plugin root>/src/DataResolver/DailyMotionCmsElementResolver.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\DataResolver;

use Shopware\Core\Content\Cms\Aggregate\CmsSlot\CmsSlotEntity;
use Shopware\Core\Content\Cms\DataResolver\Element\AbstractCmsElementResolver;
use Shopware\Core\Content\Cms\DataResolver\Element\ElementDataCollection;
use Shopware\Core\Content\Cms\DataResolver\ResolverContext\ResolverContext;
use Shopware\Core\Content\Cms\DataResolver\CriteriaCollection;

class DailyMotionCmsElementResolver extends AbstractCmsElementResolver
{
    public function getType(): string
    {
        return 'dailymotion';
    }

    public function collect(CmsSlotEntity $slot, ResolverContext $resolverContext): ?CriteriaCollection
    {
        return null;
    }

    public function enrich(CmsSlotEntity $slot, ResolverContext $resolverContext, ElementDataCollection $result): void
    {

    }
}
```

Our custom resolver extends from the `AbstractCmsElementResolver` which forces us to implement the methods `getType`, `collect` and `enrich`.

In the previous [example](add-cms-element) we added a cms element with the name `dailymotion`. As you can see the `getType` method of our custom resolver reflects that name by returning the `dailymotion` string. This resolver is called every time for an element of the type `dailymotion`.

To register our custom resolver to the service container we have to register it in the `services.xml` file in our plugin.

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\DataResolver\DailyMotionCmsElementResolver">
            <tag name="shopware.cms.data_resolver" />
        </service>
    </services>
</container>
```

### Collect data

The `collect` method prepares the criteria object. This is useful if, for example, you have a media entity `ID` stored in your configuration. As in the following example, you can retrieve the configuration for the current cms element with the call `$slot->getFieldConfig()` and then have access to the individual fields. In this case we read out `myCustomMedia` field which may contain a mediaId. If a `mediaId` exists, we create a new `CriteriaCollection` for it. Now we are able to use this media-object later on.

```php
// <plugin root>/src/DataResolver/DailyMotionCmsElementResolver.php
<?php declare(strict_types=1);

// ...
use Shopware\Core\Content\Media\MediaDefinition;
use Shopware\Core\Content\Media\MediaEntity;
// ...

    public function collect(CmsSlotEntity $slot, ResolverContext $resolverContext): ?CriteriaCollection
    {
        $config = $slot->getFieldConfig();
        $myCustomMedia = $config->get('myCustomMedia');

        if (!$myCustomMedia) {
            return null;
        }

        $mediaId = $myCustomMedia->getValue();

        $criteria = new Criteria([$mediaId]);

        $criteriaCollection = new CriteriaCollection();
        $criteriaCollection->add('media_' . $slot->getUniqueIdentifier(), MediaDefinition::class, $criteria);

        return $criteriaCollection;
    }

// ...
```

### Enrich data

Inside the `enrich` you can perform additional logic on the data that has been resolved. Like in the `collect` method, we have access to our configuration fields and their values. Imagine you have stored some information in the element configuration and want to perform an external `Api` call to fetch some additional data. After that you can add the response information to the current slot data by calling `$slot->setData()`.

This could be a possible solution for that:

```php
// <plugin root>/src/DataResolver/DailyMotionCmsElementResolver.php
<?php declare(strict_types=1);
// ...

    public function enrich(CmsSlotEntity $slot, ResolverContext $resolverContext, ElementDataCollection $result): void
    {
        $config = $slot->getFieldConfig();
        $myCustomApiPayload = $config->get('myCustomApiPayload');

        // perform some external api call with the payload `myCustomApiPayload`
        $myCustomAPI = new MyCustomAPI();

        $response = $myCustomAPI->query($myCustomApiPayload);

        if ($response) {
            $slot->setData($response);
        }
    }

// ...
```

---

---
url: /docs/guides/plugins/plugins/content/mail/add-data-to-mails.md
---

# Add Data to Mails

## Overview

The mail templates in Shopware have access to a given set of data, e.g. the customer data, the order data, etc. Sometimes you want add your custom entity to that data set though, so you can use this data in your mail templates as well.

This guide will teach you how to add new data to the mail templates using your plugin.

## Prerequisites

This guide is built upon our [plugin base guide](../../plugin-base-guide), whose namespace is going to be used in the examples of this guide. However, you can use those examples with any plugin, you'll just have to adjust the namespace and the directory the files are located in.

Furthermore, you should know how to [decorate a service](../../services/adjusting-service.md).

## Adding data via decorator

To add new data to the mail templates, decorate the [MailService](https://github.com/shopware/shopware/blob/trunk/src/Core/Content/Mail/Service/MailService.php).

To be precise, you have to extend the `send` method, whose last parameter is the `$templateData`, that we want to enrich.

So let's do that, here's an example of a decorated mail service:

::: code-group

```php [PLUGIN_ROOT/src/Service/AddDataToMails.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Content\Mail\Service\AbstractMailService;
use Shopware\Core\Framework\Context;
use Symfony\Component\Mime\Email;

class AddDataToMails extends AbstractMailService
{
    /**
     * @var AbstractMailService
     */
    private AbstractMailService $mailService;

    public function __construct(AbstractMailService $mailService)
    {
        $this->mailService = $mailService;
    }

    public function getDecorated(): AbstractMailService
    {
        return $this->mailService;
    }

    public function send(array $data, Context $context, array $templateData = []): ?Email
    {
        $templateData['myCustomData'] = 'Example data';

        return $this->mailService->send($data, $context, $templateData);
    }
}
```

:::

If you don't recognise the decoration pattern used here, make sure to have a look at our guide about [decorations](../../services/adjusting-service.md).

As always, we're passing in the original `MailService` as a constructor parameter, so we can return it in the `getDecorated` method, as well as use the original `send` method after having adjusted the `$templateData`.

In this example, we're adding `myCustomData` to the `$templateData`, so that one should be available then.

If we add {{ myCustomData }} to any mail template, it should then print "Example data". You can use any kind of data here, e.g. an array of data.

### Register your decorator

Of course you still have to register the decoration to the service container. Beware of the `decorates` attribute of our service.

Here's the respective example `services.php`:

::: code-group

```php [PLUGIN_ROOT/src/Resources/config/services.php]
<?php declare(strict_types=1);

use Shopware\Core\Content\Mail\Service\MailService;
use Swag\BasicExample\Service\AddDataToMails;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(AddDataToMails::class)
        ->decorate(MailService::class)
        ->args([
            service('.inner'),
        ]);
};
```

:::

## Adding data via subscriber

In many cases, adding mail data via an event subscriber is a suitable solution. This way, you avoid the overhead of decorating the mail service. Simply create an event subscriber and listen to the `MailBeforeValidateEvent` event. There, you can safely add template or mail data.
Here is a small example:

::: code-group

```php [PLUGIN_ROOT/src/Subscriber/MyMailSubscriber.php]
<?php

declare(strict_types=1);

namespace Swag\BasicExample\Subscriber;

use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Shopware\Core\Content\MailTemplate\Service\Event\MailBeforeValidateEvent;

class MyMailSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            MailBeforeValidateEvent::class => 'beforeMailValidate',
        ];
    }

    public function beforeMailValidate(
        MailBeforeValidateEvent $event
    ): void {
        $context = $event->getContext();
        $data = $event->getData(); // Get mail data
        $templateData = $event->getTemplateData(); // Get mail template data

        $event->addTemplateData('key', 'value'); // Example of adding data to the mail template
    }
}
```

### Register the event subscriber

Register the subscriber to the service container.

Here's the respective example `services.php`:

::: code-group

```php [PLUGIN_ROOT/src/Resources/config/services.php]
<?php declare(strict_types=1);

use Swag\BasicExample\Subscriber\MyMailSubscriber;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(MyMailSubscriber::class)
        ->tag('kernel.event_subscriber');
};
```

:::

---

---
url: /docs/v6.5/guides/plugins/plugins/content/mail/add-data-to-mails.md
---

# Add Data to Mails

## Overview

The mail templates in Shopware have access to a given set of data, e.g. the customer data, the order data, etc. Sometimes you want add your custom entity to that data set though, so you can use this data in your mail templates as well.

This guide will teach you how to add new data to the mail templates using your plugin.

## Prerequisites

This guide is built upon our [plugin base guide](../../plugin-base-guide), whose namespace is going to be used in the examples of this guide. However, you can use those examples with any plugin, you'll just have to adjust the namespace and the directory the files are located in.

Furthermore, you should know how to [decorate a service](../../plugin-fundamentals/adjusting-service).

## Adding data via decorator

In order to add new data to the mail templates, you'll have to decorate the [MailService](https://github.com/shopware/shopware/blob/trunk/src/Core/Content/Mail/Service/MailService.php).

To be precise, you have to extend the `send` method, whose last parameter is the `$templateData`, that we want to enrich.

So let's do that, here's an example of a decorated mail service:

```php
// <plugin root>/src/Service/AddDataToMails.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Content\Mail\Service\AbstractMailService;
use Shopware\Core\Framework\Context;
use Symfony\Component\Mime\Email;

class AddDataToMails extends AbstractMailService
{
    /**
     * @var AbstractMailService
     */
    private AbstractMailService $mailService;

    public function __construct(AbstractMailService $mailService)
    {
        $this->mailService = $mailService;
    }

    public function getDecorated(): AbstractMailService
    {
        return $this->mailService;
    }

    public function send(array $data, Context $context, array $templateData = []): ?Email
    {
        $templateData['myCustomData'] = 'Example data';

        return $this->mailService->send($data, $context, $templateData);
    }
}
```

If you don't recognise the decoration pattern used here, make sure to have a look at our guide about [decorations](../../plugin-fundamentals/adjusting-service).

As always, we're passing in the original `MailService` as a constructor parameter, so we can return it in the `getDecorated` method, as well as use the original `send` method after having adjusted the `$templateData`.

In this example, we're adding `myCustomData` to the `$templateData`, so that one should be available then.

If we add `{{ myCustomData }}` to any mail template, it should then print "Example data". You can use any kind of data here, e.g. an array of data.

### Register your decorator

Of course you still have to register the decoration to the service container. Beware of the `decorates` attribute of our service.

Here's the respective example `services.xml`:

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Service\AddDataToMails" decorates="Shopware\Core\Content\Mail\Service\MailService">
            <argument type="service" id="Swag\BasicExample\Service\AddDataToMails.inner" />
        </service>
    </services>
</container>
```

---

---
url: /docs/v6.6/guides/plugins/plugins/content/mail/add-data-to-mails.md
---

# Add Data to Mails

## Overview

The mail templates in Shopware have access to a given set of data, e.g. the customer data, the order data, etc. Sometimes you want add your custom entity to that data set though, so you can use this data in your mail templates as well.

This guide will teach you how to add new data to the mail templates using your plugin.

## Prerequisites

This guide is built upon our [plugin base guide](../../plugin-base-guide), whose namespace is going to be used in the examples of this guide. However, you can use those examples with any plugin, you'll just have to adjust the namespace and the directory the files are located in.

Furthermore, you should know how to [decorate a service](../../plugin-fundamentals/adjusting-service).

## Adding data via decorator

In order to add new data to the mail templates, you'll have to decorate the [MailService](https://github.com/shopware/shopware/blob/trunk/src/Core/Content/Mail/Service/MailService.php).

To be precise, you have to extend the `send` method, whose last parameter is the `$templateData`, that we want to enrich.

So let's do that, here's an example of a decorated mail service:

```php
// <plugin root>/src/Service/AddDataToMails.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Content\Mail\Service\AbstractMailService;
use Shopware\Core\Framework\Context;
use Symfony\Component\Mime\Email;

class AddDataToMails extends AbstractMailService
{
    /**
     * @var AbstractMailService
     */
    private AbstractMailService $mailService;

    public function __construct(AbstractMailService $mailService)
    {
        $this->mailService = $mailService;
    }

    public function getDecorated(): AbstractMailService
    {
        return $this->mailService;
    }

    public function send(array $data, Context $context, array $templateData = []): ?Email
    {
        $templateData['myCustomData'] = 'Example data';

        return $this->mailService->send($data, $context, $templateData);
    }
}
```

If you don't recognise the decoration pattern used here, make sure to have a look at our guide about [decorations](../../plugin-fundamentals/adjusting-service).

As always, we're passing in the original `MailService` as a constructor parameter, so we can return it in the `getDecorated` method, as well as use the original `send` method after having adjusted the `$templateData`.

In this example, we're adding `myCustomData` to the `$templateData`, so that one should be available then.

If we add `{{ myCustomData }}` to any mail template, it should then print "Example data". You can use any kind of data here, e.g. an array of data.

### Register your decorator

Of course you still have to register the decoration to the service container. Beware of the `decorates` attribute of our service.

Here's the respective example `services.xml`:

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Service\AddDataToMails" decorates="Shopware\Core\Content\Mail\Service\MailService">
            <argument type="service" id="Swag\BasicExample\Service\AddDataToMails.inner" />
        </service>
    </services>
</container>
```

---

---
url: >-
  /docs/guides/plugins/plugins/storefront/controllers/add-data-to-storefront-page.md
---

# Add Data to Storefront Page

## Overview

Pages or pagelets are the objects that get handed to the templates and provide all necessary information for the template to render.

If you make template changes you probably want to display some data that is currently not available in the page.
In this case you will have to listen on the page loaded event and then load the additional data and add it to the page object.
This guide will show you how to achieve this, by adding the total number of active products to the footer pagelet and displaying them in the Storefront.

## Prerequisites

This guide is built upon our [Plugin base guide](../../plugin-base-guide.md), so keep that in mind.

Also the following knowledge is necessary, even though some of them are covered here as well:

* Knowing how to [listen to events by using a subscriber](../../framework/event/listening-to-events.md)
* Knowing how to [customize storefront templates](../templates/customize-templates.md)
* Knowing how to [read data using our data abstraction layer](../../framework/data-handling/reading-data.md)
* Knowing how to [add a store-api route](../../framework/store-api/add-store-api-route.md)

## Adding data to the Storefront

The workflow you need here was already described in the overview:

1. Figure out which page you want to change
2. Register to the event that this page is firing
3. Add a store-api route for your needed data
4. Add data to the page via the event
5. Display this data in the Storefront

### Subscribe to an event

So first of all, you need to know which page or pagelet you actually want to extend.
In this example, we're going to extend the [FooterPagelet](https://github.com/shopware/shopware/blob/trunk/src/Storefront/Pagelet/Footer/FooterPagelet.php).
All pages or pagelets throw `Loaded` events and this is the right event to subscribe to if you want to add data to the page or pagelet.
In our case we want to add data to the `FooterPagelet` so we need to subscribe to the `FooterPageletLoadedEvent`.

```php
// SwagBasicExample/src/Service/AddDataToPage.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Storefront\Pagelet\Footer\FooterPageletLoadedEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class AddDataToPage implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            FooterPageletLoadedEvent::class => 'addActiveProductCount'
        ];
    }

    public function addActiveProductCount(FooterPageletLoadedEvent $event): void
    {

    }
}
```

The next thing we need to do is register our subscriber in the DI-Container and tag it as an event subscriber:

```php
// Resources/config/services.php
$services->set(\Swag\BasicExample\Service\AddDataToPage::class)
    ->tag('kernel.event_subscriber');
```

### Adding data to the page

Now that we have registered our Subscriber to the right event, we first need to fetch the additional data we need and then add it as an extension to the pagelet.

Since we are in a `Pagelet`-event, the DAL should not be called directly to fetch data.
Instead, we should check whether a suitable `store-api` route exists.

If we only needed specific product data, we could use the `ProductListRoute`.
However, this does not satisfy our use case.
While the `ProductListRoute` could provide this data, it would return far more information than necessary.

Therefore, we will create a new `store-api` route tailored to our needs.

First you should read our guide for [adding store-api routes](../../framework/store-api/add-store-api-route.md).

Our new Route should look like this:

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\SalesChannel;

use Shopware\Core\PlatformRequest;
use Shopware\Core\Framework\Routing\StoreApiRouteScope;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Symfony\Component\Routing\Attribute\Route;

#[Route(defaults: [PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [StoreApiRouteScope::ID]])]
abstract class AbstractProductCountRoute
{
    abstract public function getDecorated(): AbstractProductCountRoute;

    abstract public function load(Criteria $criteria, SalesChannelContext $context): ProductCountRouteResponse;
}
```

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\SalesChannel;

use Shopware\Core\PlatformRequest;
use Shopware\Core\Framework\Routing\StoreApiRouteScope;
use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Aggregation\Metric\CountAggregation;
use Shopware\Core\Framework\DataAbstractionLayer\Search\AggregationResult\Metric\CountResult;
use Shopware\Core\Framework\Plugin\Exception\DecorationPatternException;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Filter\EqualsFilter;
use Symfony\Component\Routing\Attribute\Route;

#[Route(defaults: [PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [StoreApiRouteScope::ID]])]
class ProductCountRoute extends AbstractProductCountRoute
{
    protected EntityRepository $productRepository;

    public function __construct(EntityRepository $productRepository)
    {
        $this->productRepository = $productRepository;
    }

    public function getDecorated(): AbstractProductCountRoute
    {
        throw new DecorationPatternException(self::class);
    }

    #[Route(
        path: '/store-api/get-active-product-count',
        name: 'store-api.product-count.get',
        methods: ['GET', 'POST'],
        defaults: ['_entity' => 'product']
    )]
    public function load(Criteria $criteria, SalesChannelContext $context): ProductCountRouteResponse
    {
        $criteria = new Criteria();
        $criteria->addFilter(new EqualsFilter('product.active', true));
        $criteria->addAggregation(new CountAggregation('productCount', 'product.id'));

        /** @var CountResult $productCountResult */
        $productCountResult = $this->productRepository
            ->aggregate($criteria, $context->getContext())
            ->get('productCount');

        return new ProductCountRouteResponse($productCountResult);
    }
}
```

### Register route class

```php
<?php declare(strict_types=1);

use Swag\BasicExample\Core\Content\Example\SalesChannel\ProductCountRoute;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(ProductCountRoute::class)
        ->args([service('product.repository')]);
};
```

The routes.php according to our guide for [adding store-api routes](../../framework/store-api/add-store-api-route.md) should look like this.

```php
// <plugin root>/src/Resources/config/routes.php
<?php declare(strict_types=1);

use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return static function (RoutingConfigurator $routes): void {
    $routes->import('../../Core/**/*Route.php', 'attribute');
};
```

### ProductCountRouteResponse

The RouteResponse according to our guide for [adding store-api routes](../../framework/store-api/add-store-api-route.md) should look like this

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\SalesChannel;

use Shopware\Core\Framework\DataAbstractionLayer\Search\AggregationResult\Metric\CountResult;
use Shopware\Core\System\SalesChannel\StoreApiResponse;

/**
 * @extends StoreApiResponse<CountResult>
 */
class ProductCountRouteResponse extends StoreApiResponse
{
    public function __construct(CountResult $countResult)
    {
        parent::__construct($countResult);
    }

    public function getProductCount(): CountResult
    {
        return $this->object;
    }
}
```

So you should know and understand the first few lines if you have read our guide about [Reading data](../../framework/data-handling/reading-data.md) first.
Make sure to also understand the usage of aggregations, since this is what is done here.
The only main difference you might notice is, that we're using the `aggregate()` method instead of the `search()` method.
This will not actually search for any products and return the whole products dataset, but rather just the aggregated data, nothing else.

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Content\Product\SalesChannel\ProductCountRoute;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Storefront\Pagelet\Footer\FooterPageletLoadedEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class AddDataToPage implements EventSubscriberInterface
{
    private ProductCountRoute $productCountRoute;

    public function __construct(ProductCountRoute $productCountRoute)
    {
        $this->productCountRoute = $productCountRoute;
    }

    public static function getSubscribedEvents(): array
    {
        return [
            FooterPageletLoadedEvent::class => 'addActiveProductCount'
        ];
    }

    public function addActiveProductCount(FooterPageletLoadedEvent $event): void
    {
        $productCountResponse = $this->productCountRoute->load(new Criteria(), $event->getSalesChannelContext());

        $event->getPagelet()->addExtension('product_count', $productCountResponse->getProductCount());
    }
}
```

The first line should be nothing new as it is only the call for the store-api route, we created.
Completely new should only be the last line: `$event->getPagelet()->addExtension('product_count', $productCountResult);`

Basically what you're doing here, is to fetch the actual pagelet instance from the event and add the data to the template.
This data will then be available via the name `product_count`, but we'll get to that in the next section.

Now you only have to adjust your service definition to inject the productCountRoute:

```php
<?php declare(strict_types=1);

use Swag\BasicExample\Core\Content\Example\SalesChannel\ProductCountRoute;
use Swag\BasicExample\Service\AddDataToPage;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(ProductCountRoute::class)
        ->public()
        ->args([service('product.repository')]);

    $services->set(AddDataToPage::class)
        ->args([service(ProductCountRoute::class)])
        ->tag('kernel.event_subscriber');
};
```

### Displaying the data in the Storefront

To display the additional data we need to override the footer template and render the data.
Refer to the respective section of this guide for detailed information on how to [extend templates and override blocks](../templates/customize-templates.md).

For our case we extend the footer template and add a new column to the navigation block:

```twig
// Resources/views/storefront/layout/footer/footer.html.twig
{% sw_extends '@Storefront/storefront/layout/footer/footer.html.twig' %}

{% block layout_footer_navigation_columns %}
    {{ parent() }}

    {% if footer.extensions.product_count %}
        <div class="col-md-4 footer-column">
            <p>This shop offers you {{ footer.extensions.product_count.count }} products</p>
        </div>
    {% endif %}
{% endblock %}
```

Note the usage of the variable here. You're accessing the footer object, in which you can now find the path `extensions.product_count.count`.

---

---
url: /docs/v6.5/guides/plugins/plugins/storefront/add-data-to-storefront-page.md
---

# Add Data to Storefront Page

## Overview

Pages or pagelets are the objects that get handed to the templates and provide all necessary information for the template to render.

If you make template changes you probably want to display some data that is currently not available in the page.
In this case you will have to listen on the page loaded event and then load the additional data and add it to the page object.
This guide will show you how to achieve this, by adding the total number of active products to the footer pagelet and displaying them in the Storefront.

## Prerequisites

This guide is built upon our [Plugin base guide](../plugin-base-guide), so keep that in mind.

Also the following knowledge is necessary, even though some of them are covered here as well:

* Knowing how to [listen to events by using a subscriber](../plugin-fundamentals/listening-to-events)
* Knowing how to [customize storefront templates](customize-templates)
* Knowing how to [read data using our data abstraction layer](../framework/data-handling/reading-data)
* Knowing how to [add a store-api route](../framework/store-api/add-store-api-route)

## Adding data to the Storefront

The workflow you need here was already described in the overview:

1. Figure out which page you want to change
2. Register to the event that this page is firing
3. Add a store-api route for your needed data
4. Add data to the page via the event
5. Display this data in the Storefront

### Subscribe to an event

So first of all, you need to know which page or pagelet you actually want to extend.
In this example, we're going to extend the [FooterPagelet](https://github.com/shopware/shopware/blob/trunk/src/Storefront/Pagelet/Footer/FooterPagelet.php).
All pages or pagelets throw `Loaded` events and this is the right event to subscribe to if you want to add data to the page or pagelet.
In our case we want to add data to the `FooterPagelet` so we need to subscribe to the `FooterPageletLoadedEvent`.

```php
// SwagBasicExample/src/Service/AddDataToPage.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Storefront\Pagelet\Footer\FooterPageletLoadedEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class AddDataToPage implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            FooterPageletLoadedEvent::class => 'addActiveProductCount'
        ];
    }

    public function addActiveProductCount(FooterPageletLoadedEvent $event): void
    {

    }
}
```

The next thing we need to do is register our subscriber in the DI-Container and tag it as an event subscriber:

```xml
// Resources/config/services.xml
<?xml version="1.0" ?>
<service id="Swag\BasicExample\Service\AddDataToPage" >
    <tag name="kernel.event_subscriber" />
</service>
```

### Adding data to the page

Now that we have registered our Subscriber to the right event, we first need to fetch the additional data we need and then add it as an extension to the pagelet.

Because we are in an event of a Pagelet we should not directly call the DAL to fetch the data. Instead we should check if there is a proper store-api route to fetch our data.
If we just wanted to add specific products data we could use the ProductListRoute. But we want to fetch data that is currently not returned in a performant way with the store-api.
The ProductListRoute could return the data but it would return way to much data for our purpose. Because of that we will add a new store-api route for our data.

First you should read our guide for [adding store-api routes](../framework/store-api/add-store-api-route).

Our new Route should look like this:

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\SalesChannel;

use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Symfony\Component\Routing\Annotation\Route;

#[Route(defaults: ['_routeScope' => ['store-api']])]
abstract class AbstractProductCountRoute
{
    abstract public function getDecorated(): AbstractProductCountRoute;

    abstract public function load(Criteria $criteria, SalesChannelContext $context): ProductCountRouteResponse;
}
```

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\SalesChannel;

use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Aggregation\Metric\CountAggregation;
use Shopware\Core\Framework\DataAbstractionLayer\Search\AggregationResult\Metric\CountResult;
use Shopware\Core\Framework\Plugin\Exception\DecorationPatternException;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Filter\EqualsFilter;
use Symfony\Component\Routing\Annotation\Route;

#[Route(defaults: ['_routeScope' => ['store-api']])]
class ProductCountRoute extends AbstractProductCountRoute
{
    protected EntityRepository $productRepository;

    public function __construct(EntityRepository $productRepository)
    {
        $this->productRepository = $productRepository;
    }

    public function getDecorated(): AbstractProductCountRoute
    {
        throw new DecorationPatternException(self::class);
    }

     #[Route(path: '/store-api/get-active-product-count', name: 'store-api.product-count.get', methods: ['GET', 'POST'], defaults: ['_entity' => 'product'])]
    public function load(Criteria $criteria, SalesChannelContext $context): ProductCountRouteResponse
    {
        $criteria = new Criteria();
        $criteria->addFilter(new EqualsFilter('product.active', true));
        $criteria->addAggregation(new CountAggregation('productCount', 'product.id'));

        /** @var CountResult $productCountResult */
        $productCountResult = $this->productRepository
            ->aggregate($criteria, $context->getContext())
            ->get('productCount');
            
        return new ProductCountRouteResponse($productCountResult);
    }
}
```

### Register route class

```xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Core\Content\Example\SalesChannel\ProductCountRoute" >
            <argument type="service" id="product.repository"/>
        </service>
    </services>
</container>
```

The routes.xml according to our guide for [adding store-api routes](../framework/store-api/add-store-api-route) should look like this.

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<routes xmlns="http://symfony.com/schema/routing"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://symfony.com/schema/routing
        https://symfony.com/schema/routing/routing-1.0.xsd">

    <import resource="../../Core/**/*Route.php" type="annotation" />
</routes>
```

### ProductCountRouteResponse

The RouteResponse according to our guide for [adding store-api routes](../framework/store-api/add-store-api-route) should look like this

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\SalesChannel;

use Shopware\Core\Framework\DataAbstractionLayer\Search\AggregationResult\Metric\CountResult;
use Shopware\Core\System\SalesChannel\StoreApiResponse;

/**
 * Class CountResult
 * @property CountResult $object
 */
class ProductCountRouteResponse extends StoreApiResponse
{
    public function __construct(CountResult $countResult)
    {
        parent::__construct($countResult);
    }

    public function getProductCount(): CountResult
    {
        return $this->object;
    }
}
```

So you should know and understand the first few lines if you have read our guide about [Reading data](../framework/data-handling/reading-data) first.
Make sure to also understand the usage of aggregations, since this is what is done here.
The only main difference you might notice is, that we're using the `aggregate()` method instead of the `search()` method.
This will not actually search for any products and return the whole products dataset, but rather just the aggregated data, nothing else.

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Content\Product\SalesChannel\ProductCountRoute;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Storefront\Pagelet\Footer\FooterPageletLoadedEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class AddDataToPage implements EventSubscriberInterface
{
    private ProductCountRoute $productCountRoute;

    public function __construct(ProductCountRoute $productCountRoute)
    {
        $this->productCountRoute = $productCountRoute;
    }

    public static function getSubscribedEvents(): array
    {
        return [
            FooterPageletLoadedEvent::class => 'addActiveProductCount'
        ];
    }

    public function addActiveProductCount(FooterPageletLoadedEvent $event): void
    {
        $productCountResponse = $this->productCountRoute->load(new Criteria(), $event->getSalesChannelContext());

        $event->getPagelet()->addExtension('product_count', $productCountResponse->getProductCount());
    }
}
```

The first line should be nothing new as it is only the call for the store-api route, we created.
Completely new should only be the last line: `$event->getPagelet()->addExtension('product_count', $productCountResult);`

Basically what you're doing here, is to fetch the actual pagelet instance from the event and add the data to the template.
This data will then be available via the name `product_count`, but we'll get to that in the next section.

Now you only have to adjust your service definition to inject the productCountRoute:

```xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Core\Content\Example\SalesChannel\ProductCountRoute" public="true">
            <argument type="service" id="product.repository"/>
        </service>
        
        <service id="Swag\BasicExample\Service\AddDataToPage" >
            <argument type="service" id="Swag\BasicExample\Core\Content\Example\SalesChannel\ProductCountRoute"/>
            <tag name="kernel.event_subscriber" />
        </service>
    </services>
</container>
```

### Displaying the data in the Storefront

To display the additional data we need to override the footer template and render the data.
Refer to the respective section of this guide for detailed information on how to [extend templates and override blocks](customize-templates).

For our case we extend the footer template and add a new column to the navigation block:

```twig
// Resources/views/storefront/layout/footer/footer.html.twig
{% sw_extends '@Storefront/storefront/layout/footer/footer.html.twig' %}

{% block layout_footer_navigation_columns %}
    {{ parent() }}

    {% if page.footer.extensions.product_count %}
        <div class="col-md-4 footer-column">
            <p>This shop offers you {{ page.footer.extensions.product_count.count }} products</p>
        </div>
    {% endif %}
{% endblock %}
```

Note the usage of the variable here. You're accessing the footer object, in which you can now find the path `extensions.product_count.count`.

That's it for this guide, you've successfully added data to a Storefront page(let).

---

---
url: /docs/v6.6/guides/plugins/plugins/storefront/add-data-to-storefront-page.md
---

# Add Data to Storefront Page

## Overview

Pages or pagelets are the objects that get handed to the templates and provide all necessary information for the template to render.

If you make template changes you probably want to display some data that is currently not available in the page.
In this case you will have to listen on the page loaded event and then load the additional data and add it to the page object.
This guide will show you how to achieve this, by adding the total number of active products to the footer pagelet and displaying them in the Storefront.

## Prerequisites

This guide is built upon our [Plugin base guide](../plugin-base-guide), so keep that in mind.

Also the following knowledge is necessary, even though some of them are covered here as well:

* Knowing how to [listen to events by using a subscriber](../plugin-fundamentals/listening-to-events)
* Knowing how to [customize storefront templates](customize-templates)
* Knowing how to [read data using our data abstraction layer](../framework/data-handling/reading-data)
* Knowing how to [add a store-api route](../framework/store-api/add-store-api-route)

## Adding data to the Storefront

The workflow you need here was already described in the overview:

1. Figure out which page you want to change
2. Register to the event that this page is firing
3. Add a store-api route for your needed data
4. Add data to the page via the event
5. Display this data in the Storefront

### Subscribe to an event

So first of all, you need to know which page or pagelet you actually want to extend.
In this example, we're going to extend the [FooterPagelet](https://github.com/shopware/shopware/blob/trunk/src/Storefront/Pagelet/Footer/FooterPagelet.php).
All pages or pagelets throw `Loaded` events and this is the right event to subscribe to if you want to add data to the page or pagelet.
In our case we want to add data to the `FooterPagelet` so we need to subscribe to the `FooterPageletLoadedEvent`.

```php
// SwagBasicExample/src/Service/AddDataToPage.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Storefront\Pagelet\Footer\FooterPageletLoadedEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class AddDataToPage implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            FooterPageletLoadedEvent::class => 'addActiveProductCount'
        ];
    }

    public function addActiveProductCount(FooterPageletLoadedEvent $event): void
    {

    }
}
```

The next thing we need to do is register our subscriber in the DI-Container and tag it as an event subscriber:

```xml
// Resources/config/services.xml
<?xml version="1.0" ?>
<service id="Swag\BasicExample\Service\AddDataToPage" >
    <tag name="kernel.event_subscriber" />
</service>
```

### Adding data to the page

Now that we have registered our Subscriber to the right event, we first need to fetch the additional data we need and then add it as an extension to the pagelet.

Because we are in an event of a Pagelet we should not directly call the DAL to fetch the data. Instead we should check if there is a proper store-api route to fetch our data.
If we just wanted to add specific products data we could use the ProductListRoute. But we want to fetch data that is currently not returned in a performant way with the store-api.
The ProductListRoute could return the data but it would return way to much data for our purpose. Because of that we will add a new store-api route for our data.

First you should read our guide for [adding store-api routes](../framework/store-api/add-store-api-route).

Our new Route should look like this:

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\SalesChannel;

use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Symfony\Component\Routing\Attribute\Route;

#[Route(defaults: ['_routeScope' => ['store-api']])]
abstract class AbstractProductCountRoute
{
    abstract public function getDecorated(): AbstractProductCountRoute;

    abstract public function load(Criteria $criteria, SalesChannelContext $context): ProductCountRouteResponse;
}
```

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\SalesChannel;

use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Aggregation\Metric\CountAggregation;
use Shopware\Core\Framework\DataAbstractionLayer\Search\AggregationResult\Metric\CountResult;
use Shopware\Core\Framework\Plugin\Exception\DecorationPatternException;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Filter\EqualsFilter;
use Symfony\Component\Routing\Attribute\Route;

#[Route(defaults: ['_routeScope' => ['store-api']])]
class ProductCountRoute extends AbstractProductCountRoute
{
    protected EntityRepository $productRepository;

    public function __construct(EntityRepository $productRepository)
    {
        $this->productRepository = $productRepository;
    }

    public function getDecorated(): AbstractProductCountRoute
    {
        throw new DecorationPatternException(self::class);
    }

     #[Route(path: '/store-api/get-active-product-count', name: 'store-api.product-count.get', methods: ['GET', 'POST'], defaults: ['_entity' => 'product'])]
    public function load(Criteria $criteria, SalesChannelContext $context): ProductCountRouteResponse
    {
        $criteria = new Criteria();
        $criteria->addFilter(new EqualsFilter('product.active', true));
        $criteria->addAggregation(new CountAggregation('productCount', 'product.id'));

        /** @var CountResult $productCountResult */
        $productCountResult = $this->productRepository
            ->aggregate($criteria, $context->getContext())
            ->get('productCount');
            
        return new ProductCountRouteResponse($productCountResult);
    }
}
```

### Register route class

```xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Core\Content\Example\SalesChannel\ProductCountRoute" >
            <argument type="service" id="product.repository"/>
        </service>
    </services>
</container>
```

The routes.xml according to our guide for [adding store-api routes](../framework/store-api/add-store-api-route) should look like this.

```xml
<?xml version="1.0" encoding="UTF-8" ?>
<routes xmlns="http://symfony.com/schema/routing"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://symfony.com/schema/routing
        https://symfony.com/schema/routing/routing-1.0.xsd">

    <import resource="../../Core/**/*Route.php" type="attribute" />
</routes>
```

### ProductCountRouteResponse

The RouteResponse according to our guide for [adding store-api routes](../framework/store-api/add-store-api-route) should look like this

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\SalesChannel;

use Shopware\Core\Framework\DataAbstractionLayer\Search\AggregationResult\Metric\CountResult;
use Shopware\Core\System\SalesChannel\StoreApiResponse;

/**
 * Class CountResult
 * @property CountResult $object
 */
class ProductCountRouteResponse extends StoreApiResponse
{
    public function __construct(CountResult $countResult)
    {
        parent::__construct($countResult);
    }

    public function getProductCount(): CountResult
    {
        return $this->object;
    }
}
```

So you should know and understand the first few lines if you have read our guide about [Reading data](../framework/data-handling/reading-data) first.
Make sure to also understand the usage of aggregations, since this is what is done here.
The only main difference you might notice is, that we're using the `aggregate()` method instead of the `search()` method.
This will not actually search for any products and return the whole products dataset, but rather just the aggregated data, nothing else.

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Content\Product\SalesChannel\ProductCountRoute;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Storefront\Pagelet\Footer\FooterPageletLoadedEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class AddDataToPage implements EventSubscriberInterface
{
    private ProductCountRoute $productCountRoute;

    public function __construct(ProductCountRoute $productCountRoute)
    {
        $this->productCountRoute = $productCountRoute;
    }

    public static function getSubscribedEvents(): array
    {
        return [
            FooterPageletLoadedEvent::class => 'addActiveProductCount'
        ];
    }

    public function addActiveProductCount(FooterPageletLoadedEvent $event): void
    {
        $productCountResponse = $this->productCountRoute->load(new Criteria(), $event->getSalesChannelContext());

        $event->getPagelet()->addExtension('product_count', $productCountResponse->getProductCount());
    }
}
```

The first line should be nothing new as it is only the call for the store-api route, we created.
Completely new should only be the last line: `$event->getPagelet()->addExtension('product_count', $productCountResult);`

Basically what you're doing here, is to fetch the actual pagelet instance from the event and add the data to the template.
This data will then be available via the name `product_count`, but we'll get to that in the next section.

Now you only have to adjust your service definition to inject the productCountRoute:

```xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Core\Content\Example\SalesChannel\ProductCountRoute" public="true">
            <argument type="service" id="product.repository"/>
        </service>
        
        <service id="Swag\BasicExample\Service\AddDataToPage" >
            <argument type="service" id="Swag\BasicExample\Core\Content\Example\SalesChannel\ProductCountRoute"/>
            <tag name="kernel.event_subscriber" />
        </service>
    </services>
</container>
```

### Displaying the data in the Storefront

To display the additional data we need to override the footer template and render the data.
Refer to the respective section of this guide for detailed information on how to [extend templates and override blocks](customize-templates).

For our case we extend the footer template and add a new column to the navigation block:

```twig
// Resources/views/storefront/layout/footer/footer.html.twig
{% sw_extends '@Storefront/storefront/layout/footer/footer.html.twig' %}

{% block layout_footer_navigation_columns %}
    {{ parent() }}

    {% if page.footer.extensions.product_count %}
        <div class="col-md-4 footer-column">
            <p>This shop offers you {{ page.footer.extensions.product_count.count }} products</p>
        </div>
    {% endif %}
{% endblock %}
```

Note the usage of the variable here. You're accessing the footer object, in which you can now find the path `extensions.product_count.count`.

That's it for this guide, you've successfully added data to a Storefront page(let).

---

---
url: >-
  /docs/resources/references/adr/2022-04-06-add-default-cms-layouts-to-products-and-categories.md
---

# Add default cms pages to products and categories

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-04-06-add-default-cms-layouts-to-products-and-categories.md)
:::

## Context

We want to provide a way to set a default cms page.\
Currently, if a product has no cms page assigned to it, there is a hardcoded fallback twig-template but no default. This does not apply to categories.

Products and categories should both get a default cms page if none is assigned which can be configured by the user.\
The default should only be used when the corresponding entity is marked to use a default.

## Decision

In order to implement this functionality, we needed a way to mark a product or category, which should use the default. This affects the following entities:

* category
  * `category.cmsPageId` will be set to null if the defined default is given,
  * this only applies to cms pages of type `product_list`
* product
  * `product.cmsPageId` will be set to null if the defined default `\Shopware\Core\Defaults::CMS_PRODUCT_DETAIL_PAGE` is given.

In order to set the default cms page, we simply provide the corresponding cms page id in the system config.

* `\Shopware\Core\Content\Product\ProductDefinition::CONFIG_KEY_DEFAULT_CMS_PAGE_PRODUCT` for the default cms page for products
* `\Shopware\Core\Content\Category\CategoryDefinition::CONFIG_KEY_DEFAULT_CMS_PAGE_CATEGORY` for the default cms page for categories of type `product_list`

This fallback is loaded at the `entity.loaded` event of the corresponding entity, where we check if the foreign key is set to NULL and inject the corresponding system config as default.

## Consequences

For all related entities, the `cmsPageId` will be set to `null` if the default is given.
The corresponding cms page id will then be set by subscribers.
Therefore, the cms page id, which is stored in the database, might differ from the cms page id which can be received via repository.\
To use the default functionality, an entity must not have a cms page id assigned to it.

---

---
url: >-
  /docs/v6.5/resources/references/adr/2022-04-06-add-default-cms-layouts-to-products-and-categories.md
---

# Add default cms pages to products and categories

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-04-06-add-default-cms-layouts-to-products-and-categories.md)
:::

## Context

We want to provide a way to set a default cms page.\
Currently, if a product has no cms page assigned to it, there is a hardcoded fallback twig-template but no default. This does not apply to categories.

Products and categories should both get a default cms page if none is assigned which can be configured by the user.\
The default should only be used when the corresponding entity is marked to use a default.

## Decision

In order to implement this functionality, we needed a way to mark a product or category, which should use the default. This affects following entities:

* category
  * `category.cmsPageId` will be set to null if the defined default is given,
  * this only applies to cms pages of type `procut_list`
* product
  * `product.cmsPageId` will be set to null if the defined default `\Shopware\Core\Defaults::CMS_PRODUCT_DETAIL_PAGE` is given.

In order to set the default cms page, we simply provide the corresponding cms page id in the system config.

* `\Shopware\Core\Content\Product\ProductDefinition::CONFIG_KEY_DEFAULT_CMS_PAGE_PRODUCT` for the default cms page for products
* `\Shopware\Core\Content\Category\CategoryDefinition::CONFIG_KEY_DEFAULT_CMS_PAGE_CATEGORY` for the default cms page for categories of type `product_list`

This fallback is loaded at the `entity.loaded` event of the corresponding entity, where we check if the foreign key is set to NULL and inject the corresponding system config as default.

## Consequences

For all related entities, the `cmsPageId` will be set to `null` if the default is given.
The corresponding cms page id will then be set by subscribers.
Therefor the cms page id, which is stored in the database, might differ from the cms page id which can be received via repository.\
To use the default functionality, an entity must not have a cms page id assigned to it.

---

---
url: >-
  /docs/v6.6/resources/references/adr/2022-04-06-add-default-cms-layouts-to-products-and-categories.md
---

# Add default cms pages to products and categories

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-04-06-add-default-cms-layouts-to-products-and-categories.md)
:::

## Context

We want to provide a way to set a default cms page.\
Currently, if a product has no cms page assigned to it, there is a hardcoded fallback twig-template but no default. This does not apply to categories.

Products and categories should both get a default cms page if none is assigned which can be configured by the user.\
The default should only be used when the corresponding entity is marked to use a default.

## Decision

In order to implement this functionality, we needed a way to mark a product or category, which should use the default. This affects following entities:

* category
  * `category.cmsPageId` will be set to null if the defined default is given,
  * this only applies to cms pages of type `product_list`
* product
  * `product.cmsPageId` will be set to null if the defined default `\Shopware\Core\Defaults::CMS_PRODUCT_DETAIL_PAGE` is given.

In order to set the default cms page, we simply provide the corresponding cms page id in the system config.

* `\Shopware\Core\Content\Product\ProductDefinition::CONFIG_KEY_DEFAULT_CMS_PAGE_PRODUCT` for the default cms page for products
* `\Shopware\Core\Content\Category\CategoryDefinition::CONFIG_KEY_DEFAULT_CMS_PAGE_CATEGORY` for the default cms page for categories of type `product_list`

This fallback is loaded at the `entity.loaded` event of the corresponding entity, where we check if the foreign key is set to NULL and inject the corresponding system config as default.

## Consequences

For all related entities, the `cmsPageId` will be set to `null` if the default is given.
The corresponding cms page id will then be set by subscribers.
Therefor the cms page id, which is stored in the database, might differ from the cms page id which can be received via repository.\
To use the default functionality, an entity must not have a cms page id assigned to it.

---

---
url: >-
  /docs/guides/plugins/plugins/storefront/controllers/add-dynamic-content-via-ajax-calls.md
---

# Add Dynamic Content via AJAX Calls

## Overview

This guide will show you how to add dynamic content to your Storefront.
It combines and builds upon the guides about [adding custom JavaScript](../javascript/add-custom-javascript.md) and [adding a custom controller](../controllers/add-custom-controller.md), so you should probably read them first.

## Setting up the Controller

For this guide we will use a very simple controller that returns a timestamp wrapped in the JSON format.

::: info
Refer to this video on **[Creating a JSON controller](https://www.youtube.com/watch?v=VzREUDdpZ3E)** dealing with the creation of a controller that returns JSON data.
Available also on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

As mentioned before this guide builds up upon the [adding a custom controller](../controllers/add-custom-controller.md) guide.
This means that this article will only cover the differences between returning a template and a `JSON` response and making it accessible to `XmlHttpRequests`.

::: code-group

```php [PLUGIN_ROOT/Storefront/Controller/ExampleController.php]
<?php declare(strict_types=1);

namespace SwagBasicExample\Storefront\Controller;

use Shopware\Core\PlatformRequest;
use Shopware\Storefront\Framework\Routing\StorefrontRouteScope;
use Shopware\Storefront\Controller\StorefrontController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\Routing\Attribute\Route;

#[Route(defaults: [PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [StorefrontRouteScope::ID]])]
class ExampleController extends StorefrontController
{
    #[Route(path: '/example', name: 'frontend.example.example', methods: ['GET'], defaults: ['XmlHttpRequest' => 'true'])]
    public function showExample(): JsonResponse
    {
        return new JsonResponse(['timestamp' => (new \DateTime())->format(\DateTimeInterface::W3C)]);
    }
}
```

:::

As you might have seen, this controller isn't too different from the controller used in the article mentioned before.
The route attribute has an added `defaults: ['XmlHttpRequest' => true]` to allow XmlHttpRequest, and it returns a `JsonResponse` instead of a normal `Response`.
Using a `JsonResponse` instead of a normal `Response` causes the data structures passed to it to be automatically turned into a `JSON` string.

The following `services.php` and `routes.php` are identical as in the before mentioned article, but here they are for reference anyway:

::: code-group

```php [PLUGIN_ROOT/src/Resources/config/services.php]
<?php declare(strict_types=1);

use SwagBasicExample\Storefront\Controller\ExampleController;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(ExampleController::class)
        ->public()
        ->call('setContainer', [service('service_container')]);
};
```

```php [PLUGIN_ROOT/src/Resources/config/routes.php]
<?php declare(strict_types=1);

use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return static function (RoutingConfigurator $routes): void {
    $routes->import('../../Storefront/Controller/**/*Controller.php', 'attribute');
};
```

:::

## Preparing the Plugin

Now we have to add a `Storefront Javascript plugin` to display the timestamp we get from our controller.

Again this is built upon the [adding custom JavaScript](../javascript/add-custom-javascript.md) article, so if you don't already know what Storefront `plugins` are, hold on and read it first.

::: code-group

```javascript [PLUGIN_ROOT/src/Resources/app/storefront/src/example-plugin/example-plugin.plugin.js]
const { PluginBaseClass } = window;

export default class AjaxLoadPlugin extends PluginBaseClass {
    init() {
        this.button = this.el.children['ajax-button'];
        this.textdiv = this.el.children['ajax-display'];

        this._registerEvents();
    }

    _registerEvents() {
        // fetch the timestamp, when the button is clicked
        this.button.onclick = this._fetch.bind(this);
    }

    async _fetch() {
        const response = await fetch('/example');
        const data = await response.json();
        this.textdiv.innerHTML = data.timestamp;
    }
}
```

:::

and register it in the `main.js`

::: code-group

```javascript [PLUGIN_ROOT/src/Resources/app/storefront/src/main.js]
import AjaxLoadPlugin from './example-plugin/example-plugin.plugin';

window.PluginManager.register('AjaxLoadPlugin', AjaxLoadPlugin, '[data-ajax-helper]');
```

:::

## Adding the Template

The only thing that is now left is to provide a template for the Storefront plugin to hook into:

::: code-group

```twig [PLUGIN_ROOT/src/Resources/views/storefront/page/content/index.html.twig]
{% sw_extends '@Storefront/storefront/page/content/index.html.twig' %}

{% block cms_content %}
    <div>
        <h1>Swag AJAX Example</h1>

        <div data-ajax-helper>
            <div id="ajax-display"></div>
            <button id="ajax-button">Button</button>
        </div>
    </div>
{% endblock %}
```

:::

## Next steps

The controller we used in this example doesn't do a lot, but this pattern of providing and using data is generally the same.
Even if you use it to fetch data from the database, but in that case, you probably want to learn more about the [DAL](../../../../../concepts/framework/data-abstraction-layer.md).

---

---
url: >-
  /docs/v6.5/guides/plugins/plugins/storefront/add-dynamic-content-via-ajax-calls.md
---

# Add Dynamic Content via AJAX Calls

## Overview

This guide will show you how to add dynamic content to your Storefront. It combines and builds upon the the guides about [adding custom Javascript](add-custom-javascript) and [adding a custom controller](add-custom-controller), so you should probably read them first.

## Setting up the Controller

For this guide we will use a very simple controller that returns a timestamp wrapped in the JSON format.

::: info
Refer to this video on **[Creating a JSON controller](https://www.youtube.com/watch?v=VzREUDdpZ3E)** dealing with the creation of a controller that returns JSON data. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

As mentioned before this guide builds up upon the [adding a custom controller](add-custom-controller) guide. This means that this article will only cover the differences between returning a template and a `JSON` response and making it accessible to `XmlHttpRequests`.

```php
// <plugin base>/Storefront/Controller/ExampleController.php
<?php declare(strict_types=1);

namespace SwagBasicExample\Storefront\Controller;

use Shopware\Storefront\Controller\StorefrontController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\Routing\Annotation\Route;

#[Route(defaults: ['_routeScope' => ['storefront']])]
class ExampleController extends StorefrontController
{
    #[Route(path: '/example', name: 'frontend.example.example', methods: ['GET'], defaults: ['XmlHttpRequest' => 'true'])]
    public function showExample(): JsonResponse
    {
        return new JsonResponse(['timestamp' => (new \DateTime())->format(\DateTimeInterface::W3C)]);
    }
}
```

As you might have seen this controller isn't too different from the controller used in the article mentioned before. The route annotation has an added `defaults={"XmlHttpRequest"=true}` to allow XmlHttpRequest and it returns a `JsonResponse` instead of a normal `Response`. Using a `JsonResponse` instead of a normal `Response` causes the data structures passed to it to be automatically turned into a `JSON` string.

The following `services.xml` and `routes.xml` are identical as in the before mentioned article, but here they are for reference anyways:

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services" 
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="SwagBasicExample\Storefront\Controller\ExampleController" public="true">
            <call method="setContainer">
                <argument type="service" id="service_container"/>
            </call>
            <call method="setTwig">
              <argument type="service" id="twig"/>
            </call>
        </service>
    </services>
</container>
```

```xml
// <plugin root>/src/Resources/config/routes.xml
<?xml version="1.0" encoding="UTF-8" ?>
<routes xmlns="http://symfony.com/schema/routing"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://symfony.com/schema/routing
        https://symfony.com/schema/routing/routing-1.0.xsd">

    <import resource="../../Storefront/Controller/**/*Controller.php" type="annotation" />
</routes>
```

## Preparing the Plugin

Now we have to add a `Storefront Javascript plugin` to display the timestamp we get from our controller.

Again this is built upon the [adding custom Javascript](add-custom-javascript) article, so if you don't already know what Storefront `plugins` are, hold on and read it first.

```javascript
// <plugin root>/src/Resources/app/storefront/src/example-plugin/example-plugin.plugin.js
import HttpClient from 'src/service/http-client.service';
import Plugin from 'src/plugin-system/plugin.class';

export default class AjaxPlugin extends Plugin {
    init() {
        // initialize the HttpClient
        this._client = new HttpClient();

        // get references to the dom elements
        this.button = this.el.children['ajax-button'];
        this.textdiv = this.el.children['ajax-display'];

        // register the events
        this._registerEvents();
    }

    _registerEvents() {
        // fetch the timestamp, when the button is clicked
        this.button.onclick = this._fetch.bind(this);
    }

    _fetch() {
        // make the network request and call the `_setContent` function as a callback
        this._client.get('/example', this._setContent.bind(this), 'application/json', true)
    }

    _setContent(data) {
        // parse the response and set the `textdiv.innerHTML` to the timestamp
        this.textdiv.innerHTML = JSON.parse(data).timestamp;
    }
}
```

## Adding the Template

The only thing that is now left, is to provide a template for the Storefront plugin to hook into:

```twig
// <plugin root>/src/Resources/views/storefront/page/content/index.html.twig
{% sw_extends '@Storefront/storefront/page/content/index.html.twig' %}

{% block cms_content %}
    <div>
        <h1>Swag AJAX Example</h1>

        <div data-ajax-helper>
            <div id="ajax-display"></div>
            <button id="ajax-button">Button</button>
        </div>
    </div>
{% endblock %}
```

## Next steps

The controller we used in this example doesn't do a lot, but this pattern of providing and using data is generally the same. Even if you use it to fetch data form the database, but in that case you probably want to learn more about the [DAL](../../../../concepts/framework/data-abstraction-layer).

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/storefront/add-dynamic-content-via-ajax-calls.md
---

# Add Dynamic Content via AJAX Calls

## Overview

This guide will show you how to add dynamic content to your Storefront. It combines and builds upon the the guides about [adding custom Javascript](add-custom-javascript) and [adding a custom controller](add-custom-controller), so you should probably read them first.

## Setting up the Controller

For this guide we will use a very simple controller that returns a timestamp wrapped in the JSON format.

::: info
Refer to this video on **[Creating a JSON controller](https://www.youtube.com/watch?v=VzREUDdpZ3E)** dealing with the creation of a controller that returns JSON data. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

As mentioned before this guide builds up upon the [adding a custom controller](add-custom-controller) guide. This means that this article will only cover the differences between returning a template and a `JSON` response and making it accessible to `XmlHttpRequests`.

```php
// <plugin base>/Storefront/Controller/ExampleController.php
<?php declare(strict_types=1);

namespace SwagBasicExample\Storefront\Controller;

use Shopware\Storefront\Controller\StorefrontController;
use Symfony\Component\HttpFoundation\JsonResponse;
use Symfony\Component\Routing\Attribute\Route;

#[Route(defaults: ['_routeScope' => ['storefront']])]
class ExampleController extends StorefrontController
{
    #[Route(path: '/example', name: 'frontend.example.example', methods: ['GET'], defaults: ['XmlHttpRequest' => 'true'])]
    public function showExample(): JsonResponse
    {
        return new JsonResponse(['timestamp' => (new \DateTime())->format(\DateTimeInterface::W3C)]);
    }
}
```

As you might have seen this controller isn't too different from the controller used in the article mentioned before. The route attribute has an added `defaults: ['XmlHttpRequest' => true]` to allow XmlHttpRequest and it returns a `JsonResponse` instead of a normal `Response`. Using a `JsonResponse` instead of a normal `Response` causes the data structures passed to it to be automatically turned into a `JSON` string.

The following `services.xml` and `routes.xml` are identical as in the before mentioned article, but here they are for reference anyways:

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services" 
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="SwagBasicExample\Storefront\Controller\ExampleController" public="true">
            <call method="setContainer">
                <argument type="service" id="service_container"/>
            </call>
            <call method="setTwig">
              <argument type="service" id="twig"/>
            </call>
        </service>
    </services>
</container>
```

```xml
// <plugin root>/src/Resources/config/routes.xml
<?xml version="1.0" encoding="UTF-8" ?>
<routes xmlns="http://symfony.com/schema/routing"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://symfony.com/schema/routing
        https://symfony.com/schema/routing/routing-1.0.xsd">

    <import resource="../../Storefront/Controller/**/*Controller.php" type="attribute" />
</routes>
```

## Preparing the Plugin

Now we have to add a `Storefront Javascript plugin` to display the timestamp we get from our controller.

Again this is built upon the [adding custom Javascript](add-custom-javascript) article, so if you don't already know what Storefront `plugins` are, hold on and read it first.

```javascript
// <plugin root>/src/Resources/app/storefront/src/example-plugin/example-plugin.plugin.js
const { PluginBaseClass } = window;

export default class AjaxLoadPlugin extends PluginBaseClass {
    init() {
        this.button = this.el.children['ajax-button'];
        this.textdiv = this.el.children['ajax-display'];

        this._registerEvents();
    }

    _registerEvents() {
        // fetch the timestamp, when the button is clicked
        this.button.onclick = this._fetch.bind(this);
    }

    async _fetch() {
        const response = await fetch('/example');
        const data = await response.json();
        this.textdiv.innerHTML = data.timestamp;
    }
}
```

and register it in the `main.js`

```javascript
import AjaxLoadPlugin from './example-plugin/example-plugin.plugin';

window.PluginManager.register('AjaxLoadPlugin', AjaxLoadPlugin, '[data-ajax-helper]');
```

## Adding the Template

The only thing that is now left, is to provide a template for the Storefront plugin to hook into:

```twig
// <plugin root>/src/Resources/views/storefront/page/content/index.html.twig
{% sw_extends '@Storefront/storefront/page/content/index.html.twig' %}

{% block cms_content %}
    <div>
        <h1>Swag AJAX Example</h1>

        <div data-ajax-helper>
            <div id="ajax-display"></div>
            <button id="ajax-button">Button</button>
        </div>
    </div>
{% endblock %}
```

## Next steps

The controller we used in this example doesn't do a lot, but this pattern of providing and using data is generally the same. Even if you use it to fetch data form the database, but in that case you probably want to learn more about the [DAL](../../../../concepts/framework/data-abstraction-layer).

---

---
url: >-
  /docs/resources/references/adr/2022-01-05-add-feature-flag-support-for-storefront-scss.md
---

# Add feature flag support for Storefront SCSS

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-01-05-add-feature-flag-support-for-storefront-scss.md)
:::

## Context

* There is no possibility to check for feature flags inside the Storefront SCSS.
* Altering the SCSS depending on a feature flag will require workarounds like e.g. "making up" and additional class in the template and use the feature toggle in twig instead.
  * The SCSS of a selector which is hidden behind a feature flag will still be in the compiled CSS.
* It is not easily possible to make breaking changes inside SCSS functions, mixins or variables backward-compatible with the use of feature flags.

## Decision

* Add the possibility to check for feature flags inside SCSS, similar to the twig implementation.
* The feature configuration from `Feature::getAll()` is converted to a SCSS map inside `\Shopware\Storefront\Theme\ThemeCompiler::getFeatureConfigScssMap`.
  * This SCSS map is always added to the SCSS string which gets processed by `\Shopware\Storefront\Theme\ThemeCompiler::compileTheme`.
  * For webpack hot-proxy the `var/config_js_features.json` is used instead.
* The SCSS map looks like this: `$sw-features: ("FEATURE_NEXT_1234": false, "FEATURE_NEXT_1235": true);`
  * See https://sass-lang.com/documentation/values/maps
* A globally available function `feature()` is used to read inside the SCSS map if a desired feature is active.

Example:

```scss
body {
    @if feature('FEATURE_NEXT_1') {
        background-color: #ff0000;
    } @else {
        background-color: #ffcc00;
    }
}
```

## Consequences

The feature dump file `var/config_js_features.json` is now used by the Storefront webpack configuration `src/Storefront/Resources/app/storefront/webpack.config.js`.
When the feature dump cannot be found, all features will be disabled/false inside `webpack.config.js` and hot-proxy SCSS.
A warning is shown in this case with the request to execute `bin/console feature:dump` manually.

---

---
url: >-
  /docs/v6.5/resources/references/adr/2022-01-05-add-feature-flag-support-for-storefront-scss.md
---

# Add feature flag support for Storefront SCSS

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-01-05-add-feature-flag-support-for-storefront-scss.md)
:::

## Context

* There is no possibility to check for feature flags inside the Storefront SCSS.
* Altering the SCSS depending on a feature flag will require workarounds like e.g. "making up" and additional class in the template and use the feature toggle in twig instead.
  * The SCSS of a selector which is hidden behind a feature flag will still be in the compiled CSS.
* It is not easily possible to make breaking changes inside SCSS functions, mixins or variables backward-compatible with the use of feature flags.

## Decision

* Add the possibility to check for feature flags inside SCSS, similar to the twig implementation.
* The feature configuration from `Feature::getAll()` is converted to a SCSS map inside `\Shopware\Storefront\Theme\ThemeCompiler::getFeatureConfigScssMap`.
  * This SCSS map is always added to the SCSS string which gets processed by `\Shopware\Storefront\Theme\ThemeCompiler::compileTheme`.
  * For webpack hot-proxy the `var/config_js_features.json` is used instead.
* The SCSS map looks like this: `$sw-features: ("FEATURE_NEXT_1234": false, "FEATURE_NEXT_1235": true);`
  * See https://sass-lang.com/documentation/values/maps
* A globally available function `feature()` is used to read inside the SCSS map if a desired feature is active.

Example:

```scss
body {
    @if feature('FEATURE_NEXT_1') {
        background-color: #ff0000;
    } @else {
        background-color: #ffcc00;
    }
}
```

## Consequences

The feature dump file `var/config_js_features.json` is now used by the Storefront webpack configuration `src/Storefront/Resources/app/storefront/webpack.config.js`.
When the feature dump cannot be found, all features will be disabled/false inside `webpack.config.js` and hot-proxy SCSS.
A warning is shown in this case with the request to execute `bin/console feature:dump` manually.

---

---
url: >-
  /docs/v6.6/resources/references/adr/2022-01-05-add-feature-flag-support-for-storefront-scss.md
---

# Add feature flag support for Storefront SCSS

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-01-05-add-feature-flag-support-for-storefront-scss.md)
:::

## Context

* There is no possibility to check for feature flags inside the Storefront SCSS.
* Altering the SCSS depending on a feature flag will require workarounds like e.g. "making up" and additional class in the template and use the feature toggle in twig instead.
  * The SCSS of a selector which is hidden behind a feature flag will still be in the compiled CSS.
* It is not easily possible to make breaking changes inside SCSS functions, mixins or variables backward-compatible with the use of feature flags.

## Decision

* Add the possibility to check for feature flags inside SCSS, similar to the twig implementation.
* The feature configuration from `Feature::getAll()` is converted to a SCSS map inside `\Shopware\Storefront\Theme\ThemeCompiler::getFeatureConfigScssMap`.
  * This SCSS map is always added to the SCSS string which gets processed by `\Shopware\Storefront\Theme\ThemeCompiler::compileTheme`.
  * For webpack hot-proxy the `var/config_js_features.json` is used instead.
* The SCSS map looks like this: `$sw-features: ("FEATURE_NEXT_1234": false, "FEATURE_NEXT_1235": true);`
  * See https://sass-lang.com/documentation/values/maps
* A globally available function `feature()` is used to read inside the SCSS map if a desired feature is active.

Example:

```scss
body {
    @if feature('FEATURE_NEXT_1') {
        background-color: #ff0000;
    } @else {
        background-color: #ffcc00;
    }
}
```

## Consequences

The feature dump file `var/config_js_features.json` is now used by the Storefront webpack configuration `src/Storefront/Resources/app/storefront/webpack.config.js`.
When the feature dump cannot be found, all features will be disabled/false inside `webpack.config.js` and hot-proxy SCSS.
A warning is shown in this case with the request to execute `bin/console feature:dump` manually.

---

---
url: >-
  /docs/resources/references/adr/2023-09-06-feature-property-for-experimental-anotation.md
---

# Add Feature property to `@experimental` annotation

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2023-09-06-feature-property-for-experimental-anotation.md)
:::

## Context

Our current development process uses ['Experimental features'](./2023-05-10-experimental-features) to publish features in an early state to gather feedback regarding those features.
During the implementation, developers may encounter challenges related to the effective management of extensive code scattered throughout the platform, particularly in connection with specific experimental features. This codebase fragmentation presents impediments to the tracking, maintenance, and comprehensive understanding of each feature's scope, thereby hindering our development progress.

Potential problems:

* Update `stableVersion` property for Prolonged Experiments
  * When a decision is made to extend an experiment, locating all relevant sections of code for updating the property `stableVersion` in `@experimental` annotation becomes a cumbersome task.
* Deprecation of Killed Features
  * Identifying and marking as deprecated the components associated with a deprecated experimental feature is problematic, particularly when multiple experimental features coexist simultaneously within the platform.
  * The ['Experimental features'](./2023-05-10-experimental-features) stipulates the "Killing Feature" rule, which mandates that a feature must remain within the platform's codebase until the next major version and be appropriately marked as deprecated. However, it is hardly possible to check with current annotation.

In all the above case main problem is detection to which feature belongs experimental code.

## Decision

To address the existing challenges, we propose implementing a refined approach to the use of the `@experimental` annotation.

The key modifications are as follows:

* Mandatory `feature` property:
  * Every `@experimental` annotation will now require a mandatory `feature` property. This property is a string that must contain the name of the associated feature.
* Uniform feature Naming:
  * To enhance code organization and traceability, all sections of code related to a particular feature must use the same feature name in the `feature` property of the `@experimental` annotation.
  * Feature names should follow the conventions.
    * Feature names cannot contain spaces
    * Feature names should be written in `ALL_CAPS`.

## Consequences

### Core

Implementation of the new `feature` property for the `@experimental` annotation will require the following changes:

* To `@experimental` annotation should be added required string property `feature`. The value of the features should follow the conventions.
* There will be implemented a static analysis rule / unit test, that checks that every `@experimental` annotation has the `feature` property.

Examples of usage:
php

```php
/**
 * @experimental stableVersion:v6.6.0 feature:WISHLIST
 */
class testClass()
{
    //...
}
```

js

```js
/**
 * @experimental stableVersion:v6.6.0 feature:WISHLIST
 */
Component.register('sw-new-component', {
    ...
});
```

In twig blocks can be wrapped as being experimental:

```twig
{# @experimental stableVersion:v6.6.0 feature:WISHLIST #}
{% block awesome_new_feature %}
   ...
{% endblock %}
```

In addition to that, we can also mark the whole template as experimental:

```twig
{# @experimental stableVersion:v6.6.0 feature:WISHLIST #}
{% sw_extends '@Storefront/storefront/page/product-detail/index.html.twig' %}
```

## Combining `@experimental` annotation and `feature flag`

Despite that, the `@experimental` annotation and the `feature flag` are two different concepts.  The `@experimental` annotation is used to mark code as experimental and influential only on BC promises regarding this code, while the `feature flag` is used to control the visibility of the experimental code.
There might be scenarios where introducing a feature flag (akin to a switch) becomes necessary, for example, in integration points. 'Experimental features' ADR doesn't explicitly prohibit this practice and does not regulate it in any way. Simultaneously, it would be beneficial to ensure a clear linkage between the feature flag and the experimental functionality it enables.

To achieve this linkage, we recommend the following:

1. Ensure that the feature flag's name matches the name used in the @experimental annotation's `feature` property.
2. The description field in the feature flag configuration should include the experimental annotation along with all the required properties, namely 'stableVersion' and 'feature'.

Example:

feature.yaml

```yaml
shopware:
  feature:
    flags:
      - name: WISHLIST
        default: false
        major: true
        description: "experimental stableVersion:v6.6.0 feature:WISHLIST"
```

New experimental class

```php
/**
 * @experimental stableVersion:v6.6.0 feature:WISHLIST
 */
class Foo
{
}
```

Connection point

```php
if (Feature.isActive('WISHLIST') {
        $obj = new Foo();
        // New implementation
} else {
        // Old/current implementation
}
```

---

---
url: >-
  /docs/v6.5/resources/references/adr/2023-09-06-feature-property-for-experimental-anotation.md
---

# Add Feature property to `@experimental` annotation

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2023-09-06-feature-property-for-experimental-anotation.md)
:::

## Context

Our current development process uses ['Experimental features'](./2023-05-10-experimental-features) to publish features in an early state to gather feedback regarding those features.
During the implementation, developers may encounter challenges related to the effective management of extensive code scattered throughout the platform, particularly in connection with specific experimental features. This codebase fragmentation presents impediments to the tracking, maintenance, and comprehensive understanding of each feature's scope, thereby hindering our development progress.

Potential problems:

* Update `stableVersion` property for Prolonged Experiments
  * When a decision is made to extend an experiment, locating all relevant sections of code for updating the property `stableVersion` in `@experimental` annotation becomes a cumbersome task.
* Deprecation of Killed Features
  * Identifying and marking as deprecated the components associated with a deprecated experimental feature is problematic, particularly when multiple experimental features coexist simultaneously within the platform.
  * The ['Experimental features'](./2023-05-10-experimental-features) stipulates the "Killing Feature" rule, which mandates that a feature must remain within the platform's codebase until the next major version and be appropriately marked as deprecated. However, it is hardly possible to check with current annotation.

In all the above case main problem is detection to which feature belongs experimental code.

## Decision

To address the existing challenges, we propose implementing a refined approach to the use of the `@experimental` annotation.

The key modifications are as follows:

* Mandatory `feature` property:
  * Every `@experimental` annotation will now require a mandatory `feature` property. This property is a string that must contain the name of the associated feature.
* Uniform feature Naming:
  * To enhance code organization and traceability, all sections of code related to a particular feature must use the same feature name in the `feature` property of the `@experimental` annotation.
  * Feature names should follow the conventions.
    * Feature names cannot contain spaces
    * Feature names should be written in `ALL_CAPS`.

## Consequences

### Core

Implementation of the new `feature` property for the `@experimental` annotation will require the following changes:

* To `@experimental` annotation should be added required string property `feature`. The value of the features should follow the conventions.
* There will be implemented a static analysis rule / unit test, that checks that every `@experimental` annotation has the `feature` property.

Examples of usage:
php

```php
/**
 * @experimental stableVersion:v6.6.0 feature:WISHLIST
 */
class testClass()
{
    //...
}
```

js

```js
/**
 * @experimental stableVersion:v6.6.0 feature:WISHLIST
 */
Component.register('sw-new-component', {
    ...
});
```

In twig blocks can be wrapped as being experimental:

```twig
{# @experimental stableVersion:v6.6.0 feature:WISHLIST #}
{% block awesome_new_feature %}
   ...
{% endblock %}
```

In addition to that, we can also mark the whole template as experimental:

```twig
{# @experimental stableVersion:v6.6.0 feature:WISHLIST #}
{% sw_extends '@Storefront/storefront/page/product-detail/index.html.twig' %}
```

## Combining `@experimental` annotation and `feature flag`

Despite that, the `@experimental` annotation and the `feature flag` are two different concepts.  The `@experimental` annotation is used to mark code as experimental and influential only on BC promises regarding this code, while the `feature flag` is used to control the visibility of the experimental code.
There might be scenarios where introducing a feature flag (akin to a switch) becomes necessary, for example, in integration points. 'Experimental features' ADR doesn't explicitly prohibit this practice and does not regulate it in any way. Simultaneously, it would be beneficial to ensure a clear linkage between the feature flag and the experimental functionality it enables.

To achieve this linkage, we recommend the following:

1. Ensure that the feature flag's name matches the name used in the @experimental annotation's `feature` property.
2. The description field in the feature flag configuration should include the experimental annotation along with all the required properties, namely 'stableVersion' and 'feature'.

Example:

feature.yaml

```yaml
shopware:
  feature:
    flags:
      - name: WISHLIST
        default: false
        major: true
        description: "experimental stableVersion:v6.6.0 feature:WISHLIST"
```

New experimental class

```php
/**
 * @experimental stableVersion:v6.6.0 feature:WISHLIST
 */
class Foo
{
}
```

Connection point

```php
if (Feature.isActive('WISHLIST') {
        $obj = new Foo();
        // New implementation
} else {
        // Old/current implementation
}
```

---

---
url: >-
  /docs/v6.6/resources/references/adr/2023-09-06-feature-property-for-experimental-anotation.md
---

# Add Feature property to `@experimental` annotation

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2023-09-06-feature-property-for-experimental-anotation.md)
:::

## Context

Our current development process uses ['Experimental features'](./2023-05-10-experimental-features) to publish features in an early state to gather feedback regarding those features.
During the implementation, developers may encounter challenges related to the effective management of extensive code scattered throughout the platform, particularly in connection with specific experimental features. This codebase fragmentation presents impediments to the tracking, maintenance, and comprehensive understanding of each feature's scope, thereby hindering our development progress.

Potential problems:

* Update `stableVersion` property for Prolonged Experiments
  * When a decision is made to extend an experiment, locating all relevant sections of code for updating the property `stableVersion` in `@experimental` annotation becomes a cumbersome task.
* Deprecation of Killed Features
  * Identifying and marking as deprecated the components associated with a deprecated experimental feature is problematic, particularly when multiple experimental features coexist simultaneously within the platform.
  * The ['Experimental features'](./2023-05-10-experimental-features) stipulates the "Killing Feature" rule, which mandates that a feature must remain within the platform's codebase until the next major version and be appropriately marked as deprecated. However, it is hardly possible to check with current annotation.

In all the above case main problem is detection to which feature belongs experimental code.

## Decision

To address the existing challenges, we propose implementing a refined approach to the use of the `@experimental` annotation.

The key modifications are as follows:

* Mandatory `feature` property:
  * Every `@experimental` annotation will now require a mandatory `feature` property. This property is a string that must contain the name of the associated feature.
* Uniform feature Naming:
  * To enhance code organization and traceability, all sections of code related to a particular feature must use the same feature name in the `feature` property of the `@experimental` annotation.
  * Feature names should follow the conventions.
    * Feature names cannot contain spaces
    * Feature names should be written in `ALL_CAPS`.

## Consequences

### Core

Implementation of the new `feature` property for the `@experimental` annotation will require the following changes:

* To `@experimental` annotation should be added required string property `feature`. The value of the features should follow the conventions.
* There will be implemented a static analysis rule / unit test, that checks that every `@experimental` annotation has the `feature` property.

Examples of usage:
php

```php
/**
 * @experimental stableVersion:v6.6.0 feature:WISHLIST
 */
class testClass()
{
    //...
}
```

js

```js
/**
 * @experimental stableVersion:v6.6.0 feature:WISHLIST
 */
Component.register('sw-new-component', {
    ...
});
```

In twig blocks can be wrapped as being experimental:

```twig
{# @experimental stableVersion:v6.6.0 feature:WISHLIST #}
{% block awesome_new_feature %}
   ...
{% endblock %}
```

In addition to that, we can also mark the whole template as experimental:

```twig
{# @experimental stableVersion:v6.6.0 feature:WISHLIST #}
{% sw_extends '@Storefront/storefront/page/product-detail/index.html.twig' %}
```

## Combining `@experimental` annotation and `feature flag`

Despite that, the `@experimental` annotation and the `feature flag` are two different concepts.  The `@experimental` annotation is used to mark code as experimental and influential only on BC promises regarding this code, while the `feature flag` is used to control the visibility of the experimental code.
There might be scenarios where introducing a feature flag (akin to a switch) becomes necessary, for example, in integration points. 'Experimental features' ADR doesn't explicitly prohibit this practice and does not regulate it in any way. Simultaneously, it would be beneficial to ensure a clear linkage between the feature flag and the experimental functionality it enables.

To achieve this linkage, we recommend the following:

1. Ensure that the feature flag's name matches the name used in the @experimental annotation's `feature` property.
2. The description field in the feature flag configuration should include the experimental annotation along with all the required properties, namely 'stableVersion' and 'feature'.

Example:

feature.yaml

```yaml
shopware:
  feature:
    flags:
      - name: WISHLIST
        default: false
        major: true
        description: "experimental stableVersion:v6.6.0 feature:WISHLIST"
```

New experimental class

```php
/**
 * @experimental stableVersion:v6.6.0 feature:WISHLIST
 */
class Foo
{
}
```

Connection point

```php
if (Feature.isActive('WISHLIST') {
        $obj = new Foo();
        // New implementation
} else {
        // Old/current implementation
}
```

---

---
url: /docs/v6.5/guides/plugins/plugins/administration/add-filter.md
---

# Add filter

## Overview

In this guide you'll learn, how to create a filter for the Shopware Administration. A filter is just a little helper for formatting text. In this example, we create a filter that converts text into uppercase and adds an underscore at the beginning and end.

## Prerequisites

This guide requires you to already have a basic plugin running. If you don't know how to do this in the first place, have a look at our [Plugin base guide](../plugin-base-guide).

## Creating the filter

First we create a new file in the directory `<plugin root>/src/Resources/app/administration/src/app/filter`. In this case we name our filter `example`, so our file will be named `example.filter.js`.

Here's an example how your filter could look like:

```javascript
// <plugin root>/src/Resources/app/administration/src/app/filter/example.filter.js
const { Filter } = Shopware;

Filter.register('example', (value) => {
    if (!value) {
        return '';
    }

    return `_${value.toLocaleUpperCase()}_`;
});
```

As you can see, it's very simple. We use `Filter` from the `Shopware` object where we can register our filter with the method `register`. The first argument we pass is the name of our filter, which is `example`. The second argument is a function with which we format our text.

If you want to use multiple arguments in your filter function, it could look like this:

```javascript
Filter.register('example', (value, secondValue, thirdValue) => {
    ...
});
```

Last, import the filter into your plugin's `main.js` file.

## Next steps

Now that you know how to create a filter for the Administration, we want to use it in our code. For this head over to our [using filter](using-filter) guide.

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/administration/services-utilities/add-filter.md
---

# Add filter

## Overview

In this guide you'll learn, how to create a filter for the Shopware Administration. A filter is just a little helper for formatting text. In this example, we create a filter that converts text into uppercase and adds an underscore at the beginning and end.

## Prerequisites

This guide requires you to already have a basic plugin running. If you don't know how to do this in the first place, have a look at our [Plugin base guide](../../plugin-base-guide.md).

## Creating the filter

First we create a new file in the directory `<plugin root>/src/Resources/app/administration/src/app/filter`. In this case we name our filter `example`, so our file will be named `example.filter.js`.

Here's an example how your filter could look like:

```javascript
// <plugin root>/src/Resources/app/administration/src/app/filter/example.filter.js
const { Filter } = Shopware;

Filter.register('example', (value) => {
    if (!value) {
        return '';
    }

    return `_${value.toLocaleUpperCase()}_`;
});
```

As you can see, it's very simple. We use `Filter` from the `Shopware` object where we can register our filter with the method `register`. The first argument we pass is the name of our filter, which is `example`. The second argument is a function with which we format our text.

If you want to use multiple arguments in your filter function, it could look like this:

```javascript
Filter.register('example', (value, secondValue, thirdValue) => {
    ...
});
```

Last, import the filter into your plugin's `main.js` file.

## Next steps

Now that you know how to create a filter for the Administration, we want to use it in our code. For this head over to our [using filter](using-filter.md) guide.

---

---
url: /docs/guides/plugins/plugins/administration/services-utilities/add-filter.md
---

# Add Filter

## Overview

This guide covers how to create a filter for the Shopware Administration. A filter is just a little helper for formatting text. In this example, we create a filter that converts text into uppercase and adds an underscore at the beginning and end.

## Prerequisites

You need to already have a basic plugin running. If you don't know how to create a plugin, have a look at our [Plugin base guide](../../plugin-base-guide.md).

## Creating the filter

First we create a new file in the directory `<plugin root>/src/Resources/app/administration/src/app/filter`. In this case we name our filter `example`, so our file will be named `example.filter.js`.

Here's an example how your filter could look like:

```javascript
// <plugin root>/src/Resources/app/administration/src/app/filter/example.filter.js
const { Filter } = Shopware;

Filter.register('example', (value) => {
    if (!value) {
        return '';
    }

    return `_${value.toLocaleUpperCase()}_`;
});
```

As you can see, it's very simple. We use `Filter` from the `Shopware` object where we can register our filter with the method `register`. The first argument we pass is the name of our filter, which is `example`. The second argument is a function with which we format our text.

If you want to use multiple arguments in your filter function, it could look like this:

```javascript
Filter.register('example', (value, secondValue, thirdValue) => {
    ...
});
```

Last, import the filter into your plugin's `main.js` file.

## Next steps

Now that you know how to create a filter for the Administration, we want to use it in our code. For this head over to our [using filter](using-filter.md) guide.

---

---
url: /docs/guides/plugins/plugins/framework/flow/add-flow-builder-action.md
---

# Add Flow Builder Action

## Overview

In this guide, you'll learn how to create custom flow action in Shopware. The flow builder uses actions to perform business tasks. This example will introduce a new custom action called `create tags`.

## Prerequisites

In order to add your own custom flow action for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide.](../../plugin-base-guide.md)

You also should be familiar with the [Dependency Injection container](../../services/dependency-injection.md) as this is used to register your custom flow action and [Listening to events](../../framework/event/listening-to-events.md#creating-your-own-subscriber) to create a subscriber class.

It might be helpful to gather some general understanding about the [concept of Flow Builder](../../../../../concepts/framework/flow-concept.md) as well.

## Existing triggers and actions

You can refer to the [Flow reference](../../../../development/troubleshooting/flow-reference.md) to read triggers and actions detail.

## Create custom flow action

To create a custom flow action, firstly you have to make a plugin and install it. Refer to the [Plugin Base Guide](../../plugin-base-guide.md) to do it. For instance, lets create a plugin named `CreateTagAction`. You must implement both backend (PHP) code and a user interface in the Administration to manage it. Let's start with the PHP part first, which handles the main logic of our action. After that, there will be an example to show your new actions in the Administration.

## Creating flow action in PHP

### Create new Aware interface

First of all, we need to define an aware interface for your own action. I intended to create the `CreateTagAction`, so I need to create a related aware named `TagAware`, will be placed in directory `<plugin root>/src/Core/Framework/Event`. Our new interface has to extend from interfaces `Shopware\Core\Framework\Event\FLowEventAware`:

```php
// <plugin root>/src/Core/Framework/Event/TagAware.php
<?php declare(strict_types=1);
namespace Swag\ExamplePlugin\Core\Framework\Event;
use Shopware\Core\Framework\Event\FlowEventAware;
use Shopware\Core\Framework\Event\IsFlowEventAware;

#[IsFlowEventAware]
interface TagAware extends FlowEventAware
{
    ...

    public const TAG = 'tag';

    public const TAG_ID = 'tagId';

    public function getTag();

    ...
}
```

### Create new action

In this example, we will name it `CreateTagAction`. It will be placed in the directory `<plugin root>/src/Core/Content/Flow/Dispatching/Action`. Below you can find an example implementation:

```php
// <plugin root>/src/Core/Content/Flow/Dispatching/Action/CreateTagAction.php
<?php declare(strict_types=1);

namespace Swag\CreateTagAction\Core\Content\Flow\Dispatching\Action;

use Shopware\Core\Content\Flow\Dispatching\Action\FlowAction;
use Shopware\Core\Content\Flow\Dispatching\StorableFlow;
use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\Uuid\Uuid;
use Swag\CreateTagAction\Core\Framework\Event\TagAware;

class CreateTagAction extends FlowAction
{
    private EntityRepository $tagRepository;

    public function __construct(EntityRepository $tagRepository)
    {
        // you would need this repository to create a tag
        $this->tagRepository = $tagRepository;
    }

    public static function getName(): string
    {
        // your own action name
        return 'action.create.tag';
    }

    public function requirements(): array
    {
        return [TagAware::class];
    }

    public function handleFlow(StorableFlow $flow): void
    {
        // config is the config data when created a flow sequence
        $config = $flow->getConfig();

        // make sure your tags data exists
        if (!\array_key_exists('tags', $config)) {
            return;
        }

        $tags = $config['tags'];

        // just a step to make sure you're dispatching correct action
        if (!$flow->hasStore(TagAware::TAG_ID) || empty($tags)) {
            return;
        }

        // get tag id
        $tagId = $flow->getStore(TagAware::TAG_ID);

        // get tag
        $tag = $flow->getData(TagAware::TAG);

        $tagData = [];
        foreach ($tags as $tag) {
            $tagData[] = [
                'id' => Uuid::randomHex(),
                'name' => $tag,
            ];
        }

        // simply create tags
        $this->tagRepository->create($tagData, $flow->getContext());
    }
}
```

As you can see, several methods are already implemented:

* `__constructor`: This only defines the default expected value. This is overwritten at runtime with the actual value, that the shop owner set in the Administration.
* `getName`: Returns a unique technical name for your action.
* `requirements`: This defines which interfaces the action belongs to.
* `handleFlow`: Use this method to handle your action stuff.
  * Use `$flow->getStore($key)` if you want to get the data from aware interfaces. E.g: `tag_id` in `TagAware`, `customer_id` from `CustomerAware` and so on.
  * Use `$flow->getData($key)` if you want to get the data from original events or additional data. E.g: `tag`, `customer`, `contactFormData` and so on.

You also need to register this action in the container as a service. Make sure to define a tag `flow.action` with `priority: 600` at `<plugin root>/src/Resources/config/services.php`. This tag will ensure that your action is included in the response of the *`/api/_info/flow-actions.json`* API. The priority attribute will determine the order of the action in the API response.

```php
// <plugin root>/src/Resources/config/services.php
$services->set(Swag\CreateTagAction\Core\Content\Flow\Dispatching\Action\CreateTagAction::class)
    ->args([service('tag.repository')])
    ->tag('flow.action', ['priority' => 600, 'key' => 'action.create.tag']);
```

Great, your own action is created completely. Let's go to the next step.

### Define action scope

In this step, you will know how to define your action scope for `CreateTagAction`.
There are three scopes for the `CreateTagAction`:

* Available for all *already Events*.
* Available for only one or multiple *already Events.*
* Available for new event (new event from this plugin).

#### `CreateTagAction` available for all *already Events*

* Just define the empty array in `CreateTagAction::requirements`

```php
    // plugin root>/src/Core/Content/Flow/Dispatching/Action/CreateTagAction.php
    ...

    public function requirements(): array
    {
        return [];
    }

    ...
```

That means when you define the requirements like the code above, all triggers in the flow builder can define the action `CreateTagAction` for the next progress.

![Flow Builder trigger](../../../../../assets/flow-builder-action-available-all-events.png)

Here, the action name is empty as the action name snippet is not yet defined.

#### `CreateTagAction` available for only one or multiple *already Events*

Make the `CreateTagAction` available for all events related to Order and Customer.

```php
    // <plugin root>/src/Core/Content/Flow/Dispatching/Action/CreateTagAction.php
    ...

    public function requirements(): array
    {
        return [OrderAware::class, CustomerAware::class];
    }

    ...
```

#### `CreateTagAction` available for new event

* For this case, you can define a new event and make the `CreateTagAction` available for this event.

* Event must implement the `TagAware`

```php
// <plugin root>/src/Core/Content/Flow/Subscriber/BusinessEventCollectorSubscriber.php
<?php declare(strict_types=1);

namespace Swag\CreateTagAction\Core\Content\Event;

use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\Event\EventData\EntityType;
use Shopware\Core\Framework\Event\EventData\EventDataCollection;
use Shopware\Core\System\Tag\TagDefinition;
use Shopware\Core\System\Tag\TagEntity;
use Swag\CreateTagAction\Core\Framework\Event\TagAware;
use Symfony\Contracts\EventDispatcher\Event;

class BasicExampleEvent extends Event implements TagAware
{
    public const EVENT_NAME = 'example.event';

    private TagEntity $tag;

    private Context $context;

    public function __construct(Context $context, TagEntity $tag)
    {
        $this->tag = $tag;
        $this->context = $context;
    }

    public function getName(): string
    {
        return self::EVENT_NAME;
    }

    public static function getAvailableData(): EventDataCollection
    {
        return (new EventDataCollection())
            ->add('tag', new EntityType(TagDefinition::class));
    }

    public function getContext(): Context
    {
        return $this->context;
    }

    public function getTag(): TagEntity
    {
        return $this->tag;
    }
}
```

* Define the `TagAware` in `CreateTagAction::requirements`

```php
    // <plugin root>/src/Core/Content/Flow/Dispatching/Action/CreateTagAction.php
    ...

    public function requirements(): array
    {
        return [TagAware::class];
    }

    ...
```

* To show the new event in Flow Builder Triggers list

```php
// <plugin root>/src/Core/Content/Subscriber/BusinessEventCollectorSubscriber.php
<?php declare(strict_types=1);
namespace Swag\CreateTagAction\Core\Content\Subscriber;

use Shopware\Core\Framework\Event\BusinessEventCollector;
use Shopware\Core\Framework\Event\BusinessEventCollectorEvent;
use Swag\CreateTagAction\Core\Content\Event\BasicExampleEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class BusinessEventCollectorSubscriber implements EventSubscriberInterface
{
    private BusinessEventCollector $businessEventCollector;

    public function __construct(BusinessEventCollector $businessEventCollector)
    {
        $this->businessEventCollector = $businessEventCollector;
    }

    public static function getSubscribedEvents()
    {
        return [
            BusinessEventCollectorEvent::NAME => 'onAddExampleEvent',
        ];
    }

    public function onAddExampleEvent(BusinessEventCollectorEvent $event): void
    {
        $collection = $event->getCollection();

        $definition = $this->businessEventCollector->define(BasicExampleEvent::class);

        if (!$definition) {
            return;
        }

        $collection->set($definition->getName(), $definition);
    }
}
```

And don't forget to register your subscriber to the container at `<plugin root>/src/Resources/config/services.php`.

```php

$services->set(Swag\CreateTagAction\Core\Content\Subscriber\BusinessEventCollectorSubscriber::class)
    ->args([service(Shopware\Core\Framework\Event\BusinessEventCollector::class)])
    ->tag('kernel.event_subscriber');
```

* Define the Event snippet

```json
// <plugin root>/src/Resources/app/administration/src/module/sw-flow/snippet/en-GB.json
{
  "sw-flow": {
    "triggers": {
      "example": "Example",
      "event": "Event"
    }
  }
}
```

![Flow Builder trigger](../../../../../assets/flow-builder-triggers-list.png)

Well, you have successfully created your custom action in Backend in PHP.

## Add custom action in Administration

After we are done with the PHP code, `action.create.tag` is received from the response of `/api/_info/flow-actions.json`. However, the custom action displays in the action list without label. These further steps in Administration will help you show the action label and add configuration for it.

To see the action list, we select a Trigger, for example \[example\event], from the Trigger drop-down in the Flow tab. After that, we choose option `ACTION (THEN)`. An action component appears with an action list.

![Flow Builder trigger](../../../../../assets/flow-builder-trigger-drop.png)

![Flow Builder action then](../../../../../assets/flow-builder-action-then.png)

![Flow Builder trigger](../../../../../assets/flow-builder-action-no-label.png)

### Step 1: Show action label in action list

First, we need to define information like `constants`, `snippets` to show on the action list. To be consistent with the custom action defined in our PHP code, create an action name called `CREATE_TAG` to represent `action.create.tag`, which gets from the response of `/api/_info/flow-actions.json`.

![Flow Builder action services list](../../../../../assets/flow-builder-action-sevices-list.png)

```JS
// <plugin root>src/Resources/app/administration/src/constant/create-tag-action.constant.js
export const ACTION = Object.freeze({
    CREATE_TAG: 'action.create.tag',
});

export const GROUP = 'customer'

export default {
    ACTION, GROUP
};
```

And then add snippets for labels:

```JS
// src/Resources/app/administration/src/snippet/en-GB.json
{
    "create-tag-action": {
        "titleCreateTag": "Create tag",
        "labelTags": "Tags",
        "placeholderTags": "Enter tags",
        "buttonSaveAction": "Save action",
        "buttonAddAction": "Add action",
        "descriptionTags": "Tags: {tags}"
    }
}
```

Do it as the same with `de-DE.json` file for translation of DE language.

After that, we also need to override the `sw-flow-sequence-action` component in the core:

```JS
// <plugin root>/src/Resources/app/administration/src/extension/sw-flow-sequence-action/index.js
import { ACTION, GROUP } from '../../constant/create-tag-action.constant';

const { Component } = Shopware;

Component.override('sw-flow-sequence-action', {
    computed: {
        // Not necessary if you use an existing group
        // Push the `groups` method in computed if you are defining a new group
        groups() {
            this.actionGroups.unshift(GROUP);

            return this.$super('groups');
        },

        modalName() {
            if (this.selectedAction === ACTION.CREATE_TAG) {
                return 'sw-flow-create-tag-modal';
            }

            return this.$super('modalName');
        },
    },

    methods: {
        getActionDescriptions(sequence) {
            if(sequence.actionName === ACTION.CREATE_TAG){
                return this.getCreateTagDescription(sequence.config)
            }
            return this.$super('getActionDescriptions', sequence)
        },

        getCreateTagDescription(config) {
            const tags = config.tags.join(', ');

            return this.$tc('create-tag-action.descriptionTags', 0, {
                tags
            });
        },

        getActionTitle(actionName) {
            if (actionName === ACTION.CREATE_TAG) {
                return {
                    value: actionName,
                    icon: 'regular-tag',
                    label: this.$tc('create-tag-action.titleCreateTag'),
                    group: GROUP,
                }
            }

            return this.$super('getActionTitle', actionName);
        },
    },
});

```

Do not forget to import the file to the entry file `main.js`:

```JS
// <plugin root>/src/Resources/app/administration/src/main.js
import './extension/sw-flow-sequence-action';
```

**Grouping Actions**

As you can see, we already defined the constant for the group in `create-tag-action.constant.js`

```JS
export const GROUP = 'customer'
```

The new action `action.create.tag` will be shown on the Customer group.

![Choose a Flow Builder Action](../../../../../assets/flow-builder-action-customer-group.png)

It will default on the General group if it is not defined.

Here is a list of group names you should take a look at:

| Group Name | Group Headline |
| :--- | :--- |
| general | General|
| tag | Tag |
| customer | Customer |
| order | Order |

### Step 2: Add configuration for action

If you click the Create tag action, the below error will be shown on the console. That means we're going the right way.

![Choose a Flow Builder Action](../../../../../assets/flow-builder-action-error.png)

Because in `sw-flow-sequence-action`, we expect that the new modal has the name `sw-flow-create-tag-modal`.

```JS
modalName() {
    if (this.selectedAction === ACTION.CREATE_TAG) {
        return 'sw-flow-create-tag-modal';
    }

    return this.$super('modalName');
},
```

To define the modal, just create a new folder `sw-flow-create-tag-modal` in `src/Resources/app/administration/src/component` and create some files following:

#### JavaScript file

```JS
// <plugin root>/src/Resources/app/administration/src/component/sw-flow-create-tag-modal/index.js
import template from './sw-flow-create-tag-modal.html.twig';

const { Data: { Criteria, EntityCollection } } = Shopware;
const { Component, Context } = Shopware;

Component.register('sw-flow-create-tag-modal', {
    template,

    inject: [
        'repositoryFactory',
    ],

    props: {
        sequence: {
            type: Object,
            required: true,
        },
    },

    data() {
        return {
            tagCollection: [],
        };
    },

    computed: {
        tagRepository() {
            return this.repositoryFactory.create('tag');
        },

        tagCriteria() {
            const criteria = new Criteria(1, 25);
            const { config } = this.sequence;
            const tagIds = Object.keys(config.tagIds);
            if (tagIds.length) {
                criteria.addFilter(Criteria.equalsAny('id', tagIds));
            }

            return criteria;
        },
    },

    created() {
        this.createdComponent();
    },

    methods: {
        createdComponent() {
            this.tagCollection = this.createTagCollection();

            const { config } = this.sequence;
            if (this.sequence.id && config?.tagIds) {
                this.getTagCollection();
            }
        },

        getTagCollection() {
            return this.tagRepository.search(this.tagCriteria)
                .then(tags => {
                    this.tagCollection = tags;
                })
                .catch(() => {
                    this.tagCollection = [];
                });
        },

        createTagCollection() {
            return new EntityCollection(
                this.tagRepository.route,
                this.tagRepository.entityName,
                Context.api,
            );
        },

        onClose() {
            this.$emit('modal-close');
        },

        onAddTag(data) {
            this.tagCollection.add(data);
        },

        onRemoveTag(data) {
            this.tagCollection.remove(data);
        },

        getConfig() {
            const tagIds = {};
            this.tagCollection.forEach(tag => {
                Object.assign(tagIds, {
                    [tag.id]: tag.name,
                });
            });

            return {
                tagIds,
            };
        },

        onAddAction() {
            const config = this.getConfig();
            const data = {
                ...this.sequence,
                config,
            };

            this.$emit('process-finish', data);
        },
    },
});
```

#### Twig template file

```twig
// <plugin root>/src/Resources/app/administration/src/component/sw-flow-create-tag-modal/sw-flow-create-tag-modal.html.twig
{% block create_tag_action_modal %}
<sw-modal
    class="create-tag-action-modal"
    :title="$tc('create-tag-action.titleCreateTag')"
    @modal-close="onClose"
>
    {% block create_tag_action_modal_content %}
        <sw-entity-tag-select
            v-model="tagCollection"
            class="sw-flow-create-tag-modal__tags-field"
            required
            :label="$tc('create-tag-action.labelTags')"
            :placeholder="$tc('create-tag-action.placeholderTags')"
            @item-add="onAddTag"
            @item-remove="onRemoveTag"
        />
    {% endblock %}

    {% block create_tag_action_modall_footer %}
        <template #modal-footer>
            {% block create_tag_action_modal_footer_cancel_button %}
                <sw-button
                    class="create-tag-action-modal__cancel-button"
                    size="small"
                    @click="onClose"
                >
                    {{ $tc('global.default.cancel') }}
                </sw-button>
            {% endblock %}

            {% block create_tag_action_modal_footer_save_button %}
                <sw-button
                    class="create-tag-action-modal__save-button"
                    variant="primary"
                    size="small"
                    @click="onAddAction"
                >
                    {{ $tc('create-tag-action.buttonSaveAction') }}
                </sw-button>
            {% endblock %}
        </template>
    {% endblock %}
</sw-modal>
{% endblock %}
```

Please update the file `main.js` like this:

```JS
// <plugin root>/src/Resources/app/administration/src/main.js
import './extension/sw-flow-sequence-action';
import './component/sw-flow-create-tag-modal';
```

Here is the final result

![Flow Builder create tag](../../../../../assets/flow-builder-tag.png)

Click on \[Save action] and we will get the result as below screenshot.

![Flow Builder create tag result](../../../../../assets/flow-builder-tag-result.png)

#### Custom configuration for action without the modal

You don't need a modal for the configuration. It can be added automatically.

Imagine, your action is already in the action list after [the first step](#step-1-show-action-label-in-action-list)

![Choose a Flow Builder Action](../../../../../assets/flow-builder-trigger-action.png)

First, override the `openDynamicModal` method in the plugin to check if the value matches the desired action. Then, call the `onSaveActionSuccess` directly with the configuration. After the check, call `return`.

#### JavaScript

```JS
// <plugin root>/src/Resources/app/administration/src/extension/sw-flow-sequence-action/index.js
const { Component } = Shopware;

Component.register('sw-flow-sequence-action', {
    methods: {
        openDynamicModal(value) {
            if (!value) {
                return;
            }

            const actionName = this.flowBuilderService.getActionName('CREATE_TAG');

            if (value === actionName) {
                this.selectedAction = actionName;
                const config = {
                    tagIds: {
                        'tag_id_1': 'Vip',
                        'tag_id_2': 'New Customer',
                    },
                };

                // Config can be a result from an API.
                this.onSaveActionSuccess({ config });
                return;
            }

            // handle for the rest of actions.
        },
    },
});
```

Now, after you click on the action, the new sequence will automatically be added to the action list like this:

![Flow Builder create tag result](../../../../../assets/flow-builder-tag-result.png)

### Demo

You can view the whole demo for this custom Flow Builder trigger and action below:

![Flow Builder demo](../../../../../assets/flow-builder-demo.gif)

---

---
url: /docs/v6.5/guides/plugins/plugins/storefront/add-javascript-as-script-tag.md
---

# Add JavaScript as script tag

## Overview

You often want to add your JavaScript to your main entry point `<plugin root>/src/Resources/app/storefront/src/main.js` to automatically compile it alongside the Storefront JavaScript.
Please refer to [Add custom Javascript](add-custom-javascript.md) for more information.

However, you might want to add JavaScript as a separate `<script>` tag in the HTML. For example, to load a script from an external CDN.
You will learn how to extend the template to add a `<script>` tag.

## Prerequisites

For this guide, you need a running plugin, Shopware 6 instance, and full access to all files. You also need a brief understanding of how a [template extension](customize-templates.md) works.

## Adding JavaScript as a separate script tag

You can extend the default template that includes the `<head>` section of the page: `src/Storefront/Resources/views/storefront/layout/meta.html.twig`.
While it is possible to add a `<script>` anywhere in the HTML via template extensions, it is recommended to include your script alongside the default scripts by extending the block `layout_head_javascript_hmr_mode`.

```twig
{# <plugin root>/src/Resources/views/storefront/layout/meta.html.twig #}
{% sw_extends '@Storefront/storefront/layout/meta.html.twig' %}

{% block layout_head_javascript_hmr_mode %}
    {# Renders Storefront script: <script src="https://your-shop.example/theme/747e1c6a73cf4d70f5e831b30554dd15/js/all.js?1698139296" defer></script> #}
    {{ parent() }}

    {# Your script #}
    <script src="https://unpkg.com/isotope-layout@3/dist/isotope.pkgd.min.js" defer></script>
{% endblock %}
```

This will render:

```html
<head>
    <!-- Other tags are rendered here... -->

    <script src="https://your-shop.example/theme/747e1c6a73cf4d70f5e831b30554dd15/js/all.js?1698139296" defer></script>
    <script src="https://unpkg.com/isotope-layout@3/dist/isotope.pkgd.min.js" defer></script>
</head>
```

::: danger
If you are extending the block `layout_head_javascript_hmr_mode` to add your script, you must always use the {{ parent() }} function to render the Storefront JavaScript as well.
Otherwise, the core JS functionalities of the Storefront will be overwritten and will stop working. This should only happen when you **explicitly** want this.
:::

### Conditional scripts

Instead of continually rendering your `<script>`, you can also put it behind a condition in Twig.
Then the script will only be rendered when the Twig condition is met.

```twig
{# <plugin root>/src/Resources/views/storefront/layout/meta.html.twig #}
{% sw_extends '@Storefront/storefront/layout/meta.html.twig' %}

{% block layout_head_javascript_hmr_mode %}
    {{ parent() }}

    {# Only add script when condition is met #}
    {% if someCondition %}
        <script src="https://unpkg.com/isotope-layout@3/dist/isotope.pkgd.min.js" defer></script>
    {% endif %}
{% endblock %}
```

### Script order

Should your `<script>` tag come before or after the Storefront core JavaScript?
It depends on whether you need to have access to the code added by your `<script>` within the Storefront JavaScript (added by `<plugin root>/src/Resources/app/storefront/src/main.js`).

* If you **don't** need access within the Storefronts JavaScript, you should add the `<script>` **after** the Storefront JavaScript.
* If you **do need** access, your `<script>` should come **before** the Storefront JavaScript.

::: warning
Please consider that non-async `<script src="#">` that are added before the Storefront JavaScript will postpone its execution.
Too many scripts can have a negative effect on the shop's performance.
:::

### Script loading behavior

Using the `defer` attribute is recommended to tell the browser that the script is meant to be executed after the document has been parsed.
However, if you add a library as `<script>`, please consult the library documentation. Some libraries are supposed to be loaded with `async` attribute.

::: warning
It should be avoided to add external `<script src="#">` without `defer` or `async` because it will block rendering of the site until the script is executed.
This can have a negative effect on the shop's performance.
:::

### Alternative script locations

You can also add a `<script>` near the body using block `base_body_script` in `src/Storefront/Resources/views/storefront/base.html.twig`.
It is possible to add `<script>` at every location the Twig blocks offer.

::: info
Alternative script locations should only be used when there is a technical reason.
For example, when the documentation of an external library recommends a specific script location inside the HTML.
:::

---

---
url: /docs/v6.6/guides/plugins/plugins/storefront/add-javascript-as-script-tag.md
---

# Add JavaScript as script tag

## Overview

You often want to add your JavaScript to your main entry point `<plugin root>/src/Resources/app/storefront/src/main.js` to automatically compile it alongside the Storefront JavaScript.
Please refer to [Add custom Javascript](add-custom-javascript.md) for more information.

However, you might want to add JavaScript as a separate `<script>` tag in the HTML. For example, to load a script from an external CDN.
You will learn how to extend the template to add a `<script>` tag.

## Prerequisites

For this guide, you need a running plugin, Shopware 6 instance, and full access to all files. You also need a brief understanding of how a [template extension](customize-templates.md) works.

## Adding JavaScript as a separate script tag

You can extend the default template that includes the `<head>` section of the page: `src/Storefront/Resources/views/storefront/layout/meta.html.twig`.
While it is possible to add a `<script>` anywhere in the HTML via template extensions, it is recommended to include your script alongside the default scripts by extending the block `layout_head_javascript_hmr_mode`.

```twig
{# <plugin root>/src/Resources/views/storefront/layout/meta.html.twig #}
{% sw_extends '@Storefront/storefront/layout/meta.html.twig' %}

{% block layout_head_javascript_hmr_mode %}
    {# Renders Storefront script: <script src="https://your-shop.example/theme/747e1c6a73cf4d70f5e831b30554dd15/js/all.js?1698139296" defer></script> #}
    {{ parent() }}

    {# Your script #}
    <script src="https://unpkg.com/isotope-layout@3/dist/isotope.pkgd.min.js" defer></script>
{% endblock %}
```

This will render:

```html
<head>
    <!-- Other tags are rendered here... -->

    <script src="https://your-shop.example/theme/747e1c6a73cf4d70f5e831b30554dd15/js/all.js?1698139296" defer></script>
    <script src="https://unpkg.com/isotope-layout@3/dist/isotope.pkgd.min.js" defer></script>
</head>
```

::: danger
If you are extending the block `layout_head_javascript_hmr_mode` to add your script, you must always use the {{ parent() }} function to render the Storefront JavaScript as well.
Otherwise, the core JS functionalities of the Storefront will be overwritten and will stop working. This should only happen when you **explicitly** want this.
:::

### Conditional scripts

Instead of continually rendering your `<script>`, you can also put it behind a condition in Twig.
Then the script will only be rendered when the Twig condition is met.

```twig
{# <plugin root>/src/Resources/views/storefront/layout/meta.html.twig #}
{% sw_extends '@Storefront/storefront/layout/meta.html.twig' %}

{% block layout_head_javascript_hmr_mode %}
    {{ parent() }}

    {# Only add script when condition is met #}
    {% if someCondition %}
        <script src="https://unpkg.com/isotope-layout@3/dist/isotope.pkgd.min.js" defer></script>
    {% endif %}
{% endblock %}
```

### Script order

Should your `<script>` tag come before or after the Storefront core JavaScript?
It depends on whether you need to have access to the code added by your `<script>` within the Storefront JavaScript (added by `<plugin root>/src/Resources/app/storefront/src/main.js`).

* If you **don't** need access within the Storefronts JavaScript, you should add the `<script>` **after** the Storefront JavaScript.
* If you **do need** access, your `<script>` should come **before** the Storefront JavaScript.

::: warning
Please consider that non-async `<script src="#">` that are added before the Storefront JavaScript will postpone its execution.
Too many scripts can have a negative effect on the shop's performance.
:::

### Script loading behavior

Using the `defer` attribute is recommended to tell the browser that the script is meant to be executed after the document has been parsed.
However, if you add a library as `<script>`, please consult the library documentation. Some libraries are supposed to be loaded with `async` attribute.

::: warning
It should be avoided to add external `<script src="#">` without `defer` or `async` because it will block rendering of the site until the script is executed.
This can have a negative effect on the shop's performance.
:::

### Alternative script locations

You can also add a `<script>` near the body using block `base_body_script` in `src/Storefront/Resources/views/storefront/base.html.twig`.
It is possible to add `<script>` at every location the Twig blocks offer.

::: info
Alternative script locations should only be used when there is a technical reason.
For example, when the documentation of an external library recommends a specific script location inside the HTML.
:::

---

---
url: >-
  /docs/guides/plugins/plugins/storefront/javascript/add-javascript-as-script-tag.md
---

# Add JavaScript as Script Tag

## Overview

You often want to add your JavaScript to your main entry point `<plugin root>/src/Resources/app/storefront/src/main.js` to automatically compile it alongside the Storefront JavaScript.
Refer to the [Add custom JavaScript](./add-custom-javascript.md) guide for more information.

However, you might want to add JavaScript as a separate `<script>` tag in the HTML. For example, to load a script from an external CDN.
You will learn how to extend the template to add a `<script>` tag.

## Prerequisites

For this guide, you need a running plugin, Shopware 6 instance, and full access to all files. You also need a brief understanding of how a [template extension](../templates/customize-templates.md) works.

## Adding JavaScript as a separate script tag

You can extend the default template that includes the `<head>` section of the page: `src/Storefront/Resources/views/storefront/layout/meta.html.twig`.
While it is possible to add a `<script>` anywhere in the HTML via template extensions, it is recommended to include your script alongside the default scripts by extending the block `layout_head_javascript_hmr_mode`.

```twig
{# <plugin root>/src/Resources/views/storefront/layout/meta.html.twig #}
{% sw_extends '@Storefront/storefront/layout/meta.html.twig' %}

{% block layout_head_javascript_hmr_mode %}
    {# Renders Storefront script: <script src="https://your-shop.example/theme/747e1c6a73cf4d70f5e831b30554dd15/js/all.js?1698139296" defer></script> #}
    {{ parent() }}

    {# Your script #}
    <script src="https://unpkg.com/isotope-layout@3/dist/isotope.pkgd.min.js" defer></script>
{% endblock %}
```

This will render:

```html
<head>
    <!-- Other tags are rendered here... -->

    <script src="https://your-shop.example/theme/747e1c6a73cf4d70f5e831b30554dd15/js/all.js?1698139296" defer></script>
    <script src="https://unpkg.com/isotope-layout@3/dist/isotope.pkgd.min.js" defer></script>
</head>
```

::: danger
If you are extending the block `layout_head_javascript_hmr_mode` to add your script, you must always use the {{ parent() }} function to render the Storefront JavaScript as well.
Otherwise, the core JS functionalities of the Storefront will be overwritten and will stop working. This should only happen when you **explicitly** want this.
:::

### Conditional scripts

Instead of continually rendering your `<script>`, you can also put it behind a condition in Twig.
Then the script will only be rendered when the Twig condition is met.

```twig
{# <plugin root>/src/Resources/views/storefront/layout/meta.html.twig #}
{% sw_extends '@Storefront/storefront/layout/meta.html.twig' %}

{% block layout_head_javascript_hmr_mode %}
    {{ parent() }}

    {# Only add script when condition is met #}
    {% if someCondition %}
        <script src="https://unpkg.com/isotope-layout@3/dist/isotope.pkgd.min.js" defer></script>
    {% endif %}
{% endblock %}
```

### Script order

Should your `<script>` tag come before or after the Storefront core JavaScript?
It depends on whether you need to have access to the code added by your `<script>` within the Storefront JavaScript (added by `<plugin root>/src/Resources/app/storefront/src/main.js`).

* If you **don't** need access within the Storefronts JavaScript, you should add the `<script>` **after** the Storefront JavaScript.
* If you **do need** access, your `<script>` should come **before** the Storefront JavaScript.

::: warning
Please consider that non-async `<script src="#">` that are added before the Storefront JavaScript will postpone its execution.
Too many scripts can have a negative effect on the shop's performance.
:::

### Script loading behavior

Using the `defer` attribute is recommended to tell the browser that the script is meant to be executed after the document has been parsed.
However, if you add a library as `<script>`, please consult the library documentation. Some libraries are supposed to be loaded with `async` attribute.

::: warning
It should be avoided to add external `<script src="#">` without `defer` or `async` because it will block rendering of the site until the script is executed.
This can have a negative effect on the shop's performance.
:::

### Alternative script locations

You can also add a `<script>` near the body using block `base_body_script` in `src/Storefront/Resources/views/storefront/base.html.twig`.
It is possible to add `<script>` at every location the Twig blocks offer.

::: info
Alternative script locations should only be used when there is a technical reason.
For example, when the documentation of an external library recommends a specific script location inside the HTML.
:::

---

---
url: >-
  /docs/resources/references/adr/2024-06-12-add-jest-runner-with-disabled-compat-mode.md
---

# Add jest runner with disabled compat mode

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2024-06-12-add-jest-runner-with-disabled-compat-mode.md)
:::

## Context

Currently, our component tests in Jest are running with enabled compat mode. To remove the compat mode for each
component, we need to add a new Jest runner with disabled compat mode to make sure that the tests are running without compat mode.

## Decision

I added a new runner command in the NPM scripts to run the Jest tests without compat mode. The new runner command is
`unit:disabled-compat` and `unit-watch:disabled-compat`. Also, the composer commands are added to run the tests. These commands are `admin:unit:disabled-compat` and `admin:unit-watch:disabled-compat`. These commands are using the environment variable `DISABLE_JEST_COMPAT_MODE` to disable the compat mode.

For the pipeline, I added a new stage to run the Jest tests without compat mode. The stage is `Jest (Administration with disabled compat mode)`.

To mark a test file working without the compat mode you need to add a comment with the `@group` tag. The tag is `@group disabledCompat`.

Example:

```javascript
/**
 * @package admin
 * @group disabledCompat
 */

import { mount } from '@vue/test-utils';

async function createWrapper() {
...
```

With this tag, the test file is running without compat mode. To make a component working for both modes, you can use the
compatUtils helper function from Vue compat:

```javascript
// Example
import { compatUtils } from '@vue/compat';

...

if (compatUtils.isCompatEnabled('INSTANCE_LISTENERS')) {
    return this.$listeners;
}

return {};

...
```

Important: the test still runs also with compat mode activated in parallel.

## Consequences

* Fixing the components and tests to run also without compat mode. This has to be done by removing the compat mode for each component.
* Marking fixed tests with `@group disabledCompat` to run without compat mode.
* When everything is fixed, we can remove the compat mode from the Jest configuration.

---

---
url: >-
  /docs/v6.6/resources/references/adr/2024-06-12-add-jest-runner-with-disabled-compat-mode.md
---

# Add jest runner with disabled compat mode

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2024-06-12-add-jest-runner-with-disabled-compat-mode.md)
:::

## Context

Currently, our component tests in Jest are running with enabled compat mode. To remove the compat mode for each
component, we need to add a new Jest runner with disabled compat mode to make sure that the tests are running without compat mode.

## Decision

I added a new runner command in the NPM scripts to run the Jest tests without compat mode. The new runner command is
`unit:disabled-compat` and `unit-watch:disabled-compat`. Also, the composer commands are added to run the tests. These commands are `admin:unit:disabled-compat` and `admin:unit-watch:disabled-compat`. These commands are using the environment variable `DISABLE_JEST_COMPAT_MODE` to disable the compat mode.

For the pipeline, I added a new stage to run the Jest tests without compat mode. The stage is `Jest (Administration with disabled compat mode)`.

To mark a test file working without the compat mode you need to add a comment with the `@group` tag. The tag is `@group disabledCompat`.

Example:

```javascript
/**
 * @package admin
 * @group disabledCompat
 */

import { mount } from '@vue/test-utils';

async function createWrapper() {
...
```

With this tag, the test file is running without compat mode. To make a component working for both modes, you can use the
compatUtils helper function from Vue compat:

```javascript
// Example
import { compatUtils } from '@vue/compat';

...

if (compatUtils.isCompatEnabled('INSTANCE_LISTENERS')) {
    return this.$listeners;
}

return {};

...
```

Important: the test still runs also with compat mode activated in parallel.

## Consequences

* Fixing the components and tests to run also without compat mode. This has to be done by removing the compat mode for each component.
* Marking fixed tests with `@group disabledCompat` to run without compat mode.
* When everything is fixed, we can remove the compat mode from the Jest configuration.

---

---
url: /docs/guides/plugins/plugins/content/mail/add-mail-template.md
---

# Add Mail Templates

## Overview

You can add new mail templates to Shopware by using the Administration. However, you might want to ship a mail template with your plugin, so using the Administration is no option.

This guide will cover how to add a custom mail template with your plugin.

## Prerequisites

The namespaces used in the examples of this guide are the same as the namespace from our [Plugin base guide](../../plugin-base-guide), so you might want to have a look at it first.

Furthermore, this guide will use [Database migrations](../../database/database-migrations.md) in order to add a custom mail template, which is not explained in depth here. Make sure to understand those first!

## Adding a mail template via migration

As already mentioned, adding a mail template is done by using a plugin database migration. To be precise, those are the steps necessary:

* Create a new mail template type or fetch an existing mail template type ID
* Add an entry to `mail_template` using the said template type ID
* Add an entry to `mail_template_translation` for each language you want to support

The following example will create a new template of type "contact form", which is already available. There will be an example to create a custom mail template type though.

Let's have a look at an example, which will:

* Use the "contact form" type
* Add a mail template entry
* Add a mail template translation for en\_GB and de\_DE

```php
// <plugin root>/src/Migration/Migration1616418675AddMailTemplate.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use DateTime;
use Doctrine\DBAL\Connection;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Uuid\Uuid;

class Migration1616418675AddMailTemplate extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1616418675;
    }

    public function update(Connection $connection): void
    {
        $mailTemplateTypeId = $this->getMailTemplateTypeId($connection);

        $this->createMailTemplate($connection, $mailTemplateTypeId);
    }

    private function getMailTemplateTypeId(Connection $connection): string
    {
        $sql = <<<SQL
            SELECT id
            FROM mail_template_type
            WHERE technical_name = "contact_form"
        SQL;

        return Uuid::fromBytesToHex($connection->fetchOne($sql));
    }

    private function getLanguageIdByLocale(Connection $connection, string $locale): ?string
    {
        $sql = <<<SQL
        SELECT `language`.`id`
        FROM `language`
        INNER JOIN `locale` ON `locale`.`id` = `language`.`locale_id`
        WHERE `locale`.`code` = :code
        SQL;

        $languageId = $connection->executeQuery($sql, ['code' => $locale])->fetchOne();

        if (empty($languageId)) {
            return null;
        }

        return $languageId;
    }

    private function createMailTemplate(Connection $connection, string $mailTemplateTypeId): void
    {
        $mailTemplateId = Uuid::randomHex();

        $enGbLangId = $this->getLanguageIdByLocale($connection, 'en-GB');
        $deDeLangId = $this->getLanguageIdByLocale($connection, 'de-DE');

        $connection->executeStatement("
        INSERT IGNORE INTO `mail_template`
            (id, mail_template_type_id, system_default, created_at)
        VALUES
            (:id, :mailTemplateTypeId, :systemDefault, :createdAt)
        ",[
            'id' => Uuid::fromHexToBytes($mailTemplateId),
            'mailTemplateTypeId' => Uuid::fromHexToBytes($mailTemplateTypeId),
            'systemDefault' => 0,
            'createdAt' => (new DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
        ]);

        if (!empty($enGbLangId)) {
            $connection->executeStatement("
            INSERT IGNORE INTO `mail_template_translation`
                (mail_template_id, language_id, sender_name, subject, description, content_html, content_plain, created_at)
            VALUES
                (:mailTemplateId, :languageId, :senderName, :subject, :description, :contentHtml, :contentPlain, :createdAt)
            ",[
                'mailTemplateId' => Uuid::fromHexToBytes($mailTemplateId),
                'languageId' => $enGbLangId,
                'senderName' => '{{ salesChannel.name }}',
                'subject' => 'Example mail template subject',
                'description' => 'Example mail template description',
                'contentHtml' => $this->getContentHtmlEn(),
                'contentPlain' => $this->getContentPlainEn(),
                'createdAt' => (new DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
            ]);
        }

        if (!empty($deDeLangId)) {
            $connection->executeStatement("
            INSERT IGNORE INTO `mail_template_translation`
                (mail_template_id, language_id, sender_name, subject, description, content_html, content_plain, created_at)
            VALUES
                (:mailTemplateId, :languageId, :senderName, :subject, :description, :contentHtml, :contentPlain, :createdAt)
            ",[
                'mailTemplateId' => Uuid::fromHexToBytes($mailTemplateId),
                'languageId' => $deDeLangId,
                'senderName' => '{{ salesChannel.name }}',
                'subject' => 'Beispiel E-Mail Template Titel',
                'description' => 'Beispiel E-Mail Template Beschreibung',
                'contentHtml' => $this->getContentHtmlDe(),
                'contentPlain' => $this->getContentPlainDe(),
                'createdAt' => (new DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
            ]);
        }

    }

    private function getContentHtmlEn(): string
    {
        return <<<MAIL
        <div style="font-family:arial; font-size:12px;">
            <p>
                Example HTML content!
            </p>
        </div>
        MAIL;
    }

    private function getContentPlainEn(): string
    {
        return <<<MAIL
        Example plain content!
        MAIL;
    }

    private function getContentHtmlDe(): string
    {
        return <<<MAIL
        <div style="font-family:arial; font-size:12px;">
            <p>
                Beispiel HTML Inhalt!
            </p>
        </div>
        MAIL;
    }

    private function getContentPlainDe(): string
    {
        return <<<MAIL
        Beispiel Plain Inhalt!
        MAIL;
    }
}
```

First of all, let's have a look at the small `update` method. It's mainly just fetching the mail template type ID using a short SQL statement and afterwards it executes the method `createMailTemplate`, which will cover all the other steps.

Now on to the `createMailTemplate` method, which looks big, but isn't that scary. First of all, we're fetching the language IDs for both `en-GB` and `de-DE`.

We then create the entry for the `mail_template` table. Make sure to set `system_default` to 0 here!

Afterwards we're inserting the entries into the `mail_template_translation` table. For compatibility reasons we have to check whether the languages exist in the database so we can insert our translations for these languages. The same principle applies to other ISO languages.

The variables for the English and the German subject and description, may be changed to fit your needs.

Each of those calls uses a little helper method `getContentHtml` or `getContentPlain` respectively, where you can use your template.

And that's it, once your plugin is installed, the mail template will be added to Shopware.

::: warning
Do not remove e-mail templates in your plugin, e.g. when it is uninstalled. This may lead to data inconsistency, since those templates can be associated to other entities. Beware to use `IGNORE` before `INTO` Statements so no exception will be thrown upon uninstallation and reinstallation of your plugin.
:::

### Creating a custom mail type

In order to not only use an existing mail template type, but to create a custom one, you have to adjust the `update` method and create a new method.

Let's have a look:

```php
// <plugin root>/src/Migration/Migration1616418675AddMailTemplate.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use DateTime;
use Doctrine\DBAL\Connection;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Uuid\Uuid;

class Migration1616418675AddMailTemplate extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1616418675;
    }

    public function update(Connection $connection): void
    {
        $mailTemplateTypeId = $this->createMailTemplateType($connection);

        $this->createMailTemplate($connection, $mailTemplateTypeId);
    }

    private function createMailTemplateType(Connection $connection): string
    {
        $mailTemplateTypeId = Uuid::randomHex();

        $enGbLangId = $this->getLanguageIdByLocale($connection, 'en-GB');
        $deDeLangId = $this->getLanguageIdByLocale($connection, 'de-DE');

        $englishName = 'Example mail template type name';
        $germanName = 'Beispiel E-Mail Template Name';

        $connection->executeStatement("
            INSERT IGNORE INTO `mail_template_type`
                (id, technical_name, available_entities, created_at)
            VALUES
                (:id, :technicalName, :availableEntities, :createdAt)
        ",[
            'id' => Uuid::fromHexToBytes($mailTemplateTypeId),
            'technicalName' => 'custom_mail_template_type',
            'availableEntities' => json_encode(['product' => 'product']),
            'createdAt' => (new DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
        ]);

        if (!empty($enGbLangId)) {
            $connection->executeStatement("
            INSERT IGNORE INTO `mail_template_type_translation`
                (mail_template_type_id, language_id, name, created_at)
            VALUES
                (:mailTemplateTypeId, :languageId, :name, :createdAt)
            ",[
                'mailTemplateTypeId' => Uuid::fromHexToBytes($mailTemplateTypeId),
                'languageId' => $enGbLangId,
                'name' => $englishName,
                'createdAt' => (new DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
            ]);
        }

        if (!empty($deDeLangId)) {
            $connection->executeStatement("
            INSERT IGNORE INTO `mail_template_type_translation`
                (mail_template_type_id, language_id, name, created_at)
            VALUES
                (:mailTemplateTypeId, :languageId, :name, :createdAt)
            ",[
                'mailTemplateTypeId' => Uuid::fromHexToBytes($mailTemplateTypeId),
                'languageId' => $deDeLangId,
                'name' => $germanName,
                'createdAt' => (new DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
            ]);
        }

        return $mailTemplateTypeId;
    }

    // ...
}
```

First of all we changed the `getMailTemplateTypeId` method call to `createMailTemplateType`, a new method which we will create afterwards. Again, this method then has to return the ID of the newly created mail template ID.

So having a look at the `createMailTemplateType` method, you will see some similarities:

* First of all we're fetching the language IDs for `en-GB` and `de-DE`
* Then we define the translated names for the mail template type
* And then the respective `mail_template_type` entry, as well as the translated `mail_template_type_translation` entries are created

Note the `available_entities` column when creating the mail template type itself though. In here, you define which entities should be available for the respective mail template, in this example we'll just provide the `ProductEntity`.

## Next steps

Now that you know how to add custom mail templates, you might wonder how you can actually add new mail template data to existing mail templates.

For that case, we've created a separate guide about [adding data to mail templates](add-data-to-mails).

---

---
url: /docs/v6.5/guides/plugins/plugins/content/mail/add-mail-template.md
---

# Add Mail Templates

## Overview

You can add new mail templates to Shopware by using the Administration. However, you might want to ship a mail template with your plugin, so using the Administration is no option.

This guide will cover how to add a custom mail template with your plugin.

## Prerequisites

The namespaces used in the examples of this guide are the same as the namespace from our [Plugin base guide](../../plugin-base-guide), so you might want to have a look at it first.

Furthermore, this guide will use [Database migrations](../../plugin-fundamentals/database-migrations) in order to add a custom mail template, which is not explained in depth here. Make sure to understand those first!

## Adding a mail template via migration

As already mentioned, adding a mail template is done by using a plugin database migration. To be precise, those are the steps necessary:

* Create a new mail template type or fetch an existing mail template type ID
* Add an entry to `mail_template` using the said template type ID
* Add an entry to `mail_template_translation` for each language you want to support

The following example will create a new template of type "contact form", which is already available. There will be an example to create a custom mail template type though.

Let's have a look at an example, which will:

* Use the "contact form" type
* Add a mail template entry
* Add a mail template translation for en\_GB and de\_DE

```php
// <plugin root>/src/Migration/Migration1616418675AddMailTemplate.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use DateTime;
use Doctrine\DBAL\Connection;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Uuid\Uuid;

class Migration1616418675AddMailTemplate extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1616418675;
    }

    public function update(Connection $connection): void
    {
        $mailTemplateTypeId = $this->getMailTemplateTypeId($connection);

        $this->createMailTemplate($connection, $mailTemplateTypeId);
    }

    public function updateDestructive(Connection $connection): void
    {
    }

    private function getMailTemplateTypeId(Connection $connection): string
    {
        $sql = <<<SQL
            SELECT id
            FROM mail_template_type
            WHERE technical_name = "contact_form"
        SQL;

        return Uuid::fromBytesToHex($connection->fetchOne($sql));
    }

    private function getLanguageIdByLocale(Connection $connection, string $locale): ?string
    {
        $sql = <<<SQL
        SELECT `language`.`id`
        FROM `language`
        INNER JOIN `locale` ON `locale`.`id` = `language`.`locale_id`
        WHERE `locale`.`code` = :code
        SQL;

        $languageId = $connection->executeQuery($sql, ['code' => $locale])->fetchOne();

        if (empty($languageId)) {
            return null;
        }

        return $languageId;
    }

    private function createMailTemplate(Connection $connection, string $mailTemplateTypeId): void
    {
        $mailTemplateId = Uuid::randomHex();

        $enGbLangId = $this->getLanguageIdByLocale($connection, 'en-GB');
        $deDeLangId = $this->getLanguageIdByLocale($connection, 'de-DE');

        $connection->executeStatement("
        INSERT IGNORE INTO `mail_template`
            (id, mail_template_type_id, system_default, created_at)
        VALUES
            (:id, :mailTemplateTypeId, :systemDefault, :createdAt)
        ",[
            'id' => Uuid::fromHexToBytes($mailTemplateId),
            'mailTemplateTypeId' => Uuid::fromHexToBytes($mailTemplateTypeId),
            'systemDefault' => 0,
            'createdAt' => (new DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
        ]);

        if (!empty($enGbLangId)) {
            $connection->executeStatement("
            INSERT IGNORE INTO `mail_template_translation`
                (mail_template_id, language_id, sender_name, subject, description, content_html, content_plain, created_at)
            VALUES
                (:mailTemplateId, :languageId, :senderName, :subject, :description, :contentHtml, :contentPlain, :createdAt)
            ",[
                'mailTemplateId' => Uuid::fromHexToBytes($mailTemplateId),
                'languageId' => $enGbLangId,
                'senderName' => '{{ salesChannel.name }}',
                'subject' => 'Example mail template subject',
                'description' => 'Example mail template description',
                'contentHtml' => $this->getContentHtmlEn(),
                'contentPlain' => $this->getContentPlainEn(),
                'createdAt' => (new DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
            ]);
        }

        if (!empty($deDeLangId)) {            
            $connection->executeStatement("
            INSERT IGNORE INTO `mail_template_translation`
                (mail_template_id, language_id, sender_name, subject, description, content_html, content_plain, created_at)
            VALUES
                (:mailTemplateId, :languageId, :senderName, :subject, :description, :contentHtml, :contentPlain, :createdAt)
            ",[
                'mailTemplateId' => Uuid::fromHexToBytes($mailTemplateId),
                'languageId' => $deDeLangId,
                'senderName' => '{{ salesChannel.name }}',
                'subject' => 'Beispiel E-Mail Template Titel',
                'description' => 'Beispiel E-Mail Template Beschreibung',
                'contentHtml' => $this->getContentHtmlDe(),
                'contentPlain' => $this->getContentPlainDe(),
                'createdAt' => (new DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
            ]);
        }

    }

    private function getContentHtmlEn(): string
    {
        return <<<MAIL
        <div style="font-family:arial; font-size:12px;">
            <p>
                Example HTML content!
            </p>
        </div>
        MAIL;
    }

    private function getContentPlainEn(): string
    {
        return <<<MAIL
        Example plain content!
        MAIL;
    }

    private function getContentHtmlDe(): string
    {
        return <<<MAIL
        <div style="font-family:arial; font-size:12px;">
            <p>
                Beispiel HTML Inhalt!
            </p>
        </div>
        MAIL;
    }

    private function getContentPlainDe(): string
    {
        return <<<MAIL
        Beispiel Plain Inhalt!
        MAIL;
    }
}
```

First of all, let's have a look at the small `update` method. It's mainly just fetching the mail template type ID using a short SQL statement and afterwards it executes the method `createMailTemplate`, which will cover all the other steps.

Now on to the `createMailTemplate` method, which looks big, but isn't that scary. First of all, we're fetching the language IDs for both `en-GB` and `de-DE`.

We then create the entry for the `mail_template` table. Make sure to set `system_default` to 0 here!

Afterwards we're inserting the entries into the `mail_template_translation` table. For compatibility reasons we have to check whether the languages exist in the database so we can insert our translations for these languages. The same principle applies to other ISO languages.

The variables for the English and the German subject and description, may be changed to fit your needs.

Each of those calls uses a little helper method `getContentHtml` or `getContentPlain` respectively, where you can use your template.

And that's it, once your plugin is installed, the mail template will be added to Shopware.

::: warning
Do not remove e-mail templates in your plugin, e.g. when it is uninstalled. This may lead to data inconsistency, since those templates can be associated to other entities. Beware to use `IGNORE` before `INTO` Statements so no exception will be thrown upon uninstallation and reinstallation of your plugin.
:::

### Creating a custom mail type

In order to not only use an existing mail template type, but to create a custom one, you have to adjust the `update` method and create a new method.

Let's have a look:

```php
// <plugin root>/src/Migration/Migration1616418675AddMailTemplate.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use DateTime;
use Doctrine\DBAL\Connection;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Uuid\Uuid;

class Migration1616418675AddMailTemplate extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1616418675;
    }

    public function update(Connection $connection): void
    {
        $mailTemplateTypeId = $this->createMailTemplateType($connection);

        $this->createMailTemplate($connection, $mailTemplateTypeId);
    }

    private function createMailTemplateType(Connection $connection): string
    {
        $mailTemplateTypeId = Uuid::randomHex();

        $enGbLangId = $this->getLanguageIdByLocale($connection, 'en-GB');
        $deDeLangId = $this->getLanguageIdByLocale($connection, 'de-DE');

        $englishName = 'Example mail template type name';
        $germanName = 'Beispiel E-Mail Template Name';

        $connection->executeStatement("
            INSERT IGNORE INTO `mail_template_type`
                (id, technical_name, available_entities, created_at)
            VALUES
                (:id, :technicalName, :availableEntities, :createdAt)
        ",[
            'id' => Uuid::fromHexToBytes($mailTemplateTypeId),
            'technicalName' => 'custom_mail_template_type',
            'availableEntities' => json_encode(['product' => 'product']),
            'createdAt' => (new DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
        ]);

        if (!empty($enGbLangId)) {
            $connection->executeStatement("
            INSERT IGNORE INTO `mail_template_type_translation`
                (mail_template_type_id, language_id, name, created_at)
            VALUES
                (:mailTemplateTypeId, :languageId, :name, :createdAt)
            ",[
                'mailTemplateTypeId' => Uuid::fromHexToBytes($mailTemplateTypeId),
                'languageId' => $enGbLangId,
                'name' => $englishName,
                'createdAt' => (new DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
            ]);
        }

        if (!empty($deDeLangId)) {
            $connection->executeStatement("
            INSERT IGNORE INTO `mail_template_type_translation`
                (mail_template_type_id, language_id, name, created_at)
            VALUES
                (:mailTemplateTypeId, :languageId, :name, :createdAt)
            ",[
                'mailTemplateTypeId' => Uuid::fromHexToBytes($mailTemplateTypeId),
                'languageId' => $deDeLangId,
                'name' => $germanName,
                'createdAt' => (new DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
            ]);
        }

        return $mailTemplateTypeId;
    }

    // ...
}
```

First of all we changed the `getMailTemplateTypeId` method call to `createMailTemplateType`, a new method which we will create afterwards. Again, this method then has to return the ID of the newly created mail template ID.

So having a look at the `createMailTemplateType` method, you will see some similarities:

* First of all we're fetching the language IDs for `en-GB` and `de-DE`
* Then we define the translated names for the mail template type
* And then the respective `mail_template_type` entry, as well as the translated `mail_template_type_translation` entries are created

Note the `available_entities` column when creating the mail template type itself though. In here, you define which entities should be available for the respective mail template, in this example we'll just provide the `ProductEntity`.

## Next steps

Now that you know how to add custom mail templates, you might wonder how you can actually add new mail template data to existing mail templates.

For that case, we've created a separate guide about [adding data to mail templates](add-data-to-mails).

---

---
url: /docs/v6.6/guides/plugins/plugins/content/mail/add-mail-template.md
---

# Add Mail Templates

## Overview

You can add new mail templates to Shopware by using the Administration. However, you might want to ship a mail template with your plugin, so using the Administration is no option.

This guide will cover how to add a custom mail template with your plugin.

## Prerequisites

The namespaces used in the examples of this guide are the same as the namespace from our [Plugin base guide](../../plugin-base-guide), so you might want to have a look at it first.

Furthermore, this guide will use [Database migrations](../../plugin-fundamentals/database-migrations) in order to add a custom mail template, which is not explained in depth here. Make sure to understand those first!

## Adding a mail template via migration

As already mentioned, adding a mail template is done by using a plugin database migration. To be precise, those are the steps necessary:

* Create a new mail template type or fetch an existing mail template type ID
* Add an entry to `mail_template` using the said template type ID
* Add an entry to `mail_template_translation` for each language you want to support

The following example will create a new template of type "contact form", which is already available. There will be an example to create a custom mail template type though.

Let's have a look at an example, which will:

* Use the "contact form" type
* Add a mail template entry
* Add a mail template translation for en\_GB and de\_DE

```php
// <plugin root>/src/Migration/Migration1616418675AddMailTemplate.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use DateTime;
use Doctrine\DBAL\Connection;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Uuid\Uuid;

class Migration1616418675AddMailTemplate extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1616418675;
    }

    public function update(Connection $connection): void
    {
        $mailTemplateTypeId = $this->getMailTemplateTypeId($connection);

        $this->createMailTemplate($connection, $mailTemplateTypeId);
    }

    public function updateDestructive(Connection $connection): void
    {
    }

    private function getMailTemplateTypeId(Connection $connection): string
    {
        $sql = <<<SQL
            SELECT id
            FROM mail_template_type
            WHERE technical_name = "contact_form"
        SQL;

        return Uuid::fromBytesToHex($connection->fetchOne($sql));
    }

    private function getLanguageIdByLocale(Connection $connection, string $locale): ?string
    {
        $sql = <<<SQL
        SELECT `language`.`id`
        FROM `language`
        INNER JOIN `locale` ON `locale`.`id` = `language`.`locale_id`
        WHERE `locale`.`code` = :code
        SQL;

        $languageId = $connection->executeQuery($sql, ['code' => $locale])->fetchOne();

        if (empty($languageId)) {
            return null;
        }

        return $languageId;
    }

    private function createMailTemplate(Connection $connection, string $mailTemplateTypeId): void
    {
        $mailTemplateId = Uuid::randomHex();

        $enGbLangId = $this->getLanguageIdByLocale($connection, 'en-GB');
        $deDeLangId = $this->getLanguageIdByLocale($connection, 'de-DE');

        $connection->executeStatement("
        INSERT IGNORE INTO `mail_template`
            (id, mail_template_type_id, system_default, created_at)
        VALUES
            (:id, :mailTemplateTypeId, :systemDefault, :createdAt)
        ",[
            'id' => Uuid::fromHexToBytes($mailTemplateId),
            'mailTemplateTypeId' => Uuid::fromHexToBytes($mailTemplateTypeId),
            'systemDefault' => 0,
            'createdAt' => (new DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
        ]);

        if (!empty($enGbLangId)) {
            $connection->executeStatement("
            INSERT IGNORE INTO `mail_template_translation`
                (mail_template_id, language_id, sender_name, subject, description, content_html, content_plain, created_at)
            VALUES
                (:mailTemplateId, :languageId, :senderName, :subject, :description, :contentHtml, :contentPlain, :createdAt)
            ",[
                'mailTemplateId' => Uuid::fromHexToBytes($mailTemplateId),
                'languageId' => $enGbLangId,
                'senderName' => '{{ salesChannel.name }}',
                'subject' => 'Example mail template subject',
                'description' => 'Example mail template description',
                'contentHtml' => $this->getContentHtmlEn(),
                'contentPlain' => $this->getContentPlainEn(),
                'createdAt' => (new DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
            ]);
        }

        if (!empty($deDeLangId)) {            
            $connection->executeStatement("
            INSERT IGNORE INTO `mail_template_translation`
                (mail_template_id, language_id, sender_name, subject, description, content_html, content_plain, created_at)
            VALUES
                (:mailTemplateId, :languageId, :senderName, :subject, :description, :contentHtml, :contentPlain, :createdAt)
            ",[
                'mailTemplateId' => Uuid::fromHexToBytes($mailTemplateId),
                'languageId' => $deDeLangId,
                'senderName' => '{{ salesChannel.name }}',
                'subject' => 'Beispiel E-Mail Template Titel',
                'description' => 'Beispiel E-Mail Template Beschreibung',
                'contentHtml' => $this->getContentHtmlDe(),
                'contentPlain' => $this->getContentPlainDe(),
                'createdAt' => (new DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
            ]);
        }

    }

    private function getContentHtmlEn(): string
    {
        return <<<MAIL
        <div style="font-family:arial; font-size:12px;">
            <p>
                Example HTML content!
            </p>
        </div>
        MAIL;
    }

    private function getContentPlainEn(): string
    {
        return <<<MAIL
        Example plain content!
        MAIL;
    }

    private function getContentHtmlDe(): string
    {
        return <<<MAIL
        <div style="font-family:arial; font-size:12px;">
            <p>
                Beispiel HTML Inhalt!
            </p>
        </div>
        MAIL;
    }

    private function getContentPlainDe(): string
    {
        return <<<MAIL
        Beispiel Plain Inhalt!
        MAIL;
    }
}
```

First of all, let's have a look at the small `update` method. It's mainly just fetching the mail template type ID using a short SQL statement and afterwards it executes the method `createMailTemplate`, which will cover all the other steps.

Now on to the `createMailTemplate` method, which looks big, but isn't that scary. First of all, we're fetching the language IDs for both `en-GB` and `de-DE`.

We then create the entry for the `mail_template` table. Make sure to set `system_default` to 0 here!

Afterwards we're inserting the entries into the `mail_template_translation` table. For compatibility reasons we have to check whether the languages exist in the database so we can insert our translations for these languages. The same principle applies to other ISO languages.

The variables for the English and the German subject and description, may be changed to fit your needs.

Each of those calls uses a little helper method `getContentHtml` or `getContentPlain` respectively, where you can use your template.

And that's it, once your plugin is installed, the mail template will be added to Shopware.

::: warning
Do not remove e-mail templates in your plugin, e.g. when it is uninstalled. This may lead to data inconsistency, since those templates can be associated to other entities. Beware to use `IGNORE` before `INTO` Statements so no exception will be thrown upon uninstallation and reinstallation of your plugin.
:::

### Creating a custom mail type

In order to not only use an existing mail template type, but to create a custom one, you have to adjust the `update` method and create a new method.

Let's have a look:

```php
// <plugin root>/src/Migration/Migration1616418675AddMailTemplate.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use DateTime;
use Doctrine\DBAL\Connection;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Uuid\Uuid;

class Migration1616418675AddMailTemplate extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1616418675;
    }

    public function update(Connection $connection): void
    {
        $mailTemplateTypeId = $this->createMailTemplateType($connection);

        $this->createMailTemplate($connection, $mailTemplateTypeId);
    }

    private function createMailTemplateType(Connection $connection): string
    {
        $mailTemplateTypeId = Uuid::randomHex();

        $enGbLangId = $this->getLanguageIdByLocale($connection, 'en-GB');
        $deDeLangId = $this->getLanguageIdByLocale($connection, 'de-DE');

        $englishName = 'Example mail template type name';
        $germanName = 'Beispiel E-Mail Template Name';

        $connection->executeStatement("
            INSERT IGNORE INTO `mail_template_type`
                (id, technical_name, available_entities, created_at)
            VALUES
                (:id, :technicalName, :availableEntities, :createdAt)
        ",[
            'id' => Uuid::fromHexToBytes($mailTemplateTypeId),
            'technicalName' => 'custom_mail_template_type',
            'availableEntities' => json_encode(['product' => 'product']),
            'createdAt' => (new DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
        ]);

        if (!empty($enGbLangId)) {
            $connection->executeStatement("
            INSERT IGNORE INTO `mail_template_type_translation`
                (mail_template_type_id, language_id, name, created_at)
            VALUES
                (:mailTemplateTypeId, :languageId, :name, :createdAt)
            ",[
                'mailTemplateTypeId' => Uuid::fromHexToBytes($mailTemplateTypeId),
                'languageId' => $enGbLangId,
                'name' => $englishName,
                'createdAt' => (new DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
            ]);
        }

        if (!empty($deDeLangId)) {
            $connection->executeStatement("
            INSERT IGNORE INTO `mail_template_type_translation`
                (mail_template_type_id, language_id, name, created_at)
            VALUES
                (:mailTemplateTypeId, :languageId, :name, :createdAt)
            ",[
                'mailTemplateTypeId' => Uuid::fromHexToBytes($mailTemplateTypeId),
                'languageId' => $deDeLangId,
                'name' => $germanName,
                'createdAt' => (new DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT),
            ]);
        }

        return $mailTemplateTypeId;
    }

    // ...
}
```

First of all we changed the `getMailTemplateTypeId` method call to `createMailTemplateType`, a new method which we will create afterwards. Again, this method then has to return the ID of the newly created mail template ID.

So having a look at the `createMailTemplateType` method, you will see some similarities:

* First of all we're fetching the language IDs for `en-GB` and `de-DE`
* Then we define the translated names for the mail template type
* And then the respective `mail_template_type` entry, as well as the translated `mail_template_type_translation` entries are created

Note the `available_entities` column when creating the mail template type itself though. In here, you define which entities should be available for the respective mail template, in this example we'll just provide the `ProductEntity`.

## Next steps

Now that you know how to add custom mail templates, you might wonder how you can actually add new mail template data to existing mail templates.

For that case, we've created a separate guide about [adding data to mail templates](add-data-to-mails).

---

---
url: /docs/v6.5/guides/plugins/plugins/administration/add-menu-entry.md
---

# Add menu entry

## Overview

When it comes to the module configuration, the menu entry is one of the most important things to set up. It serves to open your module.

## Prerequisites

This guide **does not** explain how to create a new plugin for Shopware 6. Head over to our Plugin base guide to learn how to create a plugin at first:

Especially if you want to add a new page for an own module, you should consider to look at the process on how to add a custom module first.

## Creating a simple menu entry

This menu entry can be defined in your module configuration. Remember, your module configuration looks as seen below:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/swag-example/index.js
Shopware.Module.register('swag-plugin', {
    // configuration here
});
```

In order to create your own menu entry, you need to use the `navigation` key: It takes an array of objects, each one configuring a route connected to your module.

So let's define a menu entry using the `navigation` key in your module configuration. It takes an array of objects, each one configuring a route connected to your module:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/swag-example/index.js
navigation: [{
    label: 'CustomModule',
    color: '#ff3d58',
    path: 'swag.custommodule.list',
    icon: 'default-shopping-paper-bag-product',
    position: 100
}]
```

As you see, you are able to configure several things in there:

| Configuration | Description |
| :--- | :--- |
| label | The label to be shown with this menu entry. |
| color | This  is the theme color of the module. This color may differ from the module's color itself. |
| path | Which one of your configured routes shall be used when clicking this menu entry? The path is composed of the module id and the path name. Dashes become dots, for example module 'swag-example' and path 'index' become 'swag.example.index'. |
| icon | Also you can set a separate icon, which can make sense e.g. when having multiple menu entries for a single module, such as a special icon for 'Create bundle'. This example does not have this and it's only going to have a single menu entry, so use the icon from the main module here. |
| position | The position of the menu entry. The higher the value, the more likely it is that your menu entry appears in the bottom. |

Of course there's more to be configured here, but more's not necessary for this example.

## Menu entry in category

Due to UX reasons, we're not supporting plugin modules to add new menu entries on the first level of the main menu. Please use the "parent" property inside your navigation object to define the category where you want your menu entry will be appended to. Your navigation entry will also have to have an `id` to show up in the rendered navigation:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/swag-example/index.js
navigation: [{
    id: 'swag-custommodule-list',
    label: 'CustomModule',
    color: '#ff3d58',
    path: 'swag.custommodule.list',
    icon: 'default-shopping-paper-bag-product',
    parent: 'sw-catalogue',
    position: 100
}]
```

You can find the parent id at the `index.js` file in each module folder. You can see the property `navigation` in the `Module.register` method. The id here can be used as the parent key.

## Nesting menu entries

The parent can be on any level because the menu supports infinite depth nesting. For example, if `sw-manufacturer` were taken as the `parent`, the menu item would be present on the third level. So what's important here is that the configured parent defines where the menu entry will take place.

::: info
If you're planning to publish your plugin to the Shopware Store keep in mind we're rejecting plugins which have created their own menu entry on the first level.
:::

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/administration/routing-navigation/add-menu-entry.md
---

# Add menu entry

## Overview

When it comes to the module configuration, the menu entry is one of the most important things to set up. It serves to open your module.

## Prerequisites

This guide **does not** explain how to create a new plugin for Shopware 6. Head over to our Plugin base guide to learn how to create a plugin at first:

Especially if you want to add a new page for an own module, you should consider to look at the process on how to add a custom module first.

## Creating a simple menu entry

This menu entry can be defined in your module configuration. Remember, your module configuration looks as seen below:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/swag-example/index.js
Shopware.Module.register('swag-plugin', {
    // configuration here
});
```

In order to create your own menu entry, you need to use the `navigation` key: It takes an array of objects, each one configuring a route connected to your module.

So let's define a menu entry using the `navigation` key in your module configuration. It takes an array of objects, each one configuring a route connected to your module:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/swag-example/index.js
navigation: [{
    label: 'CustomModule',
    color: '#ff3d58',
    path: 'swag.custommodule.list',
    icon: 'default-shopping-paper-bag-product',
    parent: 'sw-catalogue',
    position: 100
}]
```

As you see, you are able to configure several things in there:

| Configuration | Description |
| :--- | :--- |
| label | The label to be shown with this menu entry. |
| color | This  is the theme color of the module. This color may differ from the module's color itself. |
| path | Which one of your configured routes shall be used when clicking this menu entry? The path is composed of the module id and the path name. Dashes become dots, for example module 'swag-example' and path 'index' become 'swag.example.index'. |
| icon | Also you can set a separate icon, which can make sense e.g. when having multiple menu entries for a single module, such as a special icon for 'Create bundle'. This example does not have this and it's only going to have a single menu entry, so use the icon from the main module here. |
| position | The position of the menu entry. The higher the value, the more likely it is that your menu entry appears in the bottom. |

Of course there's more to be configured here, but more's not necessary for this example.

## Menu entry in category

Due to UX reasons, we're not supporting plugin modules to add new menu entries on the first level of the main menu. Please use the "parent" property inside your navigation object to define the category where you want your menu entry will be appended to. Your navigation entry will also have to have an `id` to show up in the rendered navigation:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/swag-example/index.js
navigation: [{
    id: 'swag-custommodule-list',
    label: 'CustomModule',
    color: '#ff3d58',
    path: 'swag.custommodule.list',
    icon: 'default-shopping-paper-bag-product',
    parent: 'sw-catalogue',
    position: 100
}]
```

You can find the parent id at the `index.js` file in each module folder. You can see the property `navigation` in the `Module.register` method. The id here can be used as the parent key.

## Nesting menu entries

The parent can be on any level because the menu supports infinite depth nesting. For example, if `sw-manufacturer` were taken as the `parent`, the menu item would be present on the third level. So what's important here is that the configured parent defines where the menu entry will take place.

::: info
If you're planning to publish your plugin to the Shopware Store keep in mind we're rejecting plugins which have created their own menu entry on the first level.
:::

---

---
url: >-
  /docs/guides/plugins/plugins/administration/routing-navigation/add-menu-entry.md
---

# Add Menu Entry

## Overview

When it comes to the module configuration, the menu entry is one of the most important things to set up. It serves to open your module.

## Prerequisites

This guide **does not** explain how to create a new plugin for Shopware 6. Head over to our Plugin base guide to learn how to create a plugin at first:

Especially if you want to add a new page for an own module, you should consider to look at the process on how to add a custom module first.

## Creating a simple menu entry

This menu entry can be defined in your module configuration. Remember, your module configuration looks as seen below:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/swag-example/index.js
Shopware.Module.register('swag-plugin', {
    // configuration here
});
```

In order to create your own menu entry, you need to use the `navigation` key: It takes an array of objects, each one configuring a route connected to your module.

So let's define a menu entry using the `navigation` key in your module configuration. It takes an array of objects, each one configuring a route connected to your module:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/swag-example/index.js
navigation: [{
    label: 'CustomModule',
    color: '#ff3d58',
    path: 'swag.custommodule.list',
    icon: 'default-shopping-paper-bag-product',
    parent: 'sw-catalogue',
    position: 100
}]
```

As you see, you are able to configure several things in there:

| Configuration | Description |
| :--- | :--- |
| label | The label to be shown with this menu entry. |
| color | This  is the theme color of the module. This color may differ from the module's color itself. |
| path | Which one of your configured routes shall be used when clicking this menu entry? The path is composed of the module id and the path name. Dashes become dots, for example module 'swag-example' and path 'index' become 'swag.example.index'. |
| icon | Also you can set a separate icon, which can make sense e.g. when having multiple menu entries for a single module, such as a special icon for 'Create bundle'. This example does not have this and it's only going to have a single menu entry, so use the icon from the main module here. |
| position | The position of the menu entry. The higher the value, the more likely it is that your menu entry appears in the bottom. |

Of course there's more to be configured here, but more's not necessary for this example.

## Menu entry in category

Due to UX reasons, we're not supporting plugin modules to add new menu entries on the first level of the main menu. Please use the "parent" property inside your navigation object to define the category where you want your menu entry will be appended to. Your navigation entry will also have to have an `id` to show up in the rendered navigation:

```javascript
// <plugin root>/src/Resources/app/administration/src/module/swag-example/index.js
navigation: [{
    id: 'swag-custommodule-list',
    label: 'CustomModule',
    color: '#ff3d58',
    path: 'swag.custommodule.list',
    icon: 'default-shopping-paper-bag-product',
    parent: 'sw-catalogue',
    position: 100
}]
```

You can find the parent id at the `index.js` file in each module folder. You can see the property `navigation` in the `Module.register` method. The id here can be used as the parent key.

## Nesting menu entries

The parent can be on any level because the menu supports infinite depth nesting. For example, if `sw-manufacturer` were taken as the `parent`, the menu item would be present on the third level. So what's important here is that the configured parent defines where the menu entry will take place.

::: info
If you're planning to publish your plugin to the Shopware Store keep in mind we're rejecting plugins which have created their own menu entry on the first level.
:::

---

---
url: >-
  /docs/v6.5/guides/plugins/plugins/framework/message-queue/add-message-handler.md
---

# Add message handler

## Overview

::: warning
Parts of this guide refer to the `low_priority` queue, which is only available in version 6.5.7.0 and above. Configuring the messenger to consume this queue will fail if it does not exist.
:::

In this guide you'll learn how to create a message handler.

A [handler](https://symfony.com/doc/current/messenger.html#creating-a-message-handler) gets called once the message is dispatched by the `handle_messages` middleware. Handlers do the actual processing of the message.

## Prerequisites

As most guides, this guide is also built upon the [Plugin base guide](../../plugin-base-guide), but you don't necessarily need that. It will use an example message, so if you don't know how to add a custom message yet, have a look at our guide about [Adding a message to queue](add-message-to-queue). Furthermore, registering classes or services to the DI container is also not explained here, but it's covered in our guide about [Dependency injection](../../plugin-fundamentals/dependency-injection), so having this open in another tab won't hurt.

## Handling messages

First, we have to create a new class which we will name `SmsHandler` in this example. To mark the class as message handler, we use the php attribute `#[AsMessageHandler]` and implement the method `__invoke`. We can also define multiple handlers for the same message. To register a handler, we have to tag it with the `messenger.message_handler` tag.

```php
// <plugin root>/src/MessageQueue/Handler/SmsHandler.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\MessageQueue\Handler;

use Symfony\Component\Messenger\Attribute\AsMessageHandler;
use Swag\BasicExample\MessageQueue\Message\SmsNotification;

#[AsMessageHandler]
class SmsHandler
{
    public function __invoke(SmsNotification $message)
    {
        // ... do some work - like sending an SMS message!
    }
}
```

## Consuming messages

There is a console command to start a worker that will receive incoming messages from your transport and dispatch them. Simply start the worker with the following command:

```bash
// 
bin/console messenger:consume async
```

You can also append more transports to the command, so the worker will consume messages from multiple transports which will result in prioritization as mentioned in [Prioritized Transports](https://symfony.com/doc/current/messenger.html#prioritized-transports):

```bash
// 
bin/console messenger:consume async low_priority
```

Where `async` and `low_priority` are the transports you want to consume messages from. There is also an API route that lets you consume messages for a given transport. send a `POST` request to the route `/api/_action/message-queue/consume` and define the transport which you want to consume:

```js
// on
{
  "receiver": "async"
}
```

The receiver will consume messages for 2 seconds and then you get the count of the handled messages in the response:

```js
// on
{
  "handledMessages": 15
}
```

### The admin-worker

Per default there is an admin-worker that will periodically ping the endpoint to consume messages from the Administration. This feature is intended for development and hosting environments where a more complex setup is not feasible. However, you really should use the cli-worker in production setups, because the admin-worker just consumes messages if an Administration user is logged in.

### The cli-worker

The recommended way to consume messages is through the cli command. You can configure the command to run a certain amount of time or to stop if it exceeds a certain memory limit like:

```bash
// 
bin/console messenger:consume async low_priority --time-limit=60
```

```bash
// 
bin/console messenger:consume async low_priority --memory-limit=128M
```

For more information about the command and its configuration use the `-h` option:

```bash
// 
bin/console messenger:consume -h
```

You should use the limit option to periodically restart the worker processes, because of the memory leak issues of long running php processes. To automatically start the processes again after they stopped because of exceeding the given limits you can use something like [upstart](http://upstart.ubuntu.com/getting-started.html) or [supervisor](http://supervisord.org/running.html). Alternatively you can configure a `CronJob` that runs the command periodically.

If you have configured the cli-worker, you can turn off the admin worker in your `shopware.yaml`.

```yaml
// <platform root>/src/Core/Framework/Resources/config/packages/shopware.yaml
shopware:
    admin_worker:
        enable_admin_worker: false
```

**Note:** This will disable the AdminWorker completely and you have to configure the cli-worker for scheduled tasks as well.

## Configuration

### Message bus

The message bus is used to dispatch your messages to your registered handlers. While dispatching your message it loops through the configured middleware for that bus. The message bus used inside Shopware can be found under the service tag `messenger.bus.shopware`. It is mandatory to use this message bus if your messages should be handled inside Shopware. However if you want to send messages to external systems you can define your custom message bus for that.

You can configure an array of buses and define one default bus in your `framework.yaml`.

```yaml
// <platform root>/src/Core/Framework/Resources/config/packages/framework.yaml
framework:
    messenger:
        default_bus: messenger.bus.shopware
        buses:
            messenger.bus.shopware:
```

For more information on this check the [Symfony docs](https://symfony.com/doc/current/messenger/multiple_buses.html).

### Transport

A [transport](https://symfony.com/doc/current/messenger.html#transports-async-queued-messages) is responsible for communicating with your 3rd party message broker. You can configure multiple transports and route messages to multiple or different transports. Supported are all transports that are either supported by [Symfony](https://symfony.com/doc/current/messenger.html#transport-configuration) itself. If you don't configure a transport, messages will be processed synchronously like in the Symfony event system.

You can configure an amqp transport directly in your `framework.yaml` and simply tell Symfony to use your  transports.

In a simple setup you only need to set the transport to a valid DSN like:

```yaml
// <platform root>/src/Core/Framework/Resources/config/packages/queue.yaml
framework:
  messenger:
    transports:
      my_transport:
        dsn: "%env(MESSENGER_TRANSPORT_DSN)%"
```

For more information on this check the [symfony docs](https://symfony.com/doc/current/messenger.html#transport-configuration).

### Routing

You can route messages to different transports. For that, just configure your routing in the `framework.yaml`.

```yaml
// <plugin root>/src/
framework:
    messenger:
      transports:
        async: "%env(MESSENGER_TRANSPORT_DSN)%"
        another_transport: "%env(MESSENGER_TRANSPORT_ANOTHER_DSN)%"
      routing: 
        'Swag\BasicExample\MessageQueue\Message\SmsNotification': another_transport
        'Swag\BasicExample\MessageQueue\Message\AnotherExampleNotification': [async, another_transport]
        '*': async
```

You can route messages by their classname and use the asterisk as a fallback for all other messages. If you specify a list of transports the messages will be routed to all of them. For more information on this check the [Symfony docs](https://symfony.com/doc/current/messenger.html#routing-messages-to-a-transport).

### Admin worker

::: warning
The `transports` option can only be configured with the `low_priority` transport if you are on version 6.5.7.0 or above. You must not add the `low_priority` transport in lower versions, as the admin worker will fail when it tries to consume a non-existent transport.
:::

The admin-worker can be configured or disabled in the general `shopware.yml` configuration. If you want to use the admin worker you have to specify each transport, that previously was configured. The poll interval is the time in seconds that the admin-worker polls messages from the queue. After the poll-interval is over the request terminates and the Administration initiates a new request.

```yaml
// <platform root>/src/Core/Framework/Resources/config/packages/shopware.yaml
shopware:
    admin_worker:
        enable_admin_worker: true
        poll_interval: 30
        transports: ["async", "low_priority"]
```

## Next steps

Now that you know how to add a message handler and configure a bus for it, you may want to add a custom middleware for your bus. To do this, head over to [Add middleware](add-middleware) guide.

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/framework/message-queue/add-message-handler.md
---

# Add message handler

## Overview

::: warning
Parts of this guide refer to the `low_priority` queue, which is only available in version 6.5.7.0 and above. Configuring the messenger to consume this queue will fail if it does not exist.
:::

In this guide you'll learn how to create a message handler.

A [handler](https://symfony.com/doc/current/messenger.html#creating-a-message-handler) gets called once the message is dispatched by the `handle_messages` middleware. Handlers do the actual processing of the message.

## Prerequisites

As most guides, this guide is also built upon the [Plugin base guide](../../plugin-base-guide), but you don't necessarily need that. It will use an example message, so if you don't know how to add a custom message yet, have a look at our guide about [Adding a message to queue](add-message-to-queue). Furthermore, registering classes or services to the DI container is also not explained here, but it's covered in our guide about [Dependency injection](../../plugin-fundamentals/dependency-injection), so having this open in another tab won't hurt.

## Handling messages

First, we have to create a new class which we will name `SmsHandler` in this example. To mark the class as message handler, we use the php attribute `#[AsMessageHandler]` and implement the method `__invoke`. We can also define multiple handlers for the same message. To register a handler, we have to tag it with the `messenger.message_handler` tag.

```php
// <plugin root>/src/MessageQueue/Handler/SmsHandler.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\MessageQueue\Handler;

use Symfony\Component\Messenger\Attribute\AsMessageHandler;
use Swag\BasicExample\MessageQueue\Message\SmsNotification;

#[AsMessageHandler]
class SmsHandler
{
    public function __invoke(SmsNotification $message)
    {
        // ... do some work - like sending an SMS message!
    }
}
```

## Next steps

Now that you know how to add a message handler, you may want to add a custom middleware for your bus. To do this, head over to [Add middleware](add-middleware) guide.

If you want to learn more about configuring the message queue, have a look at the [Message queue hosting guide](../../../../hosting/infrastructure/message-queue.md).

---

---
url: /docs/guides/plugins/plugins/framework/message-queue/add-message-handler.md
---

# Add Message Handler

## Overview

::: warning
Parts of this guide refer to the `low_priority` queue, which is only available in version 6.5.7.0 and above. Configuring the messenger to consume this queue will fail if it does not exist.
:::

In this guide you'll learn how to create a message handler.

A [handler](https://symfony.com/doc/current/messenger.html#creating-a-message-handler) gets called once the message is dispatched by the `handle_messages` middleware. Handlers do the actual processing of the message.

## Prerequisites

As most guides, this guide is also built upon the [Plugin base guide](../../plugin-base-guide.md), but you don't necessarily need that. It will use an example message, so if you don't know how to add a custom message yet, have a look at our guide about [Adding a message to queue](add-message-to-queue.md). Furthermore, registering classes or services to the DI container is also not explained here, but it's covered in our guide about [Dependency injection](../../services/dependency-injection.md), so having this open in another tab won't hurt.

## Handling messages

First, we have to create a new class which we will name `SmsHandler` in this example. To mark the class as message handler, we use the php attribute `#[AsMessageHandler]` and implement the method `__invoke`. We can also define multiple handlers for the same message. To register a handler, we have to tag it with the `messenger.message_handler` tag.

```php
// <plugin root>/src/MessageQueue/Handler/SmsHandler.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\MessageQueue\Handler;

use Symfony\Component\Messenger\Attribute\AsMessageHandler;
use Swag\BasicExample\MessageQueue\Message\SmsNotification;

#[AsMessageHandler]
class SmsHandler
{
    public function __invoke(SmsNotification $message)
    {
        // ... do some work - like sending an SMS message!
    }
}
```

## Next steps

Now that you know how to add a message handler, you may want to add a custom middleware for your bus. To do this, head over to [Add middleware](add-middleware.md) guide.

If you want to learn more about configuring the message queue, have a look at the [Message queue hosting guide](../../../../hosting/infrastructure/message-queue.md).

---

---
url: >-
  /docs/v6.5/guides/plugins/plugins/framework/message-queue/add-message-to-queue.md
---

# Add message to queue

## Overview

::: warning
Parts of this guide refer to the `low_priority` queue and the corresponding `LowPriorityMessageInterface`, which is only available in version 6.5.7.0 and above. Configuring the messenger to consume this queue will fail if it does not exist.
:::

In this guide you'll learn how to create a message and add it to the queue.

Shopware integrates with the [Symfony Messenger](https://symfony.com/doc/current/components/messenger.html) component and [Enqueue](https://enqueue.forma-pro.com/). This gives you the possibility to send and handle asynchronous messages.

A [message](https://symfony.com/doc/current/messenger.html#creating-a-message-handler) is a simple PHP object that you want to dispatch over the MessageQueue. It must be serializable and should contain all necessary information that your handlers need to process the message.

It will be wrapped in an [envelope](https://symfony.com/doc/current/components/messenger.html#adding-metadata-to-messages-envelopes) by the message bus that dispatches the message.

## Prerequisites

As most guides, this guide is also built upon the [Plugin base guide](../../plugin-base-guide), but you don't necessarily need that. It will use an example service, so if you don't know how to add a custom service yet, have a look at our guide about [Adding a custom service](../../plugin-fundamentals/add-custom-service). Furthermore, registering classes or services to the DI container is also not explained here, but it's covered in our guide about [Dependency injection](../../plugin-fundamentals/dependency-injection), so having this open in another tab won't hurt.

## Create a message

First, we have to create a new message class in the directory `<plugin root>/MessageQueue/Message`. In this example, we create a `SmsNotification` that contains a string with content. By default, all messages are handled synchronously. To change the behavior to asynchronously, we have to implement the `AsyncMessageInterface` interface. For messages which should also be handled asynchronously but with a lower priority, implement the `LowPriorityMessageInterface` interface.

Here's an example:

```php
// <plugin root>/src/MessageQueue/Message/SmsNotification.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\MessageQueue\Message;

use Shopware\Core\Framework\MessageQueue\AsyncMessageInterface;

class SmsNotification implements AsyncMessageInterface
{
    private string $content;

    public function __construct(string $content)
    {
        $this->content = $content;
    }

    public function getContent(): string
    {
        return $this->content;
    }
}
```

## Send a message

After we've created our notification, we will create a service that will send our `SmsNotification`. We will name this service `ExampleSender`. In this service we need to inject the `Symfony\Component\Messenger\MessageBusInterface`, that is needed to send the message through the desired bus, which is called `messenger.bus.shopware`.

```php
// <plugin root>/src/Service/ExampleSender.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Swag\BasicExample\MessageQueue\Message\SmsNotification;
use Symfony\Component\Messenger\MessageBusInterface;

class ExampleSender
{
    private MessageBusInterface $bus;

    public function __construct(MessageBusInterface $bus)
    {
        $this->bus = $bus;
    }

    public function sendMessage(string $message): void
    {
        $this->bus->dispatch(new SmsNotification($message));
    }
}
```

If we want to add metadata to our message, we can dispatch an `Symfony\Component\Messenger\Envelope` in our service instead with the necessary [stamps](https://symfony.com/doc/current/components/messenger.html#adding-metadata-to-messages-envelopes). In this example below, we use the `Symfony\Component\Messenger\Stamp\DelayStamp`, which tells the queue to process the message later.

```php
// <plugin root>/src/Service/ExampleSender.php
public function sendMessage(string $message): void
{
    $message = new SmsNotification($message);
    $this->bus->dispatch(
        (new Envelope($message))
            ->with(new DelayStamp(5000))
    );
}
```

## Lower the priority for specific async messages

You might consider using the new `low_priority` queue if you are dispatching messages that do not need to be handled immediately. To configure specific messages to be transported via the `low_priority` queue, you need to either adjust the routing or implement the `LowPriorityMessageInterface` as already mentioned:

```yaml
# config/packages/framework.yaml
framework:
    messenger:
        routing:
            'Your\Custom\Message': low_priority
```

## Override transport for specific messages

If you explicitly configure a message to be transported via the `async` (default) queue, even though it implements the `LowPriorityMessageInterface`, which would usually be transported via the `low_priority` queue, the transport is overridden for this specific message.

Example:

```php
// <plugin root>/src/MessageQueue/Message/LowPriorityMessage.php
<?php declare(strict_types=1);

namespace Your\Custom;

use Shopware\Core\Framework\MessageQueue\LowPriorityMessageInterface;

class LowPriorityMessage implements LowPriorityMessageInterface
{
}
```

```yaml
# config/packages/framework.yaml
framework:
    messenger:
        routing:
            'Shopware\Core\Framework\MessageQueue\LowPriorityMessageInterface': low_priority
            'Your\Custom\LowPriorityMessage': async
```

## Encrypted messages

As the sent messages may travel through some 3rd party services you may want to encrypt messages containing sensible information. To send encrypted messages simply use the `encrypted.messenger.bus.shopware` rather than the `messenger.bus.shopware` message bus. The encrypted bus will handle encryption and decryption for you.

```html
// <plugin root>/src/Resources/config/services.xml
<service id="Swag\BasicExample\Service\ExampleSender">
    <argument type="service" id="encrypted.messenger.bus.shopware"/>
</service>
```

## Next steps

Now that you know how to create a message and add it to the queue, let's create a handler to process our message. To do this, head over to [Add message handler](add-message-handler) guide.

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/framework/message-queue/add-message-to-queue.md
---

# Add message to queue

## Overview

::: warning
Parts of this guide refer to the `low_priority` queue and the corresponding `LowPriorityMessageInterface`, which is only available in version 6.5.7.0 and above. Configuring the messenger to consume this queue will fail if it does not exist.
:::

In this guide you'll learn how to create a message and add it to the queue.

Shopware integrates with the [Symfony Messenger](https://symfony.com/doc/current/components/messenger.html) component and [Enqueue](https://enqueue.forma-pro.com/). This gives you the possibility to send and handle asynchronous messages.

A [message](https://symfony.com/doc/current/messenger.html#creating-a-message-handler) is a simple PHP object that you want to dispatch over the MessageQueue. It must be serializable and should contain all necessary information that your handlers need to process the message.

It will be wrapped in an [envelope](https://symfony.com/doc/current/components/messenger.html#adding-metadata-to-messages-envelopes) by the message bus that dispatches the message.

## Prerequisites

As most guides, this guide is also built upon the [Plugin base guide](../../plugin-base-guide), but you don't necessarily need that. It will use an example service, so if you don't know how to add a custom service yet, have a look at our guide about [Adding a custom service](../../plugin-fundamentals/add-custom-service). Furthermore, registering classes or services to the DI container is also not explained here, but it's covered in our guide about [Dependency injection](../../plugin-fundamentals/dependency-injection), so having this open in another tab won't hurt.

## Create a message

First, we have to create a new message class in the directory `<plugin root>/MessageQueue/Message`. In this example, we create a `SmsNotification` that contains a string with content. By default, all messages are handled synchronously. To change the behavior to asynchronously, we have to implement the `AsyncMessageInterface` interface. For messages which should also be handled asynchronously but with a lower priority, implement the `LowPriorityMessageInterface` interface.

Here's an example:

```php
// <plugin root>/src/MessageQueue/Message/SmsNotification.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\MessageQueue\Message;

use Shopware\Core\Framework\MessageQueue\AsyncMessageInterface;

class SmsNotification implements AsyncMessageInterface
{
    private string $content;

    public function __construct(string $content)
    {
        $this->content = $content;
    }

    public function getContent(): string
    {
        return $this->content;
    }
}
```

## Send a message

After we've created our notification, we will create a service that will send our `SmsNotification`. We will name this service `ExampleSender`. In this service we need to inject the `Symfony\Component\Messenger\MessageBusInterface`, that is needed to send the message through the desired bus, which is called `messenger.default_bus`.

```php
// <plugin root>/src/Service/ExampleSender.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Swag\BasicExample\MessageQueue\Message\SmsNotification;
use Symfony\Component\Messenger\MessageBusInterface;

class ExampleSender
{
    private MessageBusInterface $bus;

    public function __construct(MessageBusInterface $bus)
    {
        $this->bus = $bus;
    }

    public function sendMessage(string $message): void
    {
        $this->bus->dispatch(new SmsNotification($message));
    }
}
```

If we want to add metadata to our message, we can dispatch an `Symfony\Component\Messenger\Envelope` in our service instead with the necessary [stamps](https://symfony.com/doc/current/components/messenger.html#adding-metadata-to-messages-envelopes). In this example below, we use the `Symfony\Component\Messenger\Stamp\DelayStamp`, which tells the queue to process the message later.

```php
// <plugin root>/src/Service/ExampleSender.php
public function sendMessage(string $message): void
{
    $message = new SmsNotification($message);
    $this->bus->dispatch(
        (new Envelope($message))
            ->with(new DelayStamp(5000))
    );
}
```

## Lower the priority for specific async messages

You might consider using the new `low_priority` queue if you are dispatching messages that do not need to be handled immediately. To configure specific messages to be transported via the `low_priority` queue, you need to either adjust the routing or implement the `LowPriorityMessageInterface` as already mentioned:

```yaml
# config/packages/shopware.yaml
shopware:
    messenger:
        routing_overwrite:
            'Your\Custom\Message': low_priority
```

## Override transport for specific messages

If you explicitly configure a message to be transported via the `async` (default) queue, even though it implements the `LowPriorityMessageInterface`, which would usually be transported via the `low_priority` queue, the transport is overridden for this specific message.

Example:

```php
// <plugin root>/src/MessageQueue/Message/LowPriorityMessage.php
<?php declare(strict_types=1);

namespace Your\Custom;

use Shopware\Core\Framework\MessageQueue\LowPriorityMessageInterface;

class LowPriorityMessage implements LowPriorityMessageInterface
{
}
```

```yaml
# config/packages/shopware.yaml
shopware:
    messenger:
        routing_overwrite:
            'Shopware\Core\Framework\MessageQueue\LowPriorityMessageInterface': low_priority
            'Your\Custom\LowPriorityMessage': async
```

## Next steps

Now that you know how to create a message and add it to the queue, let's create a handler to process our message. To do this, head over to [Add message handler](add-message-handler) guide.

---

---
url: /docs/guides/plugins/plugins/framework/message-queue/add-message-to-queue.md
---

# Add Message to Queue

## Overview

::: warning
Parts of this guide refer to the `low_priority` queue and the corresponding `LowPriorityMessageInterface`, which is only available in version 6.5.7.0 and above. Configuring the messenger to consume this queue will fail if it does not exist.
:::

In this guide you'll learn how to create a message and add it to the queue.

Shopware integrates with the [Symfony Messenger](https://symfony.com/doc/current/components/messenger.html) component and [Enqueue](https://enqueue.forma-pro.com/). This gives you the possibility to send and handle asynchronous messages.

A [message](https://symfony.com/doc/current/messenger.html#creating-a-message-handler) is a simple PHP object that you want to dispatch over the MessageQueue. It must be serializable and should contain all necessary information that your handlers need to process the message.

It will be wrapped in an [envelope](https://symfony.com/doc/current/components/messenger.html#adding-metadata-to-messages-envelopes) by the message bus that dispatches the message.

## Prerequisites

As most guides, this guide is also built upon the [Plugin base guide](../../plugin-base-guide.md), but you don't necessarily need that. It will use an example service, so if you don't know how to add a custom service yet, have a look at our guide about [Adding a custom service](../../services/add-custom-service.md). Furthermore, registering classes or services to the DI container is also not explained here, but it's covered in our guide about [Dependency injection](../../services/dependency-injection.md), so having this open in another tab won't hurt.

## Create a message

First, we have to create a new message class in the directory `<plugin root>/MessageQueue/Message`. In this example, we create a `SmsNotification` that contains a string with content. By default, all messages are handled synchronously. To change the behavior to asynchronously, we have to implement the `AsyncMessageInterface` interface. For messages which should also be handled asynchronously but with a lower priority, implement the `LowPriorityMessageInterface` interface.

Here's an example:

```php
// <plugin root>/src/MessageQueue/Message/SmsNotification.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\MessageQueue\Message;

use Shopware\Core\Framework\MessageQueue\AsyncMessageInterface;

class SmsNotification implements AsyncMessageInterface
{
    private string $content;

    public function __construct(string $content)
    {
        $this->content = $content;
    }

    public function getContent(): string
    {
        return $this->content;
    }
}
```

## Send a message

After we've created our notification, we will create a service that will send our `SmsNotification`. We will name this service `ExampleSender`. In this service we need to inject the `Symfony\Component\Messenger\MessageBusInterface`, that is needed to send the message through the desired bus, which is called `messenger.default_bus`.

```php
// <plugin root>/src/Service/ExampleSender.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Swag\BasicExample\MessageQueue\Message\SmsNotification;
use Symfony\Component\Messenger\MessageBusInterface;

class ExampleSender
{
    private MessageBusInterface $bus;

    public function __construct(MessageBusInterface $bus)
    {
        $this->bus = $bus;
    }

    public function sendMessage(string $message): void
    {
        $this->bus->dispatch(new SmsNotification($message));
    }
}
```

If we want to add metadata to our message, we can dispatch an `Symfony\Component\Messenger\Envelope` in our service instead with the necessary [stamps](https://symfony.com/doc/current/components/messenger.html#adding-metadata-to-messages-envelopes). In this example below, we use the `Symfony\Component\Messenger\Stamp\DelayStamp`, which tells the queue to process the message later.

```php
// <plugin root>/src/Service/ExampleSender.php
public function sendMessage(string $message): void
{
    $message = new SmsNotification($message);
    $this->bus->dispatch(
        (new Envelope($message))
            ->with(new DelayStamp(5000))
    );
}
```

## Lower the priority for specific async messages

You might consider using the new `low_priority` queue if you are dispatching messages that do not need to be handled immediately. To configure specific messages to be transported via the `low_priority` queue, you need to either adjust the routing or implement the `LowPriorityMessageInterface` as already mentioned:

```yaml
# config/packages/shopware.yaml
shopware:
    messenger:
        routing_overwrite:
            'Your\Custom\Message': low_priority
```

## Override transport for specific messages

If you explicitly configure a message to be transported via the `async` (default) queue, even though it implements the `LowPriorityMessageInterface`, which would usually be transported via the `low_priority` queue, the transport is overridden for this specific message.

Example:

```php
// <plugin root>/src/MessageQueue/Message/LowPriorityMessage.php
<?php declare(strict_types=1);

namespace Your\Custom;

use Shopware\Core\Framework\MessageQueue\LowPriorityMessageInterface;

class LowPriorityMessage implements LowPriorityMessageInterface
{
}
```

```yaml
# config/packages/shopware.yaml
shopware:
    messenger:
        routing_overwrite:
            'Shopware\Core\Framework\MessageQueue\LowPriorityMessageInterface': low_priority
            'Your\Custom\LowPriorityMessage': async
```

## Next steps

Now that you know how to create a message and add it to the queue, let's create a handler to process our message. To do this, head over to [Add message handler](add-message-handler.md) guide.

---

---
url: /docs/guides/plugins/plugins/framework/message-queue/add-middleware.md
---

# Add Middleware

## Overview

In this guide you will learn how to add a custom middleware.

A [Middleware](https://symfony.com/doc/current/messenger.html#middleware) is called when the message bus dispatches messages. The middleware defines what happens when you dispatch a message. For example the `send_message` middleware is responsible for sending your message to the configured transport and the `handle_message` middleware will actually call your handlers for the given message.

## Prerequisites

As most guides, this guide is also built upon the [Plugin base guide](../../plugin-base-guide.md), but you don't necessarily need that. Furthermore, registering classes or services to the DI container is also not explained here, but it's covered in our guide about [Dependency injection](../../services/dependency-injection.md), so having this open in another tab won't hurt.

## Create middleware

First we need to create a new service that implements the `MiddlewareInterface`. This interface comes with a method `handle`, which should always call the next middleware.

```php
// <plugin root>/src/MessageQueue/Middleware/ExampleMiddleware.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\MessageQueue\Middleware;

use Symfony\Component\Messenger\Envelope;
use Symfony\Component\Messenger\Middleware\MiddlewareInterface;
use Symfony\Component\Messenger\Middleware\StackInterface;

class ExampleMiddleware implements MiddlewareInterface
{
    public function handle(Envelope $envelope, StackInterface $stack): Envelope
    {
        // do something here

        // don't forget to call the next middleware
        return $stack->next()->handle($envelope, $stack);
    }
}
```

## Configure middleware

After we've created our middleware, we have to add that middleware to the message bus through configuration.

For each defined bus in our `framework.yaml`, we can define the middleware that this bus should use. To add middleware, we simply specify our custom middleware as follows:

```yaml
// <platform root>/src/Core/Framework/Resources/config/packages/framework.yaml
framework:
    messenger:
        buses:
          messenger.bus.default:
            middleware:
              - 'Swag\BasicExample\MessageQueue\Middleware\ExampleMiddleware'
              - 'Swag\BasicExample\MessageQueue\Middleware\AnotherExampleMiddleware'
```

## More interesting topics

* [Message Queue](add-message-to-queue.md)
* [Message Handler](add-message-handler.md)

---

---
url: /docs/v6.5/guides/plugins/plugins/framework/message-queue/add-middleware.md
---

# Add Middleware

## Overview

In this guide you will learn how to add a custom middleware.

A [Middleware](https://symfony.com/doc/current/messenger.html#middleware) is called when the message bus dispatches messages. The middleware defines what happens when you dispatch a message. For example the `send_message` middleware is responsible for sending your message to the configured transport and the `handle_message` middleware will actually call your handlers for the given message.

## Prerequisites

As most guides, this guide is also built upon the [Plugin base guide](../../plugin-base-guide), but you don't necessarily need that. Furthermore, registering classes or services to the DI container is also not explained here, but it's covered in our guide about [Dependency injection](../../plugin-fundamentals/dependency-injection), so having this open in another tab won't hurt.

## Create middleware

First we need to create a new service that implements the `MiddlewareInterface`. This interface comes with a method `handle`, which should always call the next middleware.

```php
// <plugin root>/src/MessageQueue/Middleware/ExampleMiddleware.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\MessageQueue\Middleware;

use Symfony\Component\Messenger\Envelope;
use Symfony\Component\Messenger\Middleware\MiddlewareInterface;
use Symfony\Component\Messenger\Middleware\StackInterface;

class ExampleMiddleware implements MiddlewareInterface
{
    public function handle(Envelope $envelope, StackInterface $stack): Envelope
    {
        // do something here

        // don't forget to call the next middleware
        return $stack->next()->handle($envelope, $stack);
    }
}
```

## Configure middleware

After we've created our middleware, we have to add that middleware to the message bus through configuration.

For each defined bus in our `framework.yaml`, we can define the middleware that this bus should use. To add middleware, we simply specify our custom middleware as follows:

```yaml
// <platform root>/src/Core/Framework/Resources/config/packages/framework.yaml
framework:
    messenger:
        default_bus: messenger.bus.shopware
        buses:
            messenger.bus.default:
              middleware:
                - 'Swag\BasicExample\MessageQueue\Middleware\ExampleMiddleware'
                - 'Swag\BasicExample\MessageQueue\Middleware\AnotherExampleMiddleware'
```

## More interesting topics

* [Message Queue](add-message-to-queue)
* [Message Handler](add-message-handler)

---

---
url: /docs/v6.6/guides/plugins/plugins/framework/message-queue/add-middleware.md
---

# Add Middleware

## Overview

In this guide you will learn how to add a custom middleware.

A [Middleware](https://symfony.com/doc/current/messenger.html#middleware) is called when the message bus dispatches messages. The middleware defines what happens when you dispatch a message. For example the `send_message` middleware is responsible for sending your message to the configured transport and the `handle_message` middleware will actually call your handlers for the given message.

## Prerequisites

As most guides, this guide is also built upon the [Plugin base guide](../../plugin-base-guide), but you don't necessarily need that. Furthermore, registering classes or services to the DI container is also not explained here, but it's covered in our guide about [Dependency injection](../../plugin-fundamentals/dependency-injection), so having this open in another tab won't hurt.

## Create middleware

First we need to create a new service that implements the `MiddlewareInterface`. This interface comes with a method `handle`, which should always call the next middleware.

```php
// <plugin root>/src/MessageQueue/Middleware/ExampleMiddleware.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\MessageQueue\Middleware;

use Symfony\Component\Messenger\Envelope;
use Symfony\Component\Messenger\Middleware\MiddlewareInterface;
use Symfony\Component\Messenger\Middleware\StackInterface;

class ExampleMiddleware implements MiddlewareInterface
{
    public function handle(Envelope $envelope, StackInterface $stack): Envelope
    {
        // do something here

        // don't forget to call the next middleware
        return $stack->next()->handle($envelope, $stack);
    }
}
```

## Configure middleware

After we've created our middleware, we have to add that middleware to the message bus through configuration.

For each defined bus in our `framework.yaml`, we can define the middleware that this bus should use. To add middleware, we simply specify our custom middleware as follows:

```yaml
// <platform root>/src/Core/Framework/Resources/config/packages/framework.yaml
framework:
    messenger:
        buses:
          messenger.bus.default:
            middleware:
              - 'Swag\BasicExample\MessageQueue\Middleware\ExampleMiddleware'
              - 'Swag\BasicExample\MessageQueue\Middleware\AnotherExampleMiddleware'
```

## More interesting topics

* [Message Queue](add-message-to-queue)
* [Message Handler](add-message-handler)

---

---
url: >-
  /docs/products/extensions/advanced-search/How-to-add-more-fields-to-product-search.md
---

# Add more Fields to Product Search

You can add more searchable fields into your product or any Elasticsearch definition.

In this example, we create a field called `productNumberPrefix` to make it searchable. This requires 3 steps:

**1. Decorate the ElasticsearchDefinition**

```php
$services->set(YourPluginNameSpace\ElasticsearchProductDefinitionDecorator::class)
    ->decorate(Shopware\Elasticsearch\Product\ElasticsearchProductDefinition::class)
    ->args([
        service('.inner'),
        service(Shopware\Commercial\AdvancedSearch\Domain\Search\SearchLogic::class),
    ]);
```

```php
<?php declare(strict_types=1);

namespace YourPluginNameSpace;

use OpenSearchDSL\Query\Compound\BoolQuery;
use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Elasticsearch\Framework\AbstractElasticsearchDefinition;

class ElasticsearchProductDefinitionDecorator extends AbstractElasticsearchDefinition
{
    public function __construct(
        private readonly AbstractElasticsearchDefinition $decorated
    ) {
    }

    public function getEntityDefinition(): EntityDefinition
    {
        return $this->decorated->getEntityDefinition();
    }

    public function buildTermQuery(Context $context, Criteria $criteria): BoolQuery
    {
        return $this->decorated->buildTermQuery($context, $criteria);
    }

    public function getMapping(Context $context): array
    {
        $mappings = $this->decorated->getMapping($context);

        $additionalMappings = [
            // define your new field's type
            'prefixProductNumber' => self::KEYWORD_FIELD,
            // other additional fields
        ];

        $mappings['properties'] = array_merge($mappings['properties'], $additionalMappings);

        return $mappings;
    }

    public function fetch(array $ids, Context $context): array
    {
        $data = $this->decorated->fetch($ids, $context);

        $documents = [];

        foreach ($data as $id => $document) {
            $document = array_merge($document, [
                // get first 5 characters from productNumber to index it
                'prefixProductNumber' => substr($document['productNumber'], 0, 5),
            ]);

            $documents[$id] = $document;
        }

        return $documents;
    }
}
```

**2. Run the commands:**

We need to update these data mapping to the Opensearch's server to make the change effective:

```bash
// Update the Elasticsearch indices mapping, introduce since 6.5.4.0
bin/console es:mapping:update

// Assume the new field data are already set in products, otherwise you don't need to reindex
bin/console es:index --no-queue
```

**3. Insert new fields to advanced\_search\_config\_field of the search entity**

So now the data is mapped and indexed, we need to make it searchable by adding the new field into the search config. Create a new migration and make sure it is run by reinstalling or updating the plugin:

```bash
bin/console database:create-migration --name AddNewPrefixProductNumberFieldIntoProductAdvancedSearch --plugin YourPlugin
```

```php
<?php declare(strict_types=1);

namespace YourPluginNameSpace\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Commercial\AdvancedSearch\Entity\AdvancedSearchConfig\Aggregate\AdvancedSearchConfigFieldDefinition;
use Shopware\Core\Content\Product\ProductDefinition;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Framework\Uuid\Uuid;

class Migration1692954529AddNewPrefixProductNumberFieldIntoProductAdvancedSearch extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1692954529;
    }

    public function update(Connection $connection): void
    {
        $configSalesChannelIds = $connection->fetchFirstColumn('SELECT id FROM advanced_search_config');

        $createdAt = (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT);

        foreach ($configSalesChannelIds as $configSalesChannelId) {
            $connection->insert(AdvancedSearchConfigFieldDefinition::ENTITY_NAME, [
                'id' => Uuid::randomBytes(),
                'field' => 'prefixProductNumber',
                'config_id' => $configSalesChannelId,
                'entity' => ProductDefinition::ENTITY_NAME,
                'tokenize' => 1,
                'searchable' => 1,
                'ranking' => 500,
                'created_at' => $createdAt,
            ]);
        }
    }
}
```

---

---
url: >-
  /docs/v6.5/products/extensions/advanced-search/How-to-add-more-fields-to-product-search.md
---

# Add more Fields to Product Search

You can add more searchable fields into your product or any Elasticsearch definition.

In this example, we create a field called `productNumberPrefix` to make it searchable. This requires 3 steps:

**1. Decorate the ElasticsearchDefinition**

```xml
<service id="YourPluginNameSpace\ElasticsearchProductDefinitionDecorator" decorates="Shopware\Elasticsearch\Product\ElasticsearchProductDefinition">
    <argument type="service" id=".inner"/>
    <argument type="service" id="Shopware\Commercial\AdvancedSearch\Domain\Search\SearchLogic"/>
</service>
```

```php
<?php declare(strict_types=1);

namespace YourPluginNameSpace;

use OpenSearchDSL\Query\Compound\BoolQuery;
use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Elasticsearch\Framework\AbstractElasticsearchDefinition;

class ElasticsearchProductDefinitionDecorator extends AbstractElasticsearchDefinition
{
    public function __construct(
        private readonly AbstractElasticsearchDefinition $decorated
    ) {
    }

    public function getEntityDefinition(): EntityDefinition
    {
        return $this->decorated->getEntityDefinition();
    }

    public function buildTermQuery(Context $context, Criteria $criteria): BoolQuery
    {
        return $this->decorated->buildTermQuery($context, $criteria);
    }

    public function getMapping(Context $context): array
    {
        $mappings = $this->decorated->getMapping($context);

        $additionalMappings = [
            // define your new field's type
            'prefixProductNumber' => self::KEYWORD_FIELD,
            // other additional fields
        ];

        $mappings['properties'] = array_merge($mappings['properties'], $additionalMappings);

        return $mappings;
    }

    public function fetch(array $ids, Context $context): array
    {
        $data = $this->decorated->fetch($ids, $context);

        $documents = [];

        foreach ($data as $id => $document) {
            $document = array_merge($document, [
                // get first 5 characters from productNumber to index it
                'prefixProductNumber' => substr($document['productNumber'], 0, 5),
            ]);

            $documents[$id] = $document;
        }

        return $documents;
    }
}
```

**2. Run the commands:**

We need to update these data mapping to the Opensearch's server to make the change effective:

```bash
// Update the Elasticsearch indices mapping, introduce since 6.5.4.0
bin/console es:mapping:update

// Assume the new field data are already set in products, otherwise you don't need to reindex
bin/console es:index --no-queue
```

**3. Insert new fields to advanced\_search\_config\_field of the search entity**

So now the data is mapped and indexed, we need to make it searchable by adding the new field into the search config. Create a new migration and make sure it is run by reinstalling or updating the plugin:

```bash
bin/console database:create-migration --name AddNewPrefixProductNumberFieldIntoProductAdvancedSearch --plugin YourPlugin
```

```php
<?php declare(strict_types=1);

namespace YourPluginNameSpace\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Commercial\AdvancedSearch\Entity\AdvancedSearchConfig\Aggregate\AdvancedSearchConfigFieldDefinition;
use Shopware\Core\Content\Product\ProductDefinition;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Framework\Uuid\Uuid;

class Migration1692954529AddNewPrefixProductNumberFieldIntoProductAdvancedSearch extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1692954529;
    }

    public function update(Connection $connection): void
    {
        $configSalesChannelIds = $connection->fetchFirstColumn('SELECT id FROM advanced_search_config');

        $createdAt = (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT);

        foreach ($configSalesChannelIds as $configSalesChannelId) {
            $connection->insert(AdvancedSearchConfigFieldDefinition::ENTITY_NAME, [
                'id' => Uuid::randomBytes(),
                'field' => 'prefixProductNumber',
                'config_id' => $configSalesChannelId,
                'entity' => ProductDefinition::ENTITY_NAME,
                'tokenize' => 1,
                'searchable' => 1,
                'ranking' => 500,
                'created_at' => $createdAt,
            ]);
        }
    }
}
```

---

---
url: >-
  /docs/v6.6/products/extensions/advanced-search/How-to-add-more-fields-to-product-search.md
---

# Add more Fields to Product Search

You can add more searchable fields into your product or any Elasticsearch definition.

In this example, we create a field called `productNumberPrefix` to make it searchable. This requires 3 steps:

**1. Decorate the ElasticsearchDefinition**

```xml
<service id="YourPluginNameSpace\ElasticsearchProductDefinitionDecorator" decorates="Shopware\Elasticsearch\Product\ElasticsearchProductDefinition">
    <argument type="service" id=".inner"/>
    <argument type="service" id="Shopware\Commercial\AdvancedSearch\Domain\Search\SearchLogic"/>
</service>
```

```php
<?php declare(strict_types=1);

namespace YourPluginNameSpace;

use OpenSearchDSL\Query\Compound\BoolQuery;
use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Elasticsearch\Framework\AbstractElasticsearchDefinition;

class ElasticsearchProductDefinitionDecorator extends AbstractElasticsearchDefinition
{
    public function __construct(
        private readonly AbstractElasticsearchDefinition $decorated
    ) {
    }

    public function getEntityDefinition(): EntityDefinition
    {
        return $this->decorated->getEntityDefinition();
    }

    public function buildTermQuery(Context $context, Criteria $criteria): BoolQuery
    {
        return $this->decorated->buildTermQuery($context, $criteria);
    }

    public function getMapping(Context $context): array
    {
        $mappings = $this->decorated->getMapping($context);

        $additionalMappings = [
            // define your new field's type
            'prefixProductNumber' => self::KEYWORD_FIELD,
            // other additional fields
        ];

        $mappings['properties'] = array_merge($mappings['properties'], $additionalMappings);

        return $mappings;
    }

    public function fetch(array $ids, Context $context): array
    {
        $data = $this->decorated->fetch($ids, $context);

        $documents = [];

        foreach ($data as $id => $document) {
            $document = array_merge($document, [
                // get first 5 characters from productNumber to index it
                'prefixProductNumber' => substr($document['productNumber'], 0, 5),
            ]);

            $documents[$id] = $document;
        }

        return $documents;
    }
}
```

**2. Run the commands:**

We need to update these data mapping to the Opensearch's server to make the change effective:

```bash
// Update the Elasticsearch indices mapping, introduce since 6.5.4.0
bin/console es:mapping:update

// Assume the new field data are already set in products, otherwise you don't need to reindex
bin/console es:index --no-queue
```

**3. Insert new fields to advanced\_search\_config\_field of the search entity**

So now the data is mapped and indexed, we need to make it searchable by adding the new field into the search config. Create a new migration and make sure it is run by reinstalling or updating the plugin:

```bash
bin/console database:create-migration --name AddNewPrefixProductNumberFieldIntoProductAdvancedSearch --plugin YourPlugin
```

```php
<?php declare(strict_types=1);

namespace YourPluginNameSpace\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Commercial\AdvancedSearch\Entity\AdvancedSearchConfig\Aggregate\AdvancedSearchConfigFieldDefinition;
use Shopware\Core\Content\Product\ProductDefinition;
use Shopware\Core\Defaults;
use Shopware\Core\Framework\Migration\MigrationStep;
use Shopware\Core\Framework\Uuid\Uuid;

class Migration1692954529AddNewPrefixProductNumberFieldIntoProductAdvancedSearch extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1692954529;
    }

    public function update(Connection $connection): void
    {
        $configSalesChannelIds = $connection->fetchFirstColumn('SELECT id FROM advanced_search_config');

        $createdAt = (new \DateTime())->format(Defaults::STORAGE_DATE_TIME_FORMAT);

        foreach ($configSalesChannelIds as $configSalesChannelId) {
            $connection->insert(AdvancedSearchConfigFieldDefinition::ENTITY_NAME, [
                'id' => Uuid::randomBytes(),
                'field' => 'prefixProductNumber',
                'config_id' => $configSalesChannelId,
                'entity' => ProductDefinition::ENTITY_NAME,
                'tokenize' => 1,
                'searchable' => 1,
                'ranking' => 500,
                'created_at' => $createdAt,
            ]);
        }
    }
}
```

---

---
url: >-
  /docs/resources/references/adr/2024-07-31-add-more-unit-tests-namespaces-to-featureflag-extension.md
---

# Add more unit tests namespaces to FeatureFlag extension

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2024-07-31-add-more-unit-tests-namespaces-to-featureflag-extension.md)
:::

## Context

The `Shopware\Core\Test\PHPUnit\Extension\FeatureFlag\Subscriber\TestPreparationStartedSubscriber` only allows
the `Shopware\Tests\Unit` namespace to be considered when enabling the major feature in the unit tests suite.

## Decision

To be able to unit test the upcoming major feature in other plugins we will enable the possibility to add other
namespaces to
the `Shopware\Core\Test\PHPUnit\Extension\FeatureFlag\Subscriber\TestPreparationStartedSubscriber`.

We'll add a static method called `addNamespace()` method to the
`Shopware\Core\Test\PHPUnit\Extension\FeatureFlag\FeatureFlagExtension` and by this we are able to add other namespaces
to the allowlist of the namespaces to be considered when enabling the major flags in the unit test suite.

This can be useful for plugins that wants to enable the major flags in their unit tests suite.

Therefore, add the extension to the extension list in the `phpunit.xml`:

```xml

<extensions>
    ...
    <bootstrap class="Shopware\Core\Test\PHPUnit\Extension\FeatureFlag\FeatureFlagExtension"/>
</extensions>
```

And register your test namespace in your test bootstrap file:

```php
FeatureFlagExtension::addTestNamespace('Your\\Unit\\Tests\\Namespace\\');
```

For example, in the Commercial plugin, we added the following code to the `tests/TestBootstrap.php` file:

```php
FeatureFlagExtension::addTestNamespace('Shopware\\Commercial\\Tests\\Unit\\');
```

## Consequences

If your namespace will be added via the `FeatureFlagExtension::addNamespace()` method, the major flags will be enabled
by default in your unit tests suite, and you have to explicitly disable the feature you don't want to be executed with
the upcoming major flag turned on. If you want to know the decision why all feature flags are activated by default,
please read [this ADR](https://github.com/shopware/shopware/blob/trunk/adr/2022-10-20-deprecation-handling-during-phpunit-test-execution.md#L15-L14).

---

---
url: >-
  /docs/v6.6/resources/references/adr/2024-07-31-add-more-unit-tests-namespaces-to-featureflag-extension.md
---

# Add more unit tests namespaces to FeatureFlag extension

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2024-07-31-add-more-unit-tests-namespaces-to-featureflag-extension.md)
:::

## Context

The `Shopware\Core\Test\PHPUnit\Extension\FeatureFlag\Subscriber\TestPreparationStartedSubscriber` only allows
the `Shopware\Tests\Unit` namespace to be considered when enabling the major feature in the unit tests suite.

## Decision

To be able to unit test the upcoming major feature in other plugins we will enable the possibility to add other
namespaces to
the `Shopware\Core\Test\PHPUnit\Extension\FeatureFlag\Subscriber\TestPreparationStartedSubscriber`.

We'll add a static method called `addNamespace()` method to the
`Shopware\Core\Test\PHPUnit\Extension\FeatureFlag\FeatureFlagExtension` and by this we are able to add other namespaces
to the allowlist of the namespaces to be considered when enabling the major flags in the unit test suite.

This can be useful for plugins that wants to enable the major flags in their unit tests suite.

Therefore, add the extension to the extension list in the `phpunit.xml`:

```xml

<extensions>
    ...
    <bootstrap class="Shopware\Core\Test\PHPUnit\Extension\FeatureFlag\FeatureFlagExtension"/>
</extensions>
```

And register your test namespace in your test bootstrap file:

```php
FeatureFlagExtension::addTestNamespace('Your\\Unit\\Tests\\Namespace\\');
```

For example, in the Commercial plugin, we added the following code to the `tests/TestBootstrap.php` file:

```php
FeatureFlagExtension::addTestNamespace('Shopware\\Commercial\\Tests\\Unit\\');
```

## Consequences

If your namespace will be added via the `FeatureFlagExtension::addNamespace()` method, the major flags will be enabled
by default in your unit tests suite, and you have to explicitly disable the feature you don't want to be executed with
the upcoming major flag turned on. If you want to know the decision why all feature flags are activated by default,
please read [this ADR](https://github.com/shopware/shopware/blob/trunk/adr/2022-10-20-deprecation-handling-during-phpunit-test-execution.md#L15-L14).

---

---
url: /docs/resources/references/adr/2023-01-30-image-lazy-loading.md
---

# Add native lazy loading for images to the storefront

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2023-01-30-image-lazy-loading.md)
:::

## Context

* Currently, the images/thumbnails inside the Storefront are not making use of any lazy loading mechanism.
* Without a third-party extension which includes something like "lazysizes" it is not possible to get lazy loading images.
* Native lazy loading of images is available in current browsers, see: https://caniuse.com/?search=loading

## Decision

* We want to make use of native lazy loading for images in the Storefront without adding additional JavaScript logic.

## Consequences

* We pass a new attribute `loading="lazy"` to several usages of the thumbnail component `Resources/views/storefront/utilities/thumbnail.html.twig`. This enables native lazy loading.
* By default, the thumbnail component uses `loading="eager"` which is the default behaviour and has the same effect as not setting the attribute.
* The default is not `lazy` in order to avoid unexpected behaviour for extensions which might have added the thumbnail component while using a JavaScript solution for lazy loading.
* We add native lazy loading in appropriate areas to reduce the initial network load:
  * Main menu flyout: Category preview images will only load when flyout is being opened.
  * Product boxes: Product images will only load when they appear in the viewport inside the listing. This also affects product sliders with horizontal scrolling, e.g. cross-selling.
  * CMS image elements: CMS layouts will only load images which appear in the viewport (e.g., when scrolling down the page).
  * Line item images: Product images in line items (e.g., cart page) will only load when they appear in the viewport.

### Why don't we just add `loading="lazy"` everywhere?

* Even though this would technically work, there are a few pitfalls that need to be considered.
* For example, it is not recommended to add lazy loading to images which are very likely inside the initial viewport when loading the page aka "above-the-fold". Further reading: https://web.dev/browser-level-lazy-loading-for-cmss/#avoid-lazy-loading-above-the-fold-elements
* For a system like shopware, where the content is almost entirely dynamic, it is not easy to determine where a generic image component will be rendered. It could have any position on any CMS page.
* Even "guesses" like "only add lazy loading after the 8th product in a listing" can be invalid as soon as a monitor is in portrait mode or the viewport changes to mobile.
* Therefore, we live with the small drawback that, e.g., all product boxes have lazy loading. Some of them will appear "above-the-fold". However, we still have the benefit of loading images later when scrolling down a page or scrolling in product sliders.
* Implementing a JavaScript solution for this would contradict the usage of native lazy loading.

#### Areas without loading="lazy"\`

* Image gallery on product detail page: This is very likely "above-the-fold" and the gallery already uses JavaScript lazy loading for the image zoom as well.
* Image sliders (CMS): When sliding to the next image, the lazy loading can lead to a bad user experience because the image can appear too late.

#### How to activate lazy loading?

When using the thumbnail component, pass the `loading` attribute with value `lazy`:

```diff
{% sw_thumbnails 'my-thumbnail' with {
    media: category.media,
    attributes: {
        'class': 'my-css-class'
+        'loading': 'lazy'
    }
} %}
```

---

---
url: /docs/v6.5/resources/references/adr/2023-01-30-image-lazy-loading.md
---

# Add native lazy loading for images to the storefront

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2023-01-30-image-lazy-loading.md)
:::

## Context

* Currently, the images/thumbnails inside the Storefront are not making use of any lazy loading mechanism.
* Without a third-party extension which includes something like "lazysizes" it is not possible to get lazy loading images.
* Native lazy loading of images is available in current browsers, see: https://caniuse.com/?search=loading

## Decision

* We want to make use of native lazy loading for images in the Storefront without adding additional JavaScript logic.

## Consequences

* We pass a new attribute `loading="lazy"` to several usages of the thumbnail component `Resources/views/storefront/utilities/thumbnail.html.twig`. This enables native lazy loading.
* By default, the thumbnail component uses `loading="eager"` which is the default behaviour and has the same effect as not setting the attribute.
* The default is not `lazy` in order to avoid unexpected behaviour for extensions which might have added the thumbnail component while using a JavaScript solution for lazy loading.
* We add native lazy loading in appropriate areas to reduce the initial network load:
  * Main menu flyout: Category preview images will only load when flyout is being opened.
  * Product boxes: Product images will only load when they appear in the viewport inside the listing. This also affects product sliders with horizontal scrolling, e.g. cross-selling.
  * CMS image elements: CMS layouts will only load images which appear in the viewport (e.g., when scrolling down the page).
  * Line item images: Product images in line items (e.g., cart page) will only load when they appear in the viewport.

### Why don't we just add `loading="lazy"` everywhere?

* Even though this would technically work, there are a few pitfalls that need to be considered.
* For example, it is not recommended to add lazy loading to images which are very likely inside the initial viewport when loading the page aka "above-the-fold". Further reading: https://web.dev/browser-level-lazy-loading-for-cmss/#avoid-lazy-loading-above-the-fold-elements
* For a system like shopware, where the content is almost entirely dynamic, it is not easy to determine where a generic image component will be rendered. It could have any position on any CMS page.
* Even "guesses" like "only add lazy loading after the 8th product in a listing" can be invalid as soon as a monitor is in portrait mode or the viewport changes to mobile.
* Therefore, we live with the small drawback that, e.g., all product boxes have lazy loading. Some of them will appear "above-the-fold". However, we still have the benefit of loading images later when scrolling down a page or scrolling in product sliders.
* Implementing a JavaScript solution for this would contradict the usage of native lazy loading.

#### Areas without loading="lazy"\`

* Image gallery on product detail page: This is very likely "above-the-fold" and the gallery already uses JavaScript lazy loading for the image zoom as well.
* Image sliders (CMS): When sliding to the next image, the lazy loading can lead to a bad user experience because the image can appear too late.

#### How to activate lazy loading?

When using the thumbnail component, pass the `loading` attribute with value `lazy`:

```diff
{% sw_thumbnails 'my-thumbnail' with {
    media: category.media,
    attributes: {
        'class': 'my-css-class'
+        'loading': 'lazy'
    }
} %}
```

---

---
url: /docs/v6.6/resources/references/adr/2023-01-30-image-lazy-loading.md
---

# Add native lazy loading for images to the storefront

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2023-01-30-image-lazy-loading.md)
:::

## Context

* Currently, the images/thumbnails inside the Storefront are not making use of any lazy loading mechanism.
* Without a third-party extension which includes something like "lazysizes" it is not possible to get lazy loading images.
* Native lazy loading of images is available in current browsers, see: https://caniuse.com/?search=loading

## Decision

* We want to make use of native lazy loading for images in the Storefront without adding additional JavaScript logic.

## Consequences

* We pass a new attribute `loading="lazy"` to several usages of the thumbnail component `Resources/views/storefront/utilities/thumbnail.html.twig`. This enables native lazy loading.
* By default, the thumbnail component uses `loading="eager"` which is the default behaviour and has the same effect as not setting the attribute.
* The default is not `lazy` in order to avoid unexpected behaviour for extensions which might have added the thumbnail component while using a JavaScript solution for lazy loading.
* We add native lazy loading in appropriate areas to reduce the initial network load:
  * Main menu flyout: Category preview images will only load when flyout is being opened.
  * Product boxes: Product images will only load when they appear in the viewport inside the listing. This also affects product sliders with horizontal scrolling, e.g. cross-selling.
  * CMS image elements: CMS layouts will only load images which appear in the viewport (e.g., when scrolling down the page).
  * Line item images: Product images in line items (e.g., cart page) will only load when they appear in the viewport.

### Why don't we just add `loading="lazy"` everywhere?

* Even though this would technically work, there are a few pitfalls that need to be considered.
* For example, it is not recommended to add lazy loading to images which are very likely inside the initial viewport when loading the page aka "above-the-fold". Further reading: https://web.dev/browser-level-lazy-loading-for-cmss/#avoid-lazy-loading-above-the-fold-elements
* For a system like shopware, where the content is almost entirely dynamic, it is not easy to determine where a generic image component will be rendered. It could have any position on any CMS page.
* Even "guesses" like "only add lazy loading after the 8th product in a listing" can be invalid as soon as a monitor is in portrait mode or the viewport changes to mobile.
* Therefore, we live with the small drawback that, e.g., all product boxes have lazy loading. Some of them will appear "above-the-fold". However, we still have the benefit of loading images later when scrolling down a page or scrolling in product sliders.
* Implementing a JavaScript solution for this would contradict the usage of native lazy loading.

#### Areas without loading="lazy"\`

* Image gallery on product detail page: This is very likely "above-the-fold" and the gallery already uses JavaScript lazy loading for the image zoom as well.
* Image sliders (CMS): When sliding to the next image, the lazy loading can lead to a bad user experience because the image can appear too late.

#### How to activate lazy loading?

When using the thumbnail component, pass the `loading` attribute with value `lazy`:

```diff
{% sw_thumbnails 'my-thumbnail' with {
    media: category.media,
    attributes: {
        'class': 'my-css-class'
+        'loading': 'lazy'
    }
} %}
```

---

---
url: /docs/guides/plugins/plugins/checkout/payment/add-payment-plugin.md
---

# Add Payment Plugin

::: warning
From Shopware 6.7.0.0, payment handling is done with a single `AbstractPaymentHandler`.
:::

## Overview

Payments are an essential part of the checkout process.
That's why Shopware 6 offers an easy platform on which you can build payment plugins.

## Prerequisites

The examples mentioned in this guide are built upon our plugin base guide.

If you want to understand the payment process in detail, head to our Payment Concept.

## Creating a custom payment handler

To create a payment method with your plugin, you have to add a custom payment handler.

Shopware provides you with a handy `Shopware\Core\Checkout\Payment\Cart\PaymentHandler\AbstractPaymentHandler` abstract class for you to extend to get you started quickly.

### Registering the service

Before we're going to have a look at some examples, we need to register our new service to the [Dependency Injection](../../services/dependency-injection.md) container.
Please make sure to add the `shopware.payment.method` tag to your service definition, otherwise Shopware won't recognize your service as a payment handler.

We'll use a class called `MyCustomPaymentHandler` here.

```php [<plugin root>/src/Resources/config/services.php]
<?php declare(strict_types=1);

use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Swag\PaymentPlugin\Service\MyCustomPaymentHandler;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(MyCustomPaymentHandler::class)
        ->tag('shopware.payment.method');
};
```

Now, let's start with the actual examples.

### Example payment handlers

The following will be a synchronous example, so that no redirect will happen, and the payment can be handled in the shop.
Therefore, you don't have to return a `RedirectResponse` in the `pay` method; no `finalize` method is necessary either.

Therefore, changing the `stateId` of the order should already be done in the `pay` method since there will be no `finalize` method.
If you have to execute some logic that might fail, e.g., a call to an external API, you should throw a `PaymentException`.
Shopware 6 will handle this exception and set the transaction to the `failed` state.

::: code-group

```php [MyCustomPaymentHandler.php]
<?php declare(strict_types=1);

namespace Swag\PaymentPlugin\Service;

use Shopware\Core\Checkout\Order\Aggregate\OrderTransaction\OrderTransactionStateHandler;
use Shopware\Core\Checkout\Payment\Cart\PaymentHandler\AbstractPaymentHandler;
use Shopware\Core\Checkout\Payment\Cart\PaymentHandler\PaymentHandlerType;
use Shopware\Core\Checkout\Payment\Cart\PaymentTransactionStruct;
use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\Struct\Struct;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Request;

class MyCustomPaymentHandler extends AbstractPaymentHandler
{
    public function __construct(private readonly OrderTransactionStateHandler $transactionStateHandler)
    {
    }

    public function supports(PaymentHandlerType $type, string $paymentMethodId, Context $context): bool
    {
        // This payment handler does not support recurring payments nor refunds
        return false;
    }

    /**
     * This method is always called during the checkout.
     * You should process the payment here and return a RedirectResponse if the payment process requires an asynchronous approach.
     * In that case, the finalize method will be called additionally during checkout after the redirect.
     * If the payment process is synchronous, you should return null.
     */
    public function pay(Request $request, PaymentTransactionStruct $transaction, Context $context, ?Struct $validateStruct): ?RedirectResponse
    {
        // In here you should probably call your payment provider to precess the payment
        // $this->myPaymentProvider->processPayment($transaction);

        // afterward you should update the transaction with the new state
        $this->transactionStateHandler->process($transaction->getOrderTransactionId(), $context);

        return null;
    }
}
```

```php [services.php]
<?php declare(strict_types=1);

use Shopware\Core\Checkout\Order\Aggregate\OrderTransaction\OrderTransactionStateHandler;
use Swag\PaymentPlugin\Service\MyCustomPaymentHandler;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(MyCustomPaymentHandler::class)
        ->tag('shopware.payment.method')
        ->args([
            service(OrderTransactionStateHandler::class),
        ]);
};
```

:::

This payment handler does not do a lot in the current state but is a good starting point for your custom payment handler.

In the asynchronous example, the customer gets redirected to an external payment provider,
which then, in return, has to redirect your customer back to your shop.
Therefore, you must first redirect your customer to the payment provider by returning a `RedirectResponse`.

Also, you need a `finalize` method to properly handle your customer when he was returned to your shop.
This is where you check the payment state and set the order transaction state accordingly.

Let's have a look at an example implementation of your custom asynchronous payment handler:

::: code-group

```php [MyCustomPaymentHandler.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Checkout\Order\Aggregate\OrderTransaction\OrderTransactionStateHandler;
use Shopware\Core\Checkout\Payment\Cart\PaymentHandler\AbstractPaymentHandler;
use Shopware\Core\Checkout\Payment\Cart\PaymentHandler\PaymentHandlerType;
use Shopware\Core\Checkout\Payment\Cart\PaymentTransactionStruct;
use Shopware\Core\Checkout\Payment\PaymentException;
use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\Struct\Struct;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Request;

class MyCustomPaymentHandler extends AbstractPaymentHandler
{
    public function __construct(private readonly OrderTransactionStateHandler $transactionStateHandler)
    {
    }

    public function supports(PaymentHandlerType $type, string $paymentMethodId, Context $context): bool
    {
        // This payment handler does not support recurring payments nor refunds
        return false;
    }

    /**
     * This method is always called during the checkout.
     * You should process the payment here and return a RedirectResponse.
     * After redirect the finalize method will be called.
     */
    public function pay(Request $request, PaymentTransactionStruct $transaction, Context $context, ?Struct $validateStruct): ?RedirectResponse
    {
        // Method that sends the return URL to the external gateway and gets a redirect URL back
        try {
            $redirectUrl = $this->sendReturnUrlToExternalGateway($transaction->getReturnUrl());
        } catch (\Exception $e) {
            throw PaymentException::asyncProcessInterrupted(
                $transaction->getOrderTransactionId(),
                'An error occurred during the communication with external payment gateway' . PHP_EOL . $e->getMessage()
            );
        }

        // Redirect to external gateway
        return new RedirectResponse($redirectUrl);
    }

    /**
     * This method will be called after redirect from the external payment provider.
     */
    public function finalize(Request $request, PaymentTransactionStruct $transaction, Context $context): void
    {
        // Example check if the user canceled. Might differ for each payment provider
        if ($request->query->getBoolean('cancel')) {
            throw PaymentException::customerCanceled(
                $transaction->getOrderTransactionId(),
                'Customer canceled the payment on the PayPal page'
            );
        }

        // handle the payment state
        $this->transactionStateHandler->paid($transaction->getOrderTransactionId(), $context);
    }

    private function sendReturnUrlToExternalGateway(string $getReturnUrl): string
    {
        $paymentProviderUrl = '';

        // Do some API Call to your payment provider

        return $paymentProviderUrl;
    }
}
```

```php [services.php]
<?php declare(strict_types=1);

use Shopware\Core\Checkout\Order\Aggregate\OrderTransaction\OrderTransactionStateHandler;
use Swag\PaymentPlugin\Service\MyCustomPaymentHandler;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(MyCustomPaymentHandler::class)
        ->tag('shopware.payment.method')
        ->args([
            service(OrderTransactionStateHandler::class),
        ]);
};
```

:::

Let's start with the `pay` method. You'll have to start by letting your external payment provider know where he should redirect your customer in return when the payment is done.
This is usually done by making an API call and transmitting the return URL, which you can fetch from the passed `PaymentTransactionStruct` using the method `getReturnUrl`.
Since this is just an example, the method `sendReturnUrlToExternalGateway` is empty.
Fill in your logic in there in order to actually send the return URL to the external payment provider.
The last thing you need to do, is to redirect your customer to the external payment provider by returning a `RedirectResponse`.
Shopware handles the redirect for you automatically.

Once your customer is done at the external payment provider, he will be redirected back to your shop.
This is where the `finalize` method will be executed.
In here, you have to check whether the payment process was successful.
If e.g., the customer canceled the payment process, you'll have to throw a `PaymentException::customerCanceled` exception.

Otherwise, you can proceed to check if the payment status was successful.
If so, set the order's transaction state to `paid`.
If not, you could, e.g. reopen the order's transaction.

To improve the payment workflow on headless systems or reduce orders without payment, payment handlers can implement an additional method to support pre-created payments.
The client (e.g. a single-page application) can prepare the payment directly with the payment service (not through Shopware) and pass a transaction reference (token) to Shopware to complete the payment.

Two steps are necessary:
The handler has to validate the payment beforehand, or throw an exception, if the validation fails.
If the validation is successful, the payment handler has to capture the payment in the `pay` method.

Let's have a look at a simple example:

::: code-group

```php [MyCustomPaymentHandler.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Order\Aggregate\OrderTransaction\OrderTransactionStateHandler;
use Shopware\Core\Checkout\Payment\Cart\PaymentHandler\AbstractPaymentHandler;
use Shopware\Core\Checkout\Payment\Cart\PaymentHandler\PaymentHandlerType;
use Shopware\Core\Checkout\Payment\Cart\PaymentTransactionStruct;
use Shopware\Core\Checkout\Payment\PaymentException;
use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\Struct\ArrayStruct;
use Shopware\Core\Framework\Struct\Struct;
use Shopware\Core\Framework\Validation\DataBag\RequestDataBag;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Request;

class MyCustomPaymentHandler extends AbstractPaymentHandler
{
    public function __construct(private readonly OrderTransactionStateHandler $transactionStateHandler)
    {
    }

    public function supports(PaymentHandlerType $type, string $paymentMethodId, Context $context): bool
    {
        // This payment handler does not support recurring payments nor refunds
        return false;
    }

    /**
     * This method will always be called during the checkout, but before order creation.
     * This is especially helpful for headless systems and single-page applications, that prepare payments not through Shopware.
     */
    public function validate(Cart $cart, RequestDataBag $dataBag, SalesChannelContext $context): ?Struct
    {
        // the payment is prepared here and most certainly you will receive a token from your PSP
        if (!$dataBag->has('my-payment-token')) {
            // this will fail the validation
            throw PaymentException::validatePreparedPaymentInterrupted('No token supplied');
        }

        $token = $dataBag->get('my-payment-token');

        // other checks could include comparing the cart value with the actual payload of your PSP

        // return the payment details: these will be given as $preOrderPaymentStruct to the capture method
        return new ArrayStruct(['my-payment-provider-transaction-token' => $token]);
    }

    /**
     * This method is always called during the checkout, but only after the validate method was called.
     * You should process the payment here and return a RedirectResponse if the payment process requires an asynchronous approach.
     * In that case, the finalize method will be called additionally during checkout after the redirect.
     * If the payment process is synchronous, you should return null.
     */
    public function pay(Request $request, PaymentTransactionStruct $transaction, Context $context, ?Struct $validateStruct): ?RedirectResponse
    {
        $validateData = $validateStruct->getVars();

        if (!isset($validateData['my-payment-provider-transaction-token'])) {
            // this will fail the payment process
            throw PaymentException::syncProcessInterrupted($transaction->getOrderTransactionId(), 'No payment token provided');
        }

        // In here you should probably call your payment provider to precess the payment and compare tokens
        if ($validateData['my-payment-provider-transaction-token'] !== 'hatoooken') {
            // this will fail the payment process
            throw PaymentException::syncProcessInterrupted($transaction->getOrderTransactionId(), 'Payment token mismatch');
        }

        // In here you should probably call your payment provider to precess the payment
        // $this->myPaymentProvider->processPayment($transaction);

        // afterward you should update the transaction with the new state
        $this->transactionStateHandler->process($transaction->getOrderTransactionId(), $context);

        return null;
    }
}
```

```php [services.php]
<?php declare(strict_types=1);

use Shopware\Core\Checkout\Order\Aggregate\OrderTransaction\OrderTransactionStateHandler;
use Swag\PaymentPlugin\Service\MyCustomPaymentHandler;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(MyCustomPaymentHandler::class)
        ->tag('shopware.payment.method')
        ->args([
            service(OrderTransactionStateHandler::class),
        ]);
};
```

:::

To allow easy refund handling, your payment handler should return `true` in the supports method,
whenever the PaymentHandlerType is REFUND.

Let's look at a short example of how to implement a refund handlers.

::: code-group

```php [MyCustomPaymentHandler.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Checkout\Order\Aggregate\OrderTransaction\OrderTransactionStateHandler;
use Shopware\Core\Checkout\Order\Aggregate\OrderTransactionCaptureRefund\OrderTransactionCaptureRefundEntity;
use Shopware\Core\Checkout\Order\Aggregate\OrderTransactionCaptureRefund\OrderTransactionCaptureRefundStateHandler;
use Shopware\Core\Checkout\Order\Aggregate\OrderTransactionCaptureRefundPosition\OrderTransactionCaptureRefundPositionEntity;
use Shopware\Core\Checkout\Payment\Cart\PaymentHandler\AbstractPaymentHandler;
use Shopware\Core\Checkout\Payment\Cart\PaymentHandler\PaymentHandlerType;
use Shopware\Core\Checkout\Payment\Cart\PaymentTransactionStruct;
use Shopware\Core\Checkout\Payment\Cart\RefundPaymentTransactionStruct;
use Shopware\Core\Checkout\Payment\PaymentException;
use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\Framework\Struct\Struct;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Request;

class MyCustomPaymentHandler extends AbstractPaymentHandler
{
    public function __construct(
        private readonly EntityRepository $refundRepository,
        private readonly OrderTransactionStateHandler $transactionStateHandler,
        private readonly OrderTransactionCaptureRefundStateHandler $refundStateHandler,
    ) {
    }

    public function supports(PaymentHandlerType $type, string $paymentMethodId, Context $context): bool
    {
        // this payment handler supports refunds
        return $type === PaymentHandlerType::REFUND;
    }

    /**
     * This method is always called during the checkout.
     * You should process the payment here and return a RedirectResponse if the payment process requires an asynchronous approach.
     * In that case, the finalize method will be called additionally during checkout after the redirect.
     * If the payment process is synchronous, you should return null.
     */
    public function pay(Request $request, PaymentTransactionStruct $transaction, Context $context, ?Struct $validateStruct): ?RedirectResponse
    {
        // In here you should probably call your payment provider to precess the payment
        // $this->myPaymentProvider->processPayment($transaction);

        // afterward you should update the transaction with the new state
        $this->transactionStateHandler->process($transaction->getOrderTransactionId(), $context);

        return null;
    }

    /**
     * As long as the supports method returns true for PaymentHandlerType::REFUND, this method will be called during the refund process.
     */
    public function refund(RefundPaymentTransactionStruct $transaction, Context $context): void
    {
        $refund = $this->getRefund($transaction->getRefundId(), $context);

        if (!$refund) {
            // this will stop the refund process and set the refunds state to `failed`
            throw PaymentException::refundInterrupted($transaction->getRefundId(), 'Refund not found');
        }

        // a refund can have multiple positions, with different order line items and amounts
        foreach ($refund->getPositions() as $position) {
            $amount = $position->getAmount()->getTotalPrice();
            $reason = $position->getReason();
            $lineItem = $position->getOrderLineItem();

            // let's say, you allow a position, which was delivered, however broken
            if ($reason === 'malfunction') {
                // you can call your PSP here to refund
                try {
                    $this->callPSPForRefund($amount, $reason, $lineItem->getId());
                } catch (\Exception $e) {
                    // something went wrong at PSP side, throw a refund exception
                    // this will set the refund state to `failed`
                    throw PaymentException::refundInterrupted($refund->getId(), 'Something went wrong');
                }
            }
        }

        // let Shopware know, that the refund was successful
        $this->refundStateHandler->complete($refund->getId(), $context);
    }

    private function getRefund(string $refundId, Context $context): ?OrderTransactionCaptureRefundEntity
    {
        return $this->refundRepository->search(new Criteria([$refundId]), $context)->first();
    }

    private function callPSPForRefund(float $amount, string $reason, string $lineItemId): void
    {
        // call your PSP here
    }
}

```

```php [services.php]
<?php declare(strict_types=1);

use Shopware\Core\Checkout\Order\Aggregate\OrderTransaction\OrderTransactionStateHandler;
use Shopware\Core\Checkout\Order\Aggregate\OrderTransactionCapture\OrderTransactionCaptureStateHandler;
use Swag\PaymentPlugin\Service\MyCustomPaymentHandler;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(MyCustomPaymentHandler::class)
        ->tag('shopware.payment.method')
        ->args([
            service('order_transaction_capture_refund.repository'),
            service(OrderTransactionStateHandler::class),
            service(OrderTransactionCaptureStateHandler::class),
        ]);
};
```

:::

As you can see, you have complete control over handling the refund request and which positions to refund.

Recurring payment handlers allow continuous charging of a customer's payment method.
This is especially useful for subscription-based services.

::: info
A full-fledged Subscriptions feature with recurring payments is available exclusively through our [paid plans](https://www.shopware.com/en/pricing/).
:::

::: info
Usually, a billing agreement between the customer and the payment provider is necessary to allow recurring payments.
:::

::: code-group

```php [MyCustomPaymentHandler.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Checkout\Order\Aggregate\OrderTransaction\OrderTransactionStateHandler;
use Shopware\Core\Checkout\Payment\Cart\PaymentHandler\AbstractPaymentHandler;
use Shopware\Core\Checkout\Payment\Cart\PaymentHandler\PaymentHandlerType;
use Shopware\Core\Checkout\Payment\Cart\PaymentTransactionStruct;
use Shopware\Core\Checkout\Payment\PaymentException;
use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\Struct\Struct;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Request;

class MyCustomPaymentHandler extends AbstractPaymentHandler
{
    public function __construct(private readonly OrderTransactionStateHandler $transactionStateHandler)
    {
    }

    public function supports(PaymentHandlerType $type, string $paymentMethodId, Context $context): bool
    {
        // this payment handler supports recurring payments
        return $type === PaymentHandlerType::RECURRING;
    }

    /**
     * This method is in the case of recurring payments only called during the initial checkout.
     * You probably want to create a billing agreement between the customer and your PSP here.
     * Do not forget to capture the initial charge as well.
     */
    public function pay(Request $request, PaymentTransactionStruct $transaction, Context $context, ?Struct $validateStruct): ?RedirectResponse
    {
        // You can identify, that this is the intitial capture for a recurring payment by checking the `RecurringDataStruct` in the `PaymentTransactionStruct`
        if ($transaction->getRecurring()) {
            // In here you should probably call your payment provider to create a billing agreement
            // $this->myPaymentProvider->createBillingAgreement($transaction);
        }

        // Don't forget to capture the initial payment as well
        // $this->myPaymentProvider->processPayment($transaction);

        // afterward you should update the transaction with the new state
        $this->transactionStateHandler->process($transaction->getOrderTransactionId(), $context);

        return null;
    }

    /**
     * call your PSP here for capturing a recurring payment
     * a valid billing agreement between the customer and the PSP should usually already be in place
     * use on of the other payment handler methods to create such an agreement on checkout and capture the initial order once
     * you will probably receive a token from your PSP for the billing agreement, which you will need to capture a recurring payment
     */
    public function recurring(PaymentTransactionStruct $transaction, Context $context): void
    {
        try {
            $data = $transaction->getRecurring()?->getVars();

            if (!$data || !isset($data['pspBillingAgreementToken'])) {
                throw PaymentException::recurringInterrupted($transaction->getOrderTransactionId(), 'No token supplied');
            }

            //$this->callPSPForRecurringPayment($data['pspBillingAgreementToken']);
        } catch (\Throwable $e) {
            // throw a PaymentException::recurringInterrupted to set the transaction state to `failed`
            throw PaymentException::recurringInterrupted($transaction->getOrderTransactionId(), 'Something went wrong', $e);
        }
    }
}

```

```php [services.php]
<?php declare(strict_types=1);

use Shopware\Core\Checkout\Order\Aggregate\OrderTransaction\OrderTransactionStateHandler;
use Swag\PaymentPlugin\Service\MyCustomPaymentHandler;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(MyCustomPaymentHandler::class)
        ->tag('shopware.payment.method')
        ->args([
            service(OrderTransactionStateHandler::class),
        ]);
};
```

:::

## Setting up the new payment method

The handler itself is not used yet, since there is no payment method actually using the handler created above.
In short: Your handler is not handling any payment method so far.
The payment method can be added to the system while installing your plugin.

An example for your plugin could look like this:

::: code-group

```php [SwagBasicExample.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample;

use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Filter\EqualsFilter;
use Shopware\Core\Framework\Plugin;
use Shopware\Core\Framework\Plugin\Context\ActivateContext;
use Shopware\Core\Framework\Plugin\Context\DeactivateContext;
use Shopware\Core\Framework\Plugin\Context\InstallContext;
use Shopware\Core\Framework\Plugin\Context\UninstallContext;
use Shopware\Core\Framework\Plugin\Util\PluginIdProvider;
use Swag\BasicExample\Service\ExamplePayment;

class SwagBasicExample extends Plugin
{
    public function install(InstallContext $context): void
    {
        $this->addPaymentMethod($context->getContext());
    }

    public function uninstall(UninstallContext $context): void
    {
        // Only set the payment method to inactive when uninstalling. Removing the payment method would
        // cause data consistency issues, since the payment method might have been used in several orders
        $this->setPaymentMethodIsActive(false, $context->getContext());
    }

    public function activate(ActivateContext $context): void
    {
        $this->setPaymentMethodIsActive(true, $context->getContext());
        parent::activate($context);
    }

    public function deactivate(DeactivateContext $context): void
    {
        $this->setPaymentMethodIsActive(false, $context->getContext());
        parent::deactivate($context);
    }

    private function addPaymentMethod(Context $context): void
    {
        $paymentMethodExists = $this->getPaymentMethodId();

        // Payment method exists already, no need to continue here
        if ($paymentMethodExists) {
            return;
        }

        $pluginIdProvider = $this->container->get(PluginIdProvider::class);
        $pluginId = $pluginIdProvider->getPluginIdByBaseClass(get_class($this), $context);

        $examplePaymentData = [
            // payment handler will be selected by the identifier
            'handlerIdentifier' => MyCustomPaymentHandler::class,
            'name' => 'Example payment',
            'description' => 'Example payment description',
            'pluginId' => $pluginId,
            // if true, payment method will also be available after the order
            // is created, e.g. if payment fails and the user wants to try again
            'afterOrderEnabled' => true,
            // Required from Shopware 6.7. Use a plugin-specific prefix to avoid conflicts.
            'technicalName' => 'swag_example-example_payment',
        ];

        $paymentRepository = $this->container->get('payment_method.repository');
        $paymentRepository->create([$examplePaymentData], $context);
    }

    private function setPaymentMethodIsActive(bool $active, Context $context): void
    {
        $paymentRepository = $this->container->get('payment_method.repository');

        $paymentMethodId = $this->getPaymentMethodId();

        // Payment does not even exist, so nothing to (de-)activate here
        if (!$paymentMethodId) {
            return;
        }

        $paymentMethod = [
            'id' => $paymentMethodId,
            'active' => $active,
        ];

        $paymentRepository->update([$paymentMethod], $context);
    }

    private function getPaymentMethodId(): ?string
    {
        $paymentRepository = $this->container->get('payment_method.repository');

        // Fetch ID for update
        $paymentCriteria = (new Criteria())->addFilter(new EqualsFilter('handlerIdentifier', ExamplePayment::class));
        return $paymentRepository->searchIds($paymentCriteria, Context::createDefaultContext())->firstId();
    }
}
```

:::

::: warning
The `technicalName` is required for plugin-provided payment methods starting with
Shopware 6.7. See the [Shopware 6.7 release notes](https://developer.shopware.com/release-notes/6.7/6.7.0.0.html#new-technicalname-property-for-payment-and-shipping-methods)
for the platform change. It must be unique and should use a plugin-specific prefix.
Older versions may allow the field to be omitted, so check existing payment plugins
when migrating them to 6.7 or later. An omitted technical name can prevent the plugin
from being installed or activated, depending on where it is validated.
:::

In the `install` method, you start by creating a new payment method, if it doesn't exist yet.
If you need to know what's happening in there, you might want to have a look at our guide regarding [Writing data](../../framework/data-handling/writing-data).

::: danger
**Do not** do the opposite in the `uninstall` method and remove the payment method.
This might lead to data inconsistency if the payment method was used in some orders.
Instead, only deactivate the method!
:::

The `activate` method and `deactivate` method just do that, activating and deactivating the payment method, respectively.

### Identify your payment

You can identify your payment by the entity property `formattedHandlerIdentifier`.
It shortens the original handler identifier (php class reference): `Custom/Payment/SEPAPayment` to `handler_custom_sepapayment`.
The syntax for the shortening can be looked up in [Shopware\Core\Checkout\Payment\DataAbstractionLayer\PaymentHandlerIdentifierSubscriber](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Core/Checkout/Payment/DataAbstractionLayer/PaymentHandlerIdentifierSubscriber.php).

Otherwise, you can use your given technical name to uniquely identify your payment method.

## Migrating payment handlers from 6.6

If you are migrating a payment handler from a version before 6.7,
you need to move from the existing interfaces to the new abstract class and add your own order data loading..

### Payment handler interfaces removed

Instead of implementing multiple interfaces of `Shopware\Core\Checkout\Payment\Cart\PaymentHandler\PaymentHandlerInterface` in your payment handler,
extend the `Shopware\Core\Checkout\Payment\Cart\PaymentHandler\AbstractPaymentHandler` class and implement the necessary methods.

| Old interface                         | Method used in payment handler                                                                            | Checks for `supports` method    |
|---------------------------------------|-----------------------------------------------------------------------------------------------------------|---------------------------------|
| `SynchronousPaymentHandlerInterface`  | `pay`: always called during checkout                                                                      | -                               |
| `AsynchronousPaymentHandlerInterface` | `finalize`: only called, if `pay` returns a `RedirectResponse`                                            | -                               |
| `PreparedPaymentHandlerInterface`     | `validate`: be aware that this method is always called and can be used to validate a cart during checkout | -                               |
| `RecurringPaymentHandlerInterface`    | `recurring`                                                                                               | `PaymentHandlerType::RECURRING` |
| `RefundPaymentHandlerInterface`       | `refund`                                                                                                  | `PaymentHandlerType::REFUND`    |

### New single tag for payment handlers

Your payment handler should now have a single tag in the service definition: `shopware.payment.method`.
Remove any other occurrences of the following tags:
`shopware.payment.method.sync`, `shopware.payment.method.async`, `shopware.payment.method.prepared`, `shopware.payment.method.recurring`, `shopware.payment.method.refund`.

::: code-group

```php [services.php]
<?php declare(strict_types=1);

use Swag\PaymentPlugin\Service\MyCustomPaymentHandler;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(MyCustomPaymentHandler::class)
        // this is the new tag for payment handlers
        ->tag('shopware.payment.method')

        // remove any of these other tags
        ->tag('shopware.payment.method.sync')
        ->tag('shopware.payment.method.async')
        ->tag('shopware.payment.method.prepared')
        ->tag('shopware.payment.method.recurring')
        ->tag('shopware.payment.method.refund');
};
```

:::

### Prepared payments

In the past, you would have to implement the `validate` and `capture` methods when dealing with the `PreparedPaymentHandlerInterface`.

Now, you only have to implement the `validate` method.
Instead of the `capture` method, the streamlined `pay` method is used and has to be implemented.

---

---
url: /docs/v6.5/guides/plugins/plugins/checkout/payment/add-payment-plugin.md
---

# Add Payment Plugin

## Overview

Payments are an essential part of the checkout process. That's why Shopware 6 offers an easy platform on which you can build payment plugins.

## Prerequisites

The examples mentioned in this guide are built upon our [Plugin base guide](../../plugin-base-guide).

If you want to understand the payment process in detail, head to our [Payment Concept](../../../../../concepts/commerce/checkout-concept/payments).

::: info
Refer to this video on **[Introduction to payment handlers](https://www.youtube.com/watch?v=K58--Pxvudk)** that details you about payment extensions and payment handlers. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

## Creating a custom payment handler

To create a payment method with your plugin, you have to add a custom payment handler.

You can create your payment handler by implementing one of the following interfaces:

| Interface                           | DI container tag                    | Usage                                                                                              |
|:------------------------------------|:------------------------------------|:---------------------------------------------------------------------------------------------------|
| SynchronousPaymentHandlerInterface  | `shopware.payment.method.sync`      | Payment can be handled locally, e.g. pre-payment                                                   |
| AsynchronousPaymentHandlerInterface | `shopware.payment.method.async`     | A redirect to an external payment provider is required, e.g. PayPal                                |
| PreparedPaymentHandlerInterface     | `shopware.payment.method.prepared`  | The payment was prepared beforehand and will only be validated and captured by your implementation |
| RefundPaymentHandlerInterface       | `shopware.payment.method.refund`    | The payment allows refund handling                                                                 |
| RecurringPaymentHandlerInterface    | `shopware.payment.method.recurring` | The payment allows recurring payments, e.g. subscriptions                                       |

Depending on the interface, those methods are required:

* `pay`: This method will be called after an order has been placed. You receive a `Shopware\Core\Checkout\Payment\Cart\AsyncPaymentTransactionStruct` or a `Shopware\Core\Checkout\Payment\Cart\SyncPaymentTransactionStruct` which contains the transactionId, order details, the amount of the transaction, a return URL, payment method information and language information. Please be aware, Shopware 6 supports multiple transactions, and you have to use the amount provided and not the total order amount. If you're using the `AsynchronousPaymentHandlerInterface`, the `pay` method has to return a `RedirectResponse` to redirect the customer to an external payment provider. Note: The [AsyncPaymentTransactionStruct](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Core/Checkout/Payment/Cart/AsyncPaymentTransactionStruct.php) contains a return URL. This represents the URL the external payment provider needs to know to redirect your customer back to your shop. If an error occurs while, e.g., calling the API of your external payment provider, you should throw an `AsyncPaymentProcessException`. Shopware 6 will handle this exception and set the transaction to the `cancelled` state. The same happens if you use the `SynchronousPaymentHandlerInterface`: throw a `SyncPaymentProcessException` in an error case.
* `finalize`: The `finalize` method is only required if you implemented the `AsynchronousPaymentHandlerInterface`, returned a `RedirectResponse` in your `pay` method, and the customer has been redirected from the payment provider back to Shopware 6. You must check here if the payment was successful and update the order transaction state accordingly. Similar to the pay action, you can throw exceptions if some error cases occur. Throw the `CustomerCanceledAsyncPaymentException` if the customer canceled the payment process on the payment provider site. If another general error occurs, throw the `AsyncPaymentFinalizeException` e.g., if your call to the payment provider API fails. Shopware 6 will handle these exceptions and set the transaction to the `cancelled` state.
* `validate`: This method will be called before an order was placed and should check if a given prepared payment is valid. The payment handler has to verify the given payload with the payment service because Shopware cannot ensure that the transaction created by the frontend is valid for the current cart. Throw a `ValidatePreparedPaymentException` to fail the validation in your implementation.
* `capture`: This method will be called after an order was placed, but only if the validation did not fail and stop the payment flow before. At this point, the order was created, and the payment handler will be called again to charge the payment. When the charge was successful, the payment handler should update the transaction state to `paid`. The user will be forwarded to the finish page. Throw a `CapturePreparedPaymentException` on any errors to fail the capture process and, the after-order process will be active so that the customer can complete the payment again.
* `refund`: This method is called whenever a successful transaction is claimed to be refunded. The implementation of the refund handler should validate the legitimacy of the refund and call the PSP to refund the given transaction. Throw a `RefundException` to let the refund fail.
* `captureRecurring`: This method is called whenever a recurring payment is charged. At this point, a valid billing agreement with the payment provider should exist. Use some of the other payment methods for handling the initial order and billing agreement. Use this interface only for handling all recurring captures afterward.

All payment handler methods have the `\Shopware\Core\System\SalesChannel\SalesChannelContext` injected, except for the new  `captureRecurring`  method. Note that this class contains nullable properties. If you want to use this information, you must ensure in your code that they are set and not `NULL`.

### Registering the service

Before we're going to have a look at some examples, we need to register our new service to the [Dependency Injection](../../plugin-fundamentals/dependency-injection) container. We'll use a class called `ExamplePayment` here.

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\PaymentPlugin\Service\ExamplePayment">
            <argument type="service" id="Shopware\Core\Checkout\Order\Aggregate\OrderTransaction\OrderTransactionStateHandler"/>
            <tag name="shopware.payment.method.sync" />
<!--        <tag name="shopware.payment.method.async" />-->
<!--        <tag name="shopware.payment.method.prepared" />-->
<!--        <tag name="shopware.payment.method.refund" />-->
        </service>
    </services>
</container>
```

We inject the `OrderTransactionStateHandler` in this example, as it helps change an order's transaction state, e.g. to `paid`. The payment handler has to be marked as such as well; hence the tag `shopware.payment.method.sync`, `shopware.payment.method.async` or `shopware.payment.method.prepared` respectively for a synchronous, an asynchronous or a prepared payment handler.

Now, let's start with the actual examples.

### Synchronous example

The following will be a synchronous example, so that no redirect will happen, and the payment can be handled in the shop. Therefore, you don't have to return a `RedirectResponse` in the `pay` method; no `finalize` method is necessary either.

Therefore, changing the `stateId` of the order should already be done in the `pay` method since there will be no `finalize` method. If you have to execute some logic that might fail, e.g., a call to an external API, you should throw a `SyncPaymentProcessException`. Shopware 6 will handle this exception and set the transaction to the `cancelled` state.

```php
// <plugin root>/src/Service/ExamplePayment.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Checkout\Payment\Cart\PaymentHandler\SynchronousPaymentHandlerInterface;
use Shopware\Core\Checkout\Payment\Cart\SyncPaymentTransactionStruct;
use Shopware\Core\Checkout\Order\Aggregate\OrderTransaction\OrderTransactionStateHandler;
use Shopware\Core\Framework\Validation\DataBag\RequestDataBag;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class ExamplePayment implements SynchronousPaymentHandlerInterface
{
    private OrderTransactionStateHandler $transactionStateHandler;

    public function __construct(OrderTransactionStateHandler $transactionStateHandler)
    {
        $this->transactionStateHandler = $transactionStateHandler;
    }

    public function pay(SyncPaymentTransactionStruct $transaction, RequestDataBag $dataBag, SalesChannelContext $salesChannelContext): void
    {
        $context = $salesChannelContext->getContext();
        $this->transactionStateHandler->paid($transaction->getOrderTransaction()->getId(), $context);
    }
}
```

All it does now is to set the state of the order transaction to `paid`.

### Asynchronous example

In the asynchronous example, the customer gets redirected to an external payment provider, which then, in return, has to redirect your customer back to your shop. Therefore, you must first redirect your customer to the payment provider by returning a `RedirectResponse`.

Also, you need a `finalize` method to properly handle your customer when he was returned to your shop. This is where you check the payment state and set the order transaction state accordingly.

Let's have a look at an example implementation of your custom asynchronous payment handler:

```php
// <plugin root>/src/Service/ExamplePayment.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Checkout\Payment\PaymentException;
use Shopware\Core\Checkout\Payment\Cart\AsyncPaymentTransactionStruct;
use Shopware\Core\Checkout\Payment\Cart\PaymentHandler\AsynchronousPaymentHandlerInterface;
use Shopware\Core\Checkout\Payment\Exception\AsyncPaymentProcessException;
use Shopware\Core\Checkout\Payment\Exception\CustomerCanceledAsyncPaymentException;
use Shopware\Core\Checkout\Order\Aggregate\OrderTransaction\OrderTransactionStateHandler;
use Shopware\Core\Framework\Validation\DataBag\RequestDataBag;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Request;

class ExamplePayment implements AsynchronousPaymentHandlerInterface
{
    private OrderTransactionStateHandler $transactionStateHandler;

    public function __construct(OrderTransactionStateHandler $transactionStateHandler) {
        $this->transactionStateHandler = $transactionStateHandler;
    }

    /**
     * @throws AsyncPaymentProcessException
     */
    public function pay(AsyncPaymentTransactionStruct $transaction, RequestDataBag $dataBag, SalesChannelContext $salesChannelContext): RedirectResponse
    {
        // Method that sends the return URL to the external gateway and gets a redirect URL back
        try {
            $redirectUrl = $this->sendReturnUrlToExternalGateway($transaction->getReturnUrl());
        } catch (\Exception $e) {
            throw PaymentException::asyncProcess(
                $transaction->getOrderTransaction()->getId(),
                'An error occurred during the communication with external payment gateway' . PHP_EOL . $e->getMessage()
            );
        }

        // Redirect to external gateway
        return new RedirectResponse($redirectUrl);
    }

    /**
     * @throws CustomerCanceledAsyncPaymentException
     */
    public function finalize(AsyncPaymentTransactionStruct $transaction, Request $request, SalesChannelContext $salesChannelContext): void
    {
        $transactionId = $transaction->getOrderTransaction()->getId();

        // Example check if the user canceled. Might differ for each payment provider
        if ($request->query->getBoolean('cancel')) {
            throw PaymentException::asyncCustomerCanceled(
                $transactionId,
                'Customer canceled the payment on the PayPal page'
            );
        }

        // Example check for the actual status of the payment. Might differ for each payment provider
        $paymentState = $request->query->getAlpha('status');

        $context = $salesChannelContext->getContext();
        if ($paymentState === 'completed') {
            // Payment completed, set transaction status to "paid"
            $this->transactionStateHandler->paid($transaction->getOrderTransaction()->getId(), $context);
        } else {
            // Payment not completed, set transaction status to "open"
            $this->transactionStateHandler->reopen($transaction->getOrderTransaction()->getId(), $context);
        }
    }

    private function sendReturnUrlToExternalGateway(string $getReturnUrl): string
    {
        $paymentProviderUrl = '';

        // Do some API Call to your payment provider

        return $paymentProviderUrl;
    }
}
```

Let's start with the `pay` method. You'll have to start by letting your external payment provider know where he should redirect your customer in return when the payment is done. This is usually done by making an API call and transmitting the return URL, which you can fetch from the passed `AsyncPaymentTransactionStruct` using the method `getReturnUrl`. Since this is just an example, the method `sendReturnUrlToExternalGateway` is empty. Fill in your logic in there in order to actually send the return URL to the external payment provider. The last thing you need to do, is to redirect your customer to the external payment provider via a `RedirectResponse`.

Once your customer is done at the external payment provider, he will be redirected back to your shop. This is where the `finalize` method will be executed. In here, you have to check whether or not the payment process was successful. If e.g., the customer canceled the payment process, you'll have to throw a `CustomerCanceledAsyncPaymentException` exception.

Otherwise, you can proceed to check if the payment status was successful. If so, set the order's transaction state to `paid`. If not, you could, e.g. reopen the order's transaction.

### Prepared payments example

To improve the payment workflow on headless systems or reduce orders without payment, payment handlers can implement an additional interface to support pre-created payments. The client (e.g. a single-page application) can prepare the payment directly with the payment service (not through Shopware) and pass a transaction reference (token) to Shopware to complete the payment.

Two steps are necessary: The handler has to validate the payment beforehand, or throw an exception, if the validation fails. After completing the checkout, Shopware calls the handler again to charge the payment.

Let's have a look at a simple example:

```php
// <plugin root>/src/ExamplePayment.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Order\Aggregate\OrderTransaction\OrderTransactionStateHandler;
use Shopware\Core\Checkout\Payment\PaymentException;
use Shopware\Core\Checkout\Payment\Cart\PaymentHandler\PreparedPaymentHandlerInterface;
use Shopware\Core\Checkout\Payment\Cart\PreparedPaymentTransactionStruct;
use Shopware\Core\Checkout\Payment\Exception\CapturePreparedPaymentException;
use Shopware\Core\Checkout\Payment\Exception\ValidatePreparedPaymentException;
use Shopware\Core\Framework\Struct\ArrayStruct;
use Shopware\Core\Framework\Struct\Struct;
use Shopware\Core\Framework\Validation\DataBag\RequestDataBag;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class ExamplePayment implements PreparedPaymentHandlerInterface
{
    private OrderTransactionStateHandler $stateHandler;

    public function __construct(OrderTransactionStateHandler $stateHandler)
    {
        $this->stateHandler = $stateHandler;
    }

    public function validate(
        Cart $cart,
        RequestDataBag $requestDataBag,
        SalesChannelContext $context
    ): Struct {
        if (!$requestDataBag->has('my-payment-token')) {
            // this will fail the validation
            throw PaymentException::preparedValidate('No token supplied');
        }

        $token = $requestDataBag->get('my-payment-token');
        $paymentData = $this->getPaymentDataFromProvider($token);

        if (!$paymentData) {
            // no payment data simulates an error response from our payment provider in this example
            throw PaymentException::preparedValidate('Unknown payment for token ' . $token);
        }

        // other checks could include comparing the cart value with the actual payload of your PSP

        // return the payment details: these will be given as $preOrderPaymentStruct to the capture method
        return new ArrayStruct($paymentData);
    }

    public function capture(
        PreparedPaymentTransactionStruct $transaction,
        RequestDataBag $requestDataBag,
        SalesChannelContext $context,
        Struct $preOrderPaymentStruct
    ): void {

        // you can find all the order specific information in the PreparedPaymentTransactionStruct
        $order = $transaction->getOrder();
        $orderTransaction = $transaction->getOrderTransaction();

        // call you PSP and capture the transaction as usual
        // do not forget to change the transaction's state here:
        $this->stateHandler->paid($orderTransaction->getId(), $context->getContext());
        
        // or in case of an error:
        $this->stateHandler->fail($orderTransaction->getId(), $context->getContext());
        throw PaymentException::preparedCapture($orderTransaction->getId(), 'Capture failed.');
    }

    private function getPaymentDataFromProvider(string $token): array
    {
        // call your payment provider instead and return your real payment details
        return [];
    }
}
```

### Refund example

To allow easy refund handling, Shopware introduced a centralized way of handling refund for transactions.

For this, have your payment handler implement the `RefundPaymentHandlerInterface`.

Let's look at a short example of how to implement such payment handlers.

```php
// <plugin root>/src/ExamplePayment.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Checkout\Order\Aggregate\OrderTransactionCaptureRefund\OrderTransactionCaptureRefundEntity;
use Shopware\Core\Checkout\Order\Aggregate\OrderTransactionCaptureRefund\OrderTransactionCaptureRefundStateHandler;
use Shopware\Core\Checkout\Order\Aggregate\OrderTransactionCaptureRefundPosition\OrderTransactionCaptureRefundPositionEntity;
use Shopware\Core\Checkout\Payment\PaymentException;
use Shopware\Core\Checkout\Payment\Cart\PaymentHandler\RefundPaymentHandlerInterface;
use Shopware\Core\Framework\Context;

class ExamplePayment implements RefundPaymentHandlerInterface
{
    private OrderTransactionCaptureRefundStateHandler $stateHandler;

    public function __construct(OrderTransactionCaptureRefundStateHandler $stateHandler)
    {
        $this->stateHandler = $stateHandler;
    }

    public function refund(OrderTransactionCaptureRefundEntity $refund, Context $context): void
    {
        if ($refund->getAmount() > 100.00) {
            // this will stop the refund process and set the refunds state to `failed`
            throw PaymentException::refund($refund->getId(), 'Refunds over 100 € are not allowed');
        }

        // a refund can have multiple positions, with different order line items and amounts
        /** @var OrderTransactionCaptureRefundPositionEntity $position */
        foreach ($refund->getPositions() as $position) {
            $amount = $position->getAmount()->getTotalPrice();
            $reason = $position->getReason();
            $lineItem = $position->getOrderLineItem();

            // let's say, you allow a position, which was delivered, however broken
            if ($reason === 'malfunction') {
                // you can call your PSP here to refund

                try {
                    $this->callPSPForRefund($amount, $reason, $lineItem->getId());
                } catch (\Exception $e) {
                    // something went wrong at PSP side, throw a refund exception
                    // this will set the refund state to `failed`
                    throw PaymentException::refund($refund->getId(), 'Something went wrong');
                }
            }
        }

        // let Shopware know, that the refund was successful
        $this->stateHandler->complete($refund->getId(), $context);
    }

    private function callPSPForRefund(float $amount, string $reason, string $id): void
    {
        // call you PSP here and process the response
        // throw an exception to stop the refund process
    }
}
```

As you can see, you have complete control over handling the refund request and which positions to refund.

### Recurring capture example

::: info
Recurring orders and payments require the Subscriptions feature, available exclusively in our [paid plans](https://www.shopware.com/en/pricing/).
:::

```php
// <plugin root>/src/ExamplePayment.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Checkout\Payment\PaymentException;
use Shopware\Core\Checkout\Payment\Exception\RecurringPaymentProcessException;
use Shopware\Core\Checkout\Payment\Cart\PaymentHandler\RecurringPaymentHandlerInterface;
use Shopware\Core\Checkout\Payment\Cart\RecurringPaymentTransactionStruct;
use Shopware\Core\Checkout\Order\Aggregate\OrderTransaction\OrderTransactionStateHandler;
use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\Validation\DataBag\RequestDataBag;

class ExamplePayment implements RecurringPaymentHandlerInterface
{
    private OrderTransactionStateHandler $transactionStateHandler;

    public function __construct(OrderTransactionStateHandler $transactionStateHandler)
    {
        $this->transactionStateHandler = $transactionStateHandler;
    }

    /**
     * @throws RecurringPaymentProcessException
     */
    public function captureRecurring(RecurringPaymentTransactionStruct $transaction, Context $context): void
    {
        // call your PSP here for capturing a recurring payment
        // a valid billing agreement between the customer and the PSP should already be in place 
        // use on of the other payment interfaces to create such an agreement on checkout and capture the initial order once
        // you will probably receive a token from your PSP for the billing agreement, which you will need to capture a recurring payment
        
        try {
            // $this->callMyPsp();
        } catch (\Throwable $e) {
            // throw a RecurringPaymentProcessException: this will set the transaction state to `failed` 
            throw PaymentException::recurringInterrupted($transaction->getOrderTransaction()->getId(), 'Something went wrong', $e);
        }
    }
}
```

## Setting up new payment method

The handler itself is not used yet, since there is no payment method actually using the handler created above. In short: Your handler is not handling any payment method so far. The payment method can be added to the system while installing your plugin.

An example for your plugin could look like this:

```php
// <plugin root>/src/SwagBasicExample.php
<?php declare(strict_types=1);

namespace Swag\BasicExample;

use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Filter\EqualsFilter;
use Shopware\Core\Framework\Plugin;
use Shopware\Core\Framework\Plugin\Context\ActivateContext;
use Shopware\Core\Framework\Plugin\Context\DeactivateContext;
use Shopware\Core\Framework\Plugin\Context\InstallContext;
use Shopware\Core\Framework\Plugin\Context\UninstallContext;
use Shopware\Core\Framework\Plugin\Util\PluginIdProvider;
use Swag\BasicExample\Service\ExamplePayment;

class SwagBasicExample extends Plugin
{
    public function install(InstallContext $context): void
    {
        $this->addPaymentMethod($context->getContext());
    }

    public function uninstall(UninstallContext $context): void
    {
        // Only set the payment method to inactive when uninstalling. Removing the payment method would
        // cause data consistency issues, since the payment method might have been used in several orders
        $this->setPaymentMethodIsActive(false, $context->getContext());
    }

    public function activate(ActivateContext $context): void
    {
        $this->setPaymentMethodIsActive(true, $context->getContext());
        parent::activate($context);
    }

    public function deactivate(DeactivateContext $context): void
    {
        $this->setPaymentMethodIsActive(false, $context->getContext());
        parent::deactivate($context);
    }

    private function addPaymentMethod(Context $context): void
    {
        $paymentMethodExists = $this->getPaymentMethodId();

        // Payment method exists already, no need to continue here
        if ($paymentMethodExists) {
            return;
        }

        /** @var PluginIdProvider $pluginIdProvider */
        $pluginIdProvider = $this->container->get(PluginIdProvider::class);
        $pluginId = $pluginIdProvider->getPluginIdByBaseClass(get_class($this), $context);

        $examplePaymentData = [
            // payment handler will be selected by the identifier
            'handlerIdentifier' => ExamplePayment::class,
            'name' => 'Example payment',
            'description' => 'Example payment description',
            'pluginId' => $pluginId,
            // if true, payment method will also be available after the order 
            // is created, e.g. if payment fails and the user wants to try again
            'afterOrderEnabled' => true,
        ];

        /** @var EntityRepository $paymentRepository */
        $paymentRepository = $this->container->get('payment_method.repository');
        $paymentRepository->create([$examplePaymentData], $context);
    }

    private function setPaymentMethodIsActive(bool $active, Context $context): void
    {
        /** @var EntityRepository $paymentRepository */
        $paymentRepository = $this->container->get('payment_method.repository');

        $paymentMethodId = $this->getPaymentMethodId();

        // Payment does not even exist, so nothing to (de-)activate here
        if (!$paymentMethodId) {
            return;
        }

        $paymentMethod = [
            'id' => $paymentMethodId,
            'active' => $active,
        ];

        $paymentRepository->update([$paymentMethod], $context);
    }

    private function getPaymentMethodId(): ?string
    {
        /** @var EntityRepository $paymentRepository */
        $paymentRepository = $this->container->get('payment_method.repository');

        // Fetch ID for update
        $paymentCriteria = (new Criteria())->addFilter(new EqualsFilter('handlerIdentifier', ExamplePayment::class));
        return $paymentRepository->searchIds($paymentCriteria, Context::createDefaultContext())->firstId();
    }
}
```

In the `install` method, you start by creating a new payment method, if it doesn't exist yet. If you need to know what's happening in there, you might want to have a look at our guide regarding [Writing data](../../framework/data-handling/writing-data).

::: warning
**Do not** do the opposite in the `uninstall` method and remove the payment method. This might lead to data inconsistency if the payment method was used in some orders. Instead, only deactivate the method!
:::

The `activate` method and `deactivate` method just do that, activating and deactivating the payment method, respectively.

### Identify your payment

You can identify your payment by the entity property `formattedHandlerIdentifier`. It shortens the original handler identifier (php class reference): `Custom/Payment/SEPAPayment` to `handler_custom_sepapayment`. The syntax for the shortening can be looked up in [Shopware\Core\Checkout\Payment\DataAbstractionLayer\PaymentHandlerIdentifierSubscriber](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Core/Checkout/Payment/DataAbstractionLayer/PaymentHandlerIdentifierSubscriber.php).

---

---
url: /docs/v6.6/guides/plugins/plugins/checkout/payment/add-payment-plugin.md
---

# Add Payment Plugin

::: warning
With Shopware 6.6.5.0, the payment handling was refactored.
Most of this documentation is deprecated and obsolete with 6.7.0.0.

The new payment handling is done via a single `AbstractPaymentHandler`.
Check out the new documentation here: [Add Payment Plugin (>6.7)](/docs/v6.7/guides/plugins/plugins/checkout/payment/add-payment-plugin.html).
:::

## Overview

Payments are an essential part of the checkout process. That's why Shopware 6 offers an easy platform on which you can build payment plugins.

## Prerequisites

The examples mentioned in this guide are built upon our [Plugin base guide](../../plugin-base-guide).

If you want to understand the payment process in detail, head to our [Payment Concept](../../../../../concepts/commerce/checkout-concept/payments).

::: info
Refer to this video on **[Introduction to payment handlers](https://www.youtube.com/watch?v=K58--Pxvudk)** that details you about payment extensions and payment handlers. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

## Creating a custom payment handler

To create a payment method with your plugin, you have to add a custom payment handler.

You can create your payment handler by implementing one of the following interfaces:

| Interface                           | DI container tag                    | Usage                                                                                              |
|:------------------------------------|:------------------------------------|:---------------------------------------------------------------------------------------------------|
| SynchronousPaymentHandlerInterface  | `shopware.payment.method.sync`      | Payment can be handled locally, e.g. pre-payment                                                   |
| AsynchronousPaymentHandlerInterface | `shopware.payment.method.async`     | A redirect to an external payment provider is required, e.g. PayPal                                |
| PreparedPaymentHandlerInterface     | `shopware.payment.method.prepared`  | The payment was prepared beforehand and will only be validated and captured by your implementation |
| RefundPaymentHandlerInterface       | `shopware.payment.method.refund`    | The payment allows refund handling                                                                 |
| RecurringPaymentHandlerInterface    | `shopware.payment.method.recurring` | The payment allows recurring payments, e.g. subscriptions                                          |

Depending on the interface, those methods are required:

* `pay`: This method will be called after an order has been placed. You receive a `Shopware\Core\Checkout\Payment\Cart\AsyncPaymentTransactionStruct` or a `Shopware\Core\Checkout\Payment\Cart\SyncPaymentTransactionStruct` which contains the transactionId, order details, the amount of the transaction, a return URL, payment method information and language information. Please be aware, Shopware 6 supports multiple transactions, and you have to use the amount provided and not the total order amount. If you're using the `AsynchronousPaymentHandlerInterface`, the `pay` method has to return a `RedirectResponse` to redirect the customer to an external payment provider. Note: The [AsyncPaymentTransactionStruct](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Core/Checkout/Payment/Cart/AsyncPaymentTransactionStruct.php) contains a return URL. This represents the URL the external payment provider needs to know to redirect your customer back to your shop. If an error occurs while, e.g., calling the API of your external payment provider, you should throw an `AsyncPaymentProcessException`. Shopware 6 will handle this exception and set the transaction to the `cancelled` state. The same happens if you use the `SynchronousPaymentHandlerInterface`: throw a `SyncPaymentProcessException` in an error case.
* `finalize`: The `finalize` method is only required if you implemented the `AsynchronousPaymentHandlerInterface`, returned a `RedirectResponse` in your `pay` method, and the customer has been redirected from the payment provider back to Shopware 6. You must check here if the payment was successful and update the order transaction state accordingly. Similar to the pay action, you can throw exceptions if some error cases occur. Throw the `CustomerCanceledAsyncPaymentException` if the customer canceled the payment process on the payment provider site. If another general error occurs, throw the `AsyncPaymentFinalizeException` e.g., if your call to the payment provider API fails. Shopware 6 will handle these exceptions and set the transaction to the `cancelled` state.
* `validate`: This method will be called before an order was placed and should check if a given prepared payment is valid. The payment handler has to verify the given payload with the payment service because Shopware cannot ensure that the transaction created by the frontend is valid for the current cart. Throw a `ValidatePreparedPaymentException` to fail the validation in your implementation.
* `capture`: This method will be called after an order was placed, but only if the validation did not fail and stop the payment flow before. At this point, the order was created, and the payment handler will be called again to charge the payment. When the charge was successful, the payment handler should update the transaction state to `paid`. The user will be forwarded to the finish page. Throw a `CapturePreparedPaymentException` on any errors to fail the capture process and, the after-order process will be active so that the customer can complete the payment again.
* `refund`: This method is called whenever a successful transaction is claimed to be refunded. The implementation of the refund handler should validate the legitimacy of the refund and call the PSP to refund the given transaction. Throw a `RefundException` to let the refund fail.
* `captureRecurring`: This method is called whenever a recurring payment is charged. At this point, a valid billing agreement with the payment provider should exist. Use some of the other payment methods for handling the initial order and billing agreement. Use this interface only for handling all recurring captures afterward.

All payment handler methods have the `\Shopware\Core\System\SalesChannel\SalesChannelContext` injected, except for the new  `captureRecurring`  method. Note that this class contains nullable properties. If you want to use this information, you must ensure in your code that they are set and not `NULL`.

### Registering the service

Before we're going to have a look at some examples, we need to register our new service to the [Dependency Injection](../../plugin-fundamentals/dependency-injection) container. We'll use a class called `ExamplePayment` here.

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\PaymentPlugin\Service\ExamplePayment">
            <argument type="service" id="Shopware\Core\Checkout\Order\Aggregate\OrderTransaction\OrderTransactionStateHandler"/>
            <tag name="shopware.payment.method.sync" />
<!--        <tag name="shopware.payment.method.async" />-->
<!--        <tag name="shopware.payment.method.prepared" />-->
<!--        <tag name="shopware.payment.method.refund" />-->
        </service>
    </services>
</container>
```

We inject the `OrderTransactionStateHandler` in this example, as it helps change an order's transaction state, e.g. to `paid`. The payment handler has to be marked as such as well; hence the tag `shopware.payment.method.sync`, `shopware.payment.method.async` or `shopware.payment.method.prepared` respectively for a synchronous, an asynchronous or a prepared payment handler.

Now, let's start with the actual examples.

### Synchronous example

The following will be a synchronous example, so that no redirect will happen, and the payment can be handled in the shop. Therefore, you don't have to return a `RedirectResponse` in the `pay` method; no `finalize` method is necessary either.

Therefore, changing the `stateId` of the order should already be done in the `pay` method since there will be no `finalize` method. If you have to execute some logic that might fail, e.g., a call to an external API, you should throw a `SyncPaymentProcessException`. Shopware 6 will handle this exception and set the transaction to the `cancelled` state.

```php
// <plugin root>/src/Service/ExamplePayment.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Checkout\Payment\Cart\PaymentHandler\SynchronousPaymentHandlerInterface;
use Shopware\Core\Checkout\Payment\Cart\SyncPaymentTransactionStruct;
use Shopware\Core\Checkout\Order\Aggregate\OrderTransaction\OrderTransactionStateHandler;
use Shopware\Core\Framework\Validation\DataBag\RequestDataBag;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class ExamplePayment implements SynchronousPaymentHandlerInterface
{
    private OrderTransactionStateHandler $transactionStateHandler;

    public function __construct(OrderTransactionStateHandler $transactionStateHandler)
    {
        $this->transactionStateHandler = $transactionStateHandler;
    }

    public function pay(SyncPaymentTransactionStruct $transaction, RequestDataBag $dataBag, SalesChannelContext $salesChannelContext): void
    {
        $context = $salesChannelContext->getContext();
        $this->transactionStateHandler->paid($transaction->getOrderTransaction()->getId(), $context);
    }
}
```

All it does now is to set the state of the order transaction to `paid`.

### Asynchronous example

In the asynchronous example, the customer gets redirected to an external payment provider, which then, in return, has to redirect your customer back to your shop. Therefore, you must first redirect your customer to the payment provider by returning a `RedirectResponse`.

Also, you need a `finalize` method to properly handle your customer when he was returned to your shop. This is where you check the payment state and set the order transaction state accordingly.

Let's have a look at an example implementation of your custom asynchronous payment handler:

```php
// <plugin root>/src/Service/ExamplePayment.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Checkout\Payment\PaymentException;
use Shopware\Core\Checkout\Payment\Cart\AsyncPaymentTransactionStruct;
use Shopware\Core\Checkout\Payment\Cart\PaymentHandler\AsynchronousPaymentHandlerInterface;
use Shopware\Core\Checkout\Payment\Exception\AsyncPaymentProcessException;
use Shopware\Core\Checkout\Payment\Exception\CustomerCanceledAsyncPaymentException;
use Shopware\Core\Checkout\Order\Aggregate\OrderTransaction\OrderTransactionStateHandler;
use Shopware\Core\Framework\Validation\DataBag\RequestDataBag;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Symfony\Component\HttpFoundation\RedirectResponse;
use Symfony\Component\HttpFoundation\Request;

class ExamplePayment implements AsynchronousPaymentHandlerInterface
{
    private OrderTransactionStateHandler $transactionStateHandler;

    public function __construct(OrderTransactionStateHandler $transactionStateHandler) {
        $this->transactionStateHandler = $transactionStateHandler;
    }

    /**
     * @throws AsyncPaymentProcessException
     */
    public function pay(AsyncPaymentTransactionStruct $transaction, RequestDataBag $dataBag, SalesChannelContext $salesChannelContext): RedirectResponse
    {
        // Method that sends the return URL to the external gateway and gets a redirect URL back
        try {
            $redirectUrl = $this->sendReturnUrlToExternalGateway($transaction->getReturnUrl());
        } catch (\Exception $e) {
            throw PaymentException::asyncProcess(
                $transaction->getOrderTransaction()->getId(),
                'An error occurred during the communication with external payment gateway' . PHP_EOL . $e->getMessage()
            );
        }

        // Redirect to external gateway
        return new RedirectResponse($redirectUrl);
    }

    /**
     * @throws CustomerCanceledAsyncPaymentException
     */
    public function finalize(AsyncPaymentTransactionStruct $transaction, Request $request, SalesChannelContext $salesChannelContext): void
    {
        $transactionId = $transaction->getOrderTransaction()->getId();

        // Example check if the user canceled. Might differ for each payment provider
        if ($request->query->getBoolean('cancel')) {
            throw PaymentException::asyncCustomerCanceled(
                $transactionId,
                'Customer canceled the payment on the PayPal page'
            );
        }

        // Example check for the actual status of the payment. Might differ for each payment provider
        $paymentState = $request->query->getAlpha('status');

        $context = $salesChannelContext->getContext();
        if ($paymentState === 'completed') {
            // Payment completed, set transaction status to "paid"
            $this->transactionStateHandler->paid($transaction->getOrderTransaction()->getId(), $context);
        } else {
            // Payment not completed, set transaction status to "open"
            $this->transactionStateHandler->reopen($transaction->getOrderTransaction()->getId(), $context);
        }
    }

    private function sendReturnUrlToExternalGateway(string $getReturnUrl): string
    {
        $paymentProviderUrl = '';

        // Do some API Call to your payment provider

        return $paymentProviderUrl;
    }
}
```

Let's start with the `pay` method. You'll have to start by letting your external payment provider know where he should redirect your customer in return when the payment is done. This is usually done by making an API call and transmitting the return URL, which you can fetch from the passed `AsyncPaymentTransactionStruct` using the method `getReturnUrl`. Since this is just an example, the method `sendReturnUrlToExternalGateway` is empty. Fill in your logic in there in order to actually send the return URL to the external payment provider. The last thing you need to do, is to redirect your customer to the external payment provider via a `RedirectResponse`.

Once your customer is done at the external payment provider, he will be redirected back to your shop. This is where the `finalize` method will be executed. In here, you have to check whether or not the payment process was successful. If e.g., the customer canceled the payment process, you'll have to throw a `CustomerCanceledAsyncPaymentException` exception.

Otherwise, you can proceed to check if the payment status was successful. If so, set the order's transaction state to `paid`. If not, you could, e.g. reopen the order's transaction.

### Prepared payments example

To improve the payment workflow on headless systems or reduce orders without payment, payment handlers can implement an additional interface to support pre-created payments. The client (e.g. a single-page application) can prepare the payment directly with the payment service (not through Shopware) and pass a transaction reference (token) to Shopware to complete the payment.

Two steps are necessary: The handler has to validate the payment beforehand, or throw an exception, if the validation fails. After completing the checkout, Shopware calls the handler again to charge the payment.

Let's have a look at a simple example:

```php
// <plugin root>/src/ExamplePayment.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Order\Aggregate\OrderTransaction\OrderTransactionStateHandler;
use Shopware\Core\Checkout\Payment\PaymentException;
use Shopware\Core\Checkout\Payment\Cart\PaymentHandler\PreparedPaymentHandlerInterface;
use Shopware\Core\Checkout\Payment\Cart\PreparedPaymentTransactionStruct;
use Shopware\Core\Checkout\Payment\Exception\CapturePreparedPaymentException;
use Shopware\Core\Checkout\Payment\Exception\ValidatePreparedPaymentException;
use Shopware\Core\Framework\Struct\ArrayStruct;
use Shopware\Core\Framework\Struct\Struct;
use Shopware\Core\Framework\Validation\DataBag\RequestDataBag;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class ExamplePayment implements PreparedPaymentHandlerInterface
{
    private OrderTransactionStateHandler $stateHandler;

    public function __construct(OrderTransactionStateHandler $stateHandler)
    {
        $this->stateHandler = $stateHandler;
    }

    public function validate(
        Cart $cart,
        RequestDataBag $requestDataBag,
        SalesChannelContext $context
    ): Struct {
        if (!$requestDataBag->has('my-payment-token')) {
            // this will fail the validation
            throw PaymentException::preparedValidate('No token supplied');
        }

        $token = $requestDataBag->get('my-payment-token');
        $paymentData = $this->getPaymentDataFromProvider($token);

        if (!$paymentData) {
            // no payment data simulates an error response from our payment provider in this example
            throw PaymentException::preparedValidate('Unknown payment for token ' . $token);
        }

        // other checks could include comparing the cart value with the actual payload of your PSP

        // return the payment details: these will be given as $preOrderPaymentStruct to the capture method
        return new ArrayStruct($paymentData);
    }

    public function capture(
        PreparedPaymentTransactionStruct $transaction,
        RequestDataBag $requestDataBag,
        SalesChannelContext $context,
        Struct $preOrderPaymentStruct
    ): void {

        // you can find all the order specific information in the PreparedPaymentTransactionStruct
        $order = $transaction->getOrder();
        $orderTransaction = $transaction->getOrderTransaction();

        // call you PSP and capture the transaction as usual
        // do not forget to change the transaction's state here:
        $this->stateHandler->paid($orderTransaction->getId(), $context->getContext());
        
        // or in case of an error:
        $this->stateHandler->fail($orderTransaction->getId(), $context->getContext());
        throw PaymentException::preparedCapture($orderTransaction->getId(), 'Capture failed.');
    }

    private function getPaymentDataFromProvider(string $token): array
    {
        // call your payment provider instead and return your real payment details
        return [];
    }
}
```

### Refund example

To allow easy refund handling, Shopware introduced a centralized way of handling refund for transactions.

For this, have your payment handler implement the `RefundPaymentHandlerInterface`.

Let's look at a short example of how to implement such payment handlers.

```php
// <plugin root>/src/ExamplePayment.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Checkout\Order\Aggregate\OrderTransactionCaptureRefund\OrderTransactionCaptureRefundEntity;
use Shopware\Core\Checkout\Order\Aggregate\OrderTransactionCaptureRefund\OrderTransactionCaptureRefundStateHandler;
use Shopware\Core\Checkout\Order\Aggregate\OrderTransactionCaptureRefundPosition\OrderTransactionCaptureRefundPositionEntity;
use Shopware\Core\Checkout\Payment\PaymentException;
use Shopware\Core\Checkout\Payment\Cart\PaymentHandler\RefundPaymentHandlerInterface;
use Shopware\Core\Framework\Context;

class ExamplePayment implements RefundPaymentHandlerInterface
{
    private OrderTransactionCaptureRefundStateHandler $stateHandler;

    public function __construct(OrderTransactionCaptureRefundStateHandler $stateHandler)
    {
        $this->stateHandler = $stateHandler;
    }

    public function refund(OrderTransactionCaptureRefundEntity $refund, Context $context): void
    {
        if ($refund->getAmount() > 100.00) {
            // this will stop the refund process and set the refunds state to `failed`
            throw PaymentException::refund($refund->getId(), 'Refunds over 100 € are not allowed');
        }

        // a refund can have multiple positions, with different order line items and amounts
        /** @var OrderTransactionCaptureRefundPositionEntity $position */
        foreach ($refund->getPositions() as $position) {
            $amount = $position->getAmount()->getTotalPrice();
            $reason = $position->getReason();
            $lineItem = $position->getOrderLineItem();

            // let's say, you allow a position, which was delivered, however broken
            if ($reason === 'malfunction') {
                // you can call your PSP here to refund

                try {
                    $this->callPSPForRefund($amount, $reason, $lineItem->getId());
                } catch (\Exception $e) {
                    // something went wrong at PSP side, throw a refund exception
                    // this will set the refund state to `failed`
                    throw PaymentException::refund($refund->getId(), 'Something went wrong');
                }
            }
        }

        // let Shopware know, that the refund was successful
        $this->stateHandler->complete($refund->getId(), $context);
    }

    private function callPSPForRefund(float $amount, string $reason, string $id): void
    {
        // call you PSP here and process the response
        // throw an exception to stop the refund process
    }
}
```

As you can see, you have complete control over handling the refund request and which positions to refund.

### Recurring capture example

::: info
Recurring orders and payments require the Subscriptions feature, available exclusively in our [paid plans](https://www.shopware.com/en/pricing/).
:::

```php
// <plugin root>/src/ExamplePayment.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Checkout\Payment\PaymentException;
use Shopware\Core\Checkout\Payment\Exception\RecurringPaymentProcessException;
use Shopware\Core\Checkout\Payment\Cart\PaymentHandler\RecurringPaymentHandlerInterface;
use Shopware\Core\Checkout\Payment\Cart\RecurringPaymentTransactionStruct;
use Shopware\Core\Checkout\Order\Aggregate\OrderTransaction\OrderTransactionStateHandler;
use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\Validation\DataBag\RequestDataBag;

class ExamplePayment implements RecurringPaymentHandlerInterface
{
    private OrderTransactionStateHandler $transactionStateHandler;

    public function __construct(OrderTransactionStateHandler $transactionStateHandler)
    {
        $this->transactionStateHandler = $transactionStateHandler;
    }

    /**
     * @throws RecurringPaymentProcessException
     */
    public function captureRecurring(RecurringPaymentTransactionStruct $transaction, Context $context): void
    {
        // call your PSP here for capturing a recurring payment
        // a valid billing agreement between the customer and the PSP should already be in place 
        // use on of the other payment interfaces to create such an agreement on checkout and capture the initial order once
        // you will probably receive a token from your PSP for the billing agreement, which you will need to capture a recurring payment
        
        try {
            // $this->callMyPsp();
        } catch (\Throwable $e) {
            // throw a RecurringPaymentProcessException: this will set the transaction state to `failed` 
            throw PaymentException::recurringInterrupted($transaction->getOrderTransaction()->getId(), 'Something went wrong', $e);
        }
    }
}
```

## Setting up new payment method

The handler itself is not used yet, since there is no payment method actually using the handler created above. In short: Your handler is not handling any payment method so far. The payment method can be added to the system while installing your plugin.

An example for your plugin could look like this:

```php
// <plugin root>/src/SwagBasicExample.php
<?php declare(strict_types=1);

namespace Swag\BasicExample;

use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Filter\EqualsFilter;
use Shopware\Core\Framework\Plugin;
use Shopware\Core\Framework\Plugin\Context\ActivateContext;
use Shopware\Core\Framework\Plugin\Context\DeactivateContext;
use Shopware\Core\Framework\Plugin\Context\InstallContext;
use Shopware\Core\Framework\Plugin\Context\UninstallContext;
use Shopware\Core\Framework\Plugin\Util\PluginIdProvider;
use Swag\BasicExample\Service\ExamplePayment;

class SwagBasicExample extends Plugin
{
    public function install(InstallContext $context): void
    {
        $this->addPaymentMethod($context->getContext());
    }

    public function uninstall(UninstallContext $context): void
    {
        // Only set the payment method to inactive when uninstalling. Removing the payment method would
        // cause data consistency issues, since the payment method might have been used in several orders
        $this->setPaymentMethodIsActive(false, $context->getContext());
    }

    public function activate(ActivateContext $context): void
    {
        $this->setPaymentMethodIsActive(true, $context->getContext());
        parent::activate($context);
    }

    public function deactivate(DeactivateContext $context): void
    {
        $this->setPaymentMethodIsActive(false, $context->getContext());
        parent::deactivate($context);
    }

    private function addPaymentMethod(Context $context): void
    {
        $paymentMethodExists = $this->getPaymentMethodId();

        // Payment method exists already, no need to continue here
        if ($paymentMethodExists) {
            return;
        }

        /** @var PluginIdProvider $pluginIdProvider */
        $pluginIdProvider = $this->container->get(PluginIdProvider::class);
        $pluginId = $pluginIdProvider->getPluginIdByBaseClass(get_class($this), $context);

        $examplePaymentData = [
            // payment handler will be selected by the identifier
            'handlerIdentifier' => ExamplePayment::class,
            'name' => 'Example payment',
            'description' => 'Example payment description',
            'pluginId' => $pluginId,
            // if true, payment method will also be available after the order 
            // is created, e.g. if payment fails and the user wants to try again
            'afterOrderEnabled' => true,
        ];

        /** @var EntityRepository $paymentRepository */
        $paymentRepository = $this->container->get('payment_method.repository');
        $paymentRepository->create([$examplePaymentData], $context);
    }

    private function setPaymentMethodIsActive(bool $active, Context $context): void
    {
        /** @var EntityRepository $paymentRepository */
        $paymentRepository = $this->container->get('payment_method.repository');

        $paymentMethodId = $this->getPaymentMethodId();

        // Payment does not even exist, so nothing to (de-)activate here
        if (!$paymentMethodId) {
            return;
        }

        $paymentMethod = [
            'id' => $paymentMethodId,
            'active' => $active,
        ];

        $paymentRepository->update([$paymentMethod], $context);
    }

    private function getPaymentMethodId(): ?string
    {
        /** @var EntityRepository $paymentRepository */
        $paymentRepository = $this->container->get('payment_method.repository');

        // Fetch ID for update
        $paymentCriteria = (new Criteria())->addFilter(new EqualsFilter('handlerIdentifier', ExamplePayment::class));
        return $paymentRepository->searchIds($paymentCriteria, Context::createDefaultContext())->firstId();
    }
}
```

In the `install` method, you start by creating a new payment method, if it doesn't exist yet. If you need to know what's happening in there, you might want to have a look at our guide regarding [Writing data](../../framework/data-handling/writing-data).

::: warning
**Do not** do the opposite in the `uninstall` method and remove the payment method. This might lead to data inconsistency if the payment method was used in some orders. Instead, only deactivate the method!
:::

The `activate` method and `deactivate` method just do that, activating and deactivating the payment method, respectively.

### Identify your payment

You can identify your payment by the entity property `formattedHandlerIdentifier`. It shortens the original handler identifier (php class reference): `Custom/Payment/SEPAPayment` to `handler_custom_sepapayment`. The syntax for the shortening can be looked up in [Shopware\Core\Checkout\Payment\DataAbstractionLayer\PaymentHandlerIdentifierSubscriber](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Core/Checkout/Payment/DataAbstractionLayer/PaymentHandlerIdentifierSubscriber.php).

---

---
url: /docs/guides/plugins/plugins/plugin-fundamentals/add-plugin-configuration.md
---

# Add Plugin Configuration

Shopware allows you to define a configuration page for your plugin using a `config.xml` file. No custom Administration module or knowledge of templating is required.

::: info Related guide
See [Use plugin configuration](use-plugin-configuration.md) for additional guidance.
:::

## Prerequisites

A running plugin. Review the [Plugin Base Guide](../plugin-base-guide.md) for instructions.

## Create your plugin configuration

::: info
This video is part of the free Shopware Academy online training ["Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

Create `src/Resources/config/config.xml` inside your plugin. The content of the `config.xml` will be dynamically rendered in the Administration. Start with a simple text field first; the available field types and advanced options are listed below.

An example structure:

```text
└── plugins
    └── SwagBasicExample
        ├── src
        │   ├── Resources
        │   │   └── config
        │   │       └── config.xml
        │   └── SwagBasicExample.php
        └── composer.json
```

## Fill your plugin configuration with settings

As you now know how to create configurations, you can start to fill it with life using various configuration options.

### Cards in your configuration

The `config.xml` follows a simple syntax. You can organize the content in `<card>` elements.

Every `config.xml` must contain at least one `<card>` element with a `<title>` and at least one `<input-field>`. See the minimum `config.xml` below:

::: code-group

```xml [PLUGIN_ROOT/src/Resources/config/config.xml]
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/SystemConfig/Schema/config.xsd">
    <card>
        <title>Minimal configuration</title>
        <input-field>
            <name>example</name>
        </input-field>
    </card>
</config>
```

:::

Please make sure to specify the `xsi:noNamespaceSchemaLocation` as shown above and fetch the external resource into your IDE if possible.
This enables auto-completion and suggestions for this XML file and will therefore help you to prevent issues and bugs.

### Card Titles

A `<card>` `<title>` is translatable, this is managed via the `lang` attribute.
By default, the `lang` attribute is set to `en-GB`, to change the locale of a `<title>` just add the attribute as follows:

```html
    ...
    <card>
        <title>English Title</title>
        <title lang="de-DE">German Title</title>
    </card>
    ...
```

### Input fields

Every `<input-field>` must contain at least a `<name>` element.
The `<name>` element is not translatable and has to be unique, since it will be used as the technical identifier for the config element.
The field `<name>` must at least be 4 characters long and consist of only lower and upper case letters.
It can contain numbers, but not at first place - see this RegEx pattern: `[a-zA-Z][a-zA-Z0-9]*`

```html
    ...
    <input-field>
        <name>exampleField</name>
    </input-field>
    ...
```

### The different types of input field

Your `<input-field>` can be of different types, this is managed via the `type` attribute.
Unless defined otherwise, your `<input-field>` will be a text field.
Below you'll find a list of all available `<input-field type="?">`.

| Type          | Configuration settings                                                                                                                                                              | Renders           | Default value example                   |
|:--------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------|:----------------------------------------|
| text          | [copyable](add-plugin-configuration.md#copyable), [placeholder](add-plugin-configuration.md#label-placeholder-and-help-text), [length](add-plugin-configuration.md#text-length-restrictions) | Text field        | Some text                               |
| textarea      | [copyable](add-plugin-configuration.md#copyable), [placeholder](add-plugin-configuration.md#label-placeholder-and-help-text)                                                                 | Text area         | Some more text                          |
| text-editor   | [placeholder](add-plugin-configuration.md#label-placeholder-and-help-text)                                                                                                                   | HTML editor       | Some text with HTML `<div>`tags`</div>` |
| url           | [copyable](add-plugin-configuration.md#copyable), [placeholder](add-plugin-configuration.md#label-placeholder-and-help-text), [length](add-plugin-configuration.md#text-length-restrictions) | URL field         | <https://example.com>                   |
| password      | [placeholder](add-plugin-configuration.md#label-placeholder-and-help-text), [length](add-plugin-configuration.md#text-length-restrictions)                                                   | Password field    | \*\*\*\*\*\*\*\*                                |
| int           | [length](add-plugin-configuration.md#number-length-restrictions)                                                                                                                             | Number field      | 42                                      |
| float         | [length](add-plugin-configuration.md#number-length-restrictions)                                                                                                                             | Number field      | 42.42                                   |
| bool          |                                                                                                                                                                                              | Switch            | `true` or `false`                       |
| checkbox      |                                                                                                                                                                                              | Checkbox          | `true` or `false`                       |
| datetime      |                                                                                                                                                                                              | Date-time picker  | 2024-04-04T12:00:00.000Z                |
| date          |                                                                                                                                                                                              | Date picker       | 2024-04-05T00:00:00                     |
| time          |                                                                                                                                                                                              | Time picker       | 11:00:00                                |
| colorpicker   |                                                                                                                                                                                              | Color picker      | #189EFF                                 |
| single-select | [options](add-plugin-configuration.md#options), [placeholder](add-plugin-configuration.md#label-placeholder-and-help-text)                                                                   | Single-Select box | option\_id                               |
| multi-select  | [options](add-plugin-configuration.md#options), [placeholder](add-plugin-configuration.md#label-placeholder-and-help-text)                                                                   | Multi-Select box  | \[option\_id1, option\_id2]                |

### Input field settings

These settings are used to configure your `<input-field>`.
**Every `<input-field>` has to start with the `<name>` element.**
After the `<name>` element you can configure any of the other settings mentioned above.
Besides these settings, they have the following in common:
[label](add-plugin-configuration.md#label-placeholder-and-help-text),
[helpText](add-plugin-configuration.md#label-placeholder-and-help-text),
[defaultValue](add-plugin-configuration.md#defaultvalue),
[disabled](add-plugin-configuration.md#disabled),
and [required](add-plugin-configuration.md#required).

#### Cache-relevant fields

Use the `cache-relevant="true"` attribute when a configuration value changes cached Storefront output. This applies to fields that are read in Storefront templates, controllers, page loaders, or other code paths that influence an HTTP-cached response.

::: info
The `cache-relevant` attribute is available starting with Shopware 6.7.12.0. Starting with Shopware 6.8.0.0, system config writes no longer invalidate caches by default, so fields that affect cached Storefront output need to provide this attribute.
:::

When a shop operator changes a cache-relevant field in the Administration, Shopware treats the write as cache-relevant and triggers the broader system config cache invalidation path for the current sales channel. Leave the attribute unset for internal settings, credentials, timestamps, or other values that do not change cached Storefront output.

The default is off because most configuration values do not change cached Storefront output. Marking too many fields as cache-relevant turns routine configuration saves into broad cache invalidations, which increases cache misses and negatively impacts performance and scalability.

You can set the attribute on `<input-field>` and advanced `<component>` fields:

```html
<input-field type="bool" cache-relevant="true">
    <name>showBadge</name>
    <label>Show badge in the Storefront</label>
</input-field>

<component name="sw-media-field" cache-relevant="true">
    <name>heroImage</name>
    <label>Hero image</label>
</component>
```

#### Label, placeholder and help text

The settings `<label>`, `<placeholder>` and `<helpText>` are used to label and explain your `<input-field>` and are translatable.
You define your `<label>`, `<placeholder>` and `<helpText>` the same way as the `<card><title>`, with the `lang` attribute.
Please remember, that the `lang` attribute is set to `en-GB` per default.

```html
<input-field type="text">
    <name>email</name>
    <label>Email address</label>
    <label lang="de-DE">E-Mail-Adresse</label>
    <placeholder>you@example.com</placeholder>
    <placeholder lang="de-DE">du@beispiel.de</placeholder>
    <helpText>Enter your email address.</helpText>
    <helpText lang="de-DE">Gib deine E-Mail-Adresse ein.</helpText>
</input-field>
```

#### defaultValue

Add the `defaultValue` setting to your `<input-field>` to define a default value for it.
This value will be imported into the database on installing and updating the plugin.
We use [Symfony\Component\Config\Util\XmlUtils](https://github.com/symfony/config/blob/7.1/Util/XmlUtils.php#L211) for casting the values into the correct PHP types.

Below, you'll find an example of how to use this setting.

```html
<input-field type="text">
    <name>textField</name>
    <label>Test field with default value</label>
    <defaultValue>test</defaultValue>
</input-field>
```

#### disabled

You can add the `<disabled>` setting to any of your `<input-field>` elements to disable it.

Below, you'll find an example of how to use this setting.

```html
<input-field>
    <name>email</name>
    <disabled>true</disabled>
</input-field>
```

*Please note, `<disabled>` only accepts boolean values.*

#### required

You can add the `<required>` setting to any of your `<input-field>` elements to mark it accordingly.

Below, you'll find an example of how to use this setting.

```html
<input-field>
    <name>email</name>
    <required>true</required>
</input-field>
```

*Please note, `<required>` only accepts boolean values.*

#### copyable

You can add the `<copyable>` setting to your `<input-field>` which are of type `text` or extensions of it.
This will add a button at the right, which on click copies the content of your `<input-field>` into the clipboard.

Below, you'll find an example of how to use this setting.

```html
<input-field>
    <name>email</name>
    <copyable>true</copyable>
</input-field>
```

*Please note, that `<copyable>` only accepts boolean values*

#### Text length restrictions

You can add the `<minLength>`/`<maxLength>` settings to your `<input-field>` which are of type `text`, `url` or `password`.
With those you can restrict the length of the input.

Below, you'll find an example of how to use this setting.

```html
<input-field type="password">
    <name>token</name>
    <minLength>5</minLength>
    <maxLength>20</maxLength>
</input-field>
```

#### Number length restrictions

You can add the `<min>`/`<max>` settings to your `<input-field>` which are of type `int` or `float`.
With those you can restrict the minimum and maximum value of the input.

Below, you'll find an example of how to use this setting.

```html
<input-field type="int">
    <name>token</name>
    <min>5</min>
    <max>20</max>
</input-field>
```

#### options

You can use `<options>` to add settings to a `<input-field>` of the types `single-select` and `multi-select`.
Each `<option>` represents one setting you can select.

Below you'll find an example.

```html
<input-field type="single-select">
    <name>mailMethod</name>
    <options>
        <option>
            <id>smtp</id>
            <name>English label</name>
            <name lang="de-DE">German label</name>
        </option>
        <option>
            <id>pop3</id>
            <name>English label</name>
            <name lang="de-DE">German label</name>
        </option>
    </options>
</input-field>
```

Each `<options>` element must contain at least one `<option>` element.
Each `<option>` element must contain at least one `<id>` and one `<name>` element.
As you can see above, `<name>` elements are translatable via the `lang` attribute.

### Advanced custom input fields

For more complex and advanced configurations it is possible to declare a `<component name="componentName">` element.
This element can render many admin components.
It is also possible to render your own admin component which you could deliver with your plugin.
The name of the component has to match the component's name in the Administration, for example `sw-entity-single-select`.
The component also needs a `<name>` element first.
All other elements within the component element will be passed to the rendered admin component as properties.
For some components you could also use [`label` and `placeholder`](add-plugin-configuration.md#label-placeholder-and-help-text).

Here are some examples:

#### Entity single select for products

```html
<component name="sw-entity-single-select">
    <name>exampleProduct</name>
    <entity>product</entity>
    <label>Choose a product for the plugin configuration</label>
</component>
```

Stores the ID of the selected product into the system config.

#### Entity multi ID select for products

```html
<component name="sw-entity-multi-id-select">
    <name>exampleMultiProductIds</name>
    <entity>product</entity>
    <label>Choose multiple products IDs for the plugin configuration</label>
</component>
```

Stores an array with IDs of the selected products into the system config.

#### Media selection

```html
<component name="sw-media-field">
    <name>pluginMedia</name>
    <label>Upload media or choose one from the media manager</label>
</component>
```

#### Text editor

```html
<component name="sw-text-editor">
    <name>textEditor</name>
    <label>Write some nice text with WYSIWYG editor</label>
</component>
```

#### Snippet field

```html
<component name="sw-snippet-field">
    <name>snippetField</name>
    <label>Description</label>
    <snippet>myPlugin.test.snippet</snippet>
</component>
```

Allows you to edit snippet values within the configuration page.
This component does not store values in the system config, but changes the translations for the snippet key.
**Note: This field is only available from 6.3.4.0 onward.**

#### Entity selects without a name field

Some entities do not have a `name` field, which is used per default in the select components. For example, the `mail_template` entity does not have a name field, but you can still use `description` as a `label-property` to select mail templates in your plugin configuration. Without it, the select field would be empty and not usable. You can check available properties for an entity in the `EntityDefinition` of the entity (in this case `Shopware\Core\Content\MailTemplate\MailTemplateDefinition`).

```html
<component name="sw-entity-single-select">
    <name>exampleMailTemplate</name>
    <entity>mail_template</entity>
    <label-property>description</label-property>
    <label>Choose a mail template for the plugin configuration</label>
</component>
```

Stores the ID of the selected mail template into the system config.

#### Supported component types

Please note: It is impossible to allow every component in the `config.xml`, due to their complexities.
If you can't efficiently resolve your plugin's necessities with these components, it is probably better to create your own module instead.
Therefore, Shopware supports the following components by default (also to be found in the [ConfigValidator class](https://github.com/shopware/shopware/blob/v6.6.7.0/src/Core/Framework/App/Validation/ConfigValidator.php#L18)):

* sw-entity-single-select
* sw-entity-multi-id-select
* sw-media-field
* sw-text-editor
* sw-snippet-field

## Example

Full multi-card `config.xml` example (collapse to focus on smaller snippets above):

::: code-group

```xml [PLUGIN_ROOT/src/Resources/config/config.xml]
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/SystemConfig/Schema/config.xsd">

    <card>
        <title>Basic Configuration</title>
        <title lang="de-DE">Grundeinstellungen</title>

        <input-field>
            <name>email</name>
            <copyable>true</copyable>
            <label>eMail address</label>
            <label lang="de-DE">E-Mailadresse</label>
            <placeholder>you@example.com</placeholder>
            <placeholder lang="de-DE">du@beispiel.de</placeholder>
            <helpText>Please fill in your personal eMail address</helpText>
            <helpText lang="de-DE">Bitte trage deine persönliche E-Mailadresse ein</helpText>
        </input-field>

        <input-field type="single-select">
            <name>mailMethod</name>
            <options>
                <option>
                    <id>smtp</id>
                    <name>English smtp</name>
                    <name lang="de-DE">German smtp</name>
                </option>
                <option>
                    <id>pop3</id>
                    <name>English pop3</name>
                    <name lang="de-DE">German pop3</name>
                </option>
            </options>
            <defaultValue>smtp</defaultValue>
            <label>Mail method</label>
            <label lang="de-DE">Versand-Protokoll</label>
        </input-field>

        <input-field type="bool" cache-relevant="true">
            <name>showBadge</name>
            <defaultValue>true</defaultValue>
            <label>Show badge in the Storefront</label>
            <label lang="de-DE">Badge im Storefront anzeigen</label>
        </input-field>
    </card>

    <card>
        <title>Advanced Configuration</title>
        <title lang="de-DE">Erweiterte Einstellungen</title>

        <input-field type="password">
            <name>secret</name>
            <label>Secret token</label>
            <label lang="de-DE">Geheimschlüssel</label>
            <helpText>Your secret token for xyz...</helpText>
            <helpText lang="de-DE">Dein geheimer Schlüssel für xyz...</helpText>
        </input-field>
    </card>
</config>
```

:::

## Add values to your configuration

After adding your input fields to the `config.xml`, save and refresh the Administration. Navigate from the sidebar to the **Extensions → My extensions → Plugins** tab, find your plugin, and click **Configure** (or the plugin’s configuration action). Use the **Configuration** tab to enter values for your fields. (Apps use a separate tab.)

## Next steps

Now that your configuration is defined, review the [Using the plugin configuration](use-plugin-configuration.md) guide to use it in your plugin logic.

---

---
url: >-
  /docs/v6.5/guides/plugins/plugins/plugin-fundamentals/add-plugin-configuration.md
---

# Add Plugin Configuration

The `Shopware plugin system` provides you with the option to create a configuration page for your plugin without any knowledge of templating or the `Shopware Administration`.

## Prerequisites

To build your own configuration page for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide).

## Create your plugin configuration

::: info
This video is part of the online training ["Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma) available on Shopware Academy for **free**.
:::

All you need to do is creating a `config.xml` file inside of a `Resources/config` directory in your plugin root. The content of the `config.xml` will be dynamically rendered in the Administration. Below you'll find an example structure:

```text
└── plugins
    └── SwagBasicExample
        ├── src
        │   ├── Resources
        │   │   └── config
        │   │       └── config.xml 
        │   └── SwagBasicExample.php
        └── composer.json
```

## Fill your plugin configuration with settings

As you now know how to create configurations, you can start to fill it with life using various configuration options.

### Cards in your configuration

The `config.xml` follows a simple syntax. You can organize the content in `<card>` elements. Every `config.xml` must contain a minimum of one `<card>` element and each `<card>` must contain one `<title>` and at least one `<input-field>`. See the minimum `config.xml` below:

```xml
// <plugin root>/src/Resources/config/config.xml
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/SystemConfig/Schema/config.xsd">
    <card>
        <title>Minimal configuration</title>
        <input-field>
            <name>example</name>
        </input-field>
    </card>
</config>
```

Please make sure to specify the `xsi:noNamespaceSchemaLocation` as shown above and fetch the external resource into your IDE if possible. This enables auto-completion and suggestions for this XML file and will therefore help you to prevent issues and bugs.

### Card Titles

A `<card>` `<title>` is translatable, this is managed via the `lang` attribute. By default, the `lang` attribute is set to `en-GB`, to change the locale of a `<title>` just add the attribute as follows:

```html
    ...
    <card>
        <title>English Title</title>
        <title lang="de-DE">German Titel</title>
    </card>
    ...
```

### Input fields

As you can see above, every `<input-field>` has to contain at least a `<name>` element. The `<name>` element is not translatable and has to be unique, since it will be used as the technical identifier for the config element. The field `<name>` must at least be 4 characters long and consist of only lower and upper case letters. It can contain numbers, but not at first place - see this pattern: `[a-zA-Z][a-zA-Z0-9]*`

### The different types of input field

Your `<input-field>` can be of different types, this is managed via the `type` attribute. Unless defined otherwise, your `<input-field>` will be a text field per default. Below you'll find a list of all available `<input-field type="?">`.

| Type | Configuration settings | Renders |
| :--- | :--- | :--- |
| text | [copyable](add-plugin-configuration#copyable), [placeholder](add-plugin-configuration#label-placeholder-and-help-text) | Text field |
| textarea | [copyable](add-plugin-configuration#copyable), [placeholder](add-plugin-configuration#label-placeholder-and-help-text) | Text area |
| text-editor | [placeholder](add-plugin-configuration#label-placeholder-and-help-text) | HTML editor |
| url | [copyable](add-plugin-configuration#copyable), [placeholder](add-plugin-configuration#label-placeholder-and-help-text) | URL field |
| password | [placeholder](add-plugin-configuration#label-placeholder-and-help-text) | Password field |
| int |  | Integer field |
| float |  | Float field |
| bool |  | Switch |
| checkbox |  | Checkbox |
| datetime |  | Date-time picker |
| date |  | Date picker |
| time |  | Time picker |
| colorpicker |  | Color picker |
| single-select | [options](add-plugin-configuration#options), [placeholder](add-plugin-configuration#label-placeholder-and-help-text) | Single-Select box |
| multi-select | [options](add-plugin-configuration#options), [placeholder](add-plugin-configuration#label-placeholder-and-help-text) | Multi-Select box |

### Input field settings

These settings are used to configure your `<input-field>`. **Every `<input-field>` has to start with the `<name>` element.** After the `<name>` element you can configure any of the other settings mentioned above. Beside these settings, they have the following in common: [label](add-plugin-configuration#label-placeholder-and-help-text), [helpText](add-plugin-configuration#label-placeholder-and-help-text), [defaultValue](add-plugin-configuration#defaultvalue) and [disabled](add-plugin-configuration#disabled).

#### Label, placeholder and help text

The settings `<label>`, `<placeholder>` and `<helpText>` are used to label and explain your `<input-field>` and are translatable. You define your `<label>`, `<placeholder>` and `<helpText>` the same way as the `<card><title>`, with the `lang` attribute. Please remember, that the `lang` attribute is set to `en-GB` per default.

#### defaultValue

Add the `defaultValue` setting to your `<input-field>` to define a default value for it. This value will be imported into the database on installing and updating the plugin. We use [Symfony\Component\Config\Util\XmlUtils](https://github.com/symfony/config/blob/master/Util/XmlUtils.php#L215) for casting the values into the correct PHP types.

Below, you'll find an example of how to use this setting.

```html
<input-field type="text">
    <name>textField</name>
    <label>Test field with default value</label>
    <defaultValue>test</defaultValue>
</input-field>
```

#### disabled

You can add the `<disabled>` setting to any of your `<input-field>` elements to disable it.

Below, you'll find an example of how to use this setting.

```html
<input-field>
    <name>email</name>
    <disabled>true</disabled>
</input-field>
```

*Please note, `<disabled>` only takes boolean values.*

#### copyable

You can add the `<copyable>` setting to your `<input-field>` which are of type `text` or extensions of it. This will add a button at the right, which on click copies the content of your `<input-field>` into the clipboard.

Below, you'll find an example of how to use this setting.

```html
<input-field>
    <name>email</name>
    <copyable>true</copyable>
</input-field>
```

*Please note, that `<copyable>` only takes boolean values*

#### options

You can use `<options>` to add settings to a `<input-field>` of the types `single-select` and `multi-select`. Each `<option>` represents one setting you can select.

Below you'll find an example.

```html
<input-field type="single-select">
    <name>mailMethod</name>
    <options>
        <option>
            <id>smtp</id>
            <name>English label</name>
            <name lang="de-DE">German label</name>
        </option>
        <option>
            <id>pop3</id>
            <name>English label</name>
            <name lang="de-DE">German label</name>
        </option>
    </options>
</input-field>
```

Each `<options>` element must contain at least one `<option>` element. Each `<option>` element must contain at least one `<id>` and one `<name>` element. As you can see above, `<name>` elements are translatable via the `lang` attribute.

### Advanced custom input fields

For more complex and advanced configurations it is possible to declare a `<component name="componentName">` element. This element can render many admin components. It is also possible to render your own admin component which you could deliver with your plugin. The name of the component has to match the components name in the Administration, for example `sw-entity-single-select`. The component also needs a `<name>` element first. All other elements within the component element will be passed to the rendered admin component as properties. For some components you could also use [`label` and `placeholder`](add-plugin-configuration#label-placeholder-and-help-text).

Here are some examples:

### Entity single select for products

```html
<component name="sw-entity-single-select">
    <name>exampleProduct</name>
    <entity>product</entity>
    <label>Choose a product for the plugin configuration</label>
</component>
```

Stores the ID of the selected product into the system config.

### Entity multi ID select for products

```html
<component name="sw-entity-multi-id-select">
    <name>exampleMultiProductIds</name>
    <entity>product</entity>
    <label>Choose multiple products IDs for the plugin configuration</label>
</component>
```

Stores an array with IDs of the selected products into the system config.

### Media selection

```html
<component name="sw-media-field">
    <name>pluginMedia</name>
    <label>Upload media or choose one from the media manager</label>
</component>
```

### Text editor

```html
<component name="sw-text-editor">
    <name>textEditor</name>
    <label>Write some nice text with WYSIWYG editor</label>
</component>
```

### Snippet field

```html
<component name="sw-snippet-field">
    <name>snippetField</name>
    <label>Description</label>
    <snippet>myPlugin.test.snippet</snippet>
</component>
```

Allows you to edit snippet values within the configuration page. This component does not store values in the system config, but changes the translations for the snippet key. **Note: This field is only available from 6.3.4.0 onward.**

### Supported component types

Please Note: It is impossible to allow every component to the config.xml, due to their complexities. If you can't efficiently resolve your plugin's necessities with, it is probably better to create an own module instead. Therefore, Shopware supports the following components by default (also to be found in the [ConfigValidator class](https://github.com/shopware/shopware/blob/729fbf368a065177a17e0fc190334ce02b45f418/src/Core/Framework/App/Validation/ConfigValidator.php#L16)):

* sw-entity-single-select
* sw-entity-multi-id-select
* sw-media-field
* sw-text-editor
* sw-snippet-field

## Example

Now all that's left to do is to present you a working example `config.xml` and show you the result.

```xml
// <plugin root>/src/Resources/config/config.xml
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/SystemConfig/Schema/config.xsd">

    <card>
        <title>Basic Configuration</title>
        <title lang="de-DE">Grundeinstellungen</title>

        <input-field>
            <name>email</name>
            <copyable>true</copyable>
            <label>eMail address</label>
            <label lang="de-DE">E-Mailadresse</label>
            <placeholder>you@example.com</placeholder>
            <placeholder lang="de-DE">du@beispiel.de</placeholder>
            <helpText>Please fill in your personal eMail address</helpText>
            <helpText lang="de-DE">Bitte trage deine persönliche E-Mailadresse ein</helpText>
        </input-field>

        <input-field type="single-select">
            <name>mailMethod</name>
            <options>
                <option>
                    <id>smtp</id>
                    <name>English smtp</name>
                    <name lang="de-DE">German smtp</name>
                </option>
                <option>
                    <id>pop3</id>
                    <name>English pop3</name>
                    <name lang="de-DE">German pop3</name>
                </option>
            </options>
            <defaultValue>smtp</defaultValue>
            <label>Mail method</label>
            <label lang="de-DE">Versand-Protokoll</label>
        </input-field>
    </card>

    <card>
        <title>Advanced Configuration</title>
        <title lang="de-DE">Erweiterte Einstellungen</title>

        <input-field type="password">
            <name>secret</name>
            <label>Secret token</label>
            <label lang="de-DE">Geheimschlüssel</label>
            <helpText>Your secret token for xyz...</helpText>
            <helpText lang="de-DE">Dein geheimer Schlüssel für xyz...</helpText>
        </input-field>
    </card>
</config>
```

## Add values to your configuration

After adding your input fields to the `config.xml`, you can add values to your configuration. To do so, navigate from the sidebar to the `Extensions` > `My extensions` > `Apps` tab and click on your plugin's `...` button. Now you can see the `Configuration` tab and fill in the values for your input fields.

## Next steps

Now you've added your own plugin configuration. But how do you actually read which configurations the shop owner used? This will be covered in our guide about [Using the plugin configuration](use-plugin-configuration).

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/plugin-fundamentals/add-plugin-configuration.md
---

# Add Plugin Configuration

The `Shopware plugin system` provides you with the option to create a configuration page for your plugin without any knowledge of templating or the `Shopware Administration`.

## Prerequisites

To build your own configuration page for your plugin, you first need a plugin as base.
Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide).

## Create your plugin configuration

::: info
This video is part of the online training ["Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma) available on Shopware Academy for **free**.
:::

All you need to do is create a `config.xml` file inside a `Resources/config` directory in your plugin root.
The content of the `config.xml` will be dynamically rendered in the Administration.
Below you'll find an example structure:

```text
└── plugins
    └── SwagBasicExample
        ├── src
        │   ├── Resources
        │   │   └── config
        │   │       └── config.xml 
        │   └── SwagBasicExample.php
        └── composer.json
```

## Fill your plugin configuration with settings

As you now know how to create configurations, you can start to fill it with life using various configuration options.

### Cards in your configuration

The `config.xml` follows a simple syntax.
You can organize the content in `<card>` elements.
Every `config.xml` must contain a minimum of one `<card>` element and each `<card>` must contain one `<title>` and at least one `<input-field>`.
See the minimum `config.xml` below:

```xml
<!--<plugin root>/src/Resources/config/config.xml-->
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/SystemConfig/Schema/config.xsd">
    <card>
        <title>Minimal configuration</title>
        <input-field>
            <name>example</name>
        </input-field>
    </card>
</config>
```

Please make sure to specify the `xsi:noNamespaceSchemaLocation` as shown above and fetch the external resource into your IDE if possible.
This enables auto-completion and suggestions for this XML file and will therefore help you to prevent issues and bugs.

### Card Titles

A `<card>` `<title>` is translatable, this is managed via the `lang` attribute.
By default, the `lang` attribute is set to `en-GB`, to change the locale of a `<title>` just add the attribute as follows:

```html
    ...
    <card>
        <title>English Title</title>
        <title lang="de-DE">German Titel</title>
    </card>
    ...
```

### Input fields

As you can see above, every `<input-field>` has to contain at least a `<name>` element.
The `<name>` element is not translatable and has to be unique, since it will be used as the technical identifier for the config element.
The field `<name>` must at least be 4 characters long and consist of only lower and upper case letters.
It can contain numbers, but not at first place - see this RegEx pattern: `[a-zA-Z][a-zA-Z0-9]*`

### The different types of input field

Your `<input-field>` can be of different types, this is managed via the `type` attribute.
Unless defined otherwise, your `<input-field>` will be a text field.
Below you'll find a list of all available `<input-field type="?">`.

| Type          | Configuration settings                                                                                                                                                              | Renders           | Default value example                   |
|:--------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------|:----------------------------------------|
| text          | [copyable](add-plugin-configuration#copyable), [placeholder](add-plugin-configuration#label-placeholder-and-help-text), [length](add-plugin-configuration#text-length-restrictions) | Text field        | Some text                               |
| textarea      | [copyable](add-plugin-configuration#copyable), [placeholder](add-plugin-configuration#label-placeholder-and-help-text)                                                              | Text area         | Some more text                          |
| text-editor   | [placeholder](add-plugin-configuration#label-placeholder-and-help-text)                                                                                                             | HTML editor       | Some text with HTML `<div>`tags`</div>` |
| url           | [copyable](add-plugin-configuration#copyable), [placeholder](add-plugin-configuration#label-placeholder-and-help-text), [length](add-plugin-configuration#text-length-restrictions) | URL field         | <https://example.com>                     |
| password      | [placeholder](add-plugin-configuration#label-placeholder-and-help-text), [length](add-plugin-configuration#text-length-restrictions)                                                | Password field    | \*\*\*\*\*\*\*\*                                |
| int           | [length](add-plugin-configuration#number-length-restrictions)                                                                                                                       | Number field      | 42                                      |
| float         | [length](add-plugin-configuration#number-length-restrictions)                                                                                                                       | Number field      | 42.42                                   |
| bool          |                                                                                                                                                                                     | Switch            | `true` or `false`                       |
| checkbox      |                                                                                                                                                                                     | Checkbox          | `true` or `false`                       |
| datetime      |                                                                                                                                                                                     | Date-time picker  | 2024-04-04T12:00:00.000Z                |
| date          |                                                                                                                                                                                     | Date picker       | 2024-04-05T00:00:00                     |
| time          |                                                                                                                                                                                     | Time picker       | 11:00:00                                |
| colorpicker   |                                                                                                                                                                                     | Color picker      | #189EFF                                 |
| single-select | [options](add-plugin-configuration#options), [placeholder](add-plugin-configuration#label-placeholder-and-help-text)                                                                | Single-Select box | option\_id                               |
| multi-select  | [options](add-plugin-configuration#options), [placeholder](add-plugin-configuration#label-placeholder-and-help-text)                                                                | Multi-Select box  | \[option\_id1, option\_id2]                |

### Input field settings

These settings are used to configure your `<input-field>`.
**Every `<input-field>` has to start with the `<name>` element.**
After the `<name>` element you can configure any of the other settings mentioned above.
Beside these settings, they have the following in common:
[label](add-plugin-configuration#label-placeholder-and-help-text),
[helpText](add-plugin-configuration#label-placeholder-and-help-text),
[defaultValue](add-plugin-configuration#defaultvalue),
[disabled](add-plugin-configuration#disabled),
and [required](add-plugin-configuration#required).

#### Label, placeholder and help text

The settings `<label>`, `<placeholder>` and `<helpText>` are used to label and explain your `<input-field>` and are translatable.
You define your `<label>`, `<placeholder>` and `<helpText>` the same way as the `<card><title>`, with the `lang` attribute.
Please remember, that the `lang` attribute is set to `en-GB` per default.

#### defaultValue

Add the `defaultValue` setting to your `<input-field>` to define a default value for it.
This value will be imported into the database on installing and updating the plugin.
We use [Symfony\Component\Config\Util\XmlUtils](https://github.com/symfony/config/blob/7.1/Util/XmlUtils.php#L211) for casting the values into the correct PHP types.

Below, you'll find an example of how to use this setting.

```html
<input-field type="text">
    <name>textField</name>
    <label>Test field with default value</label>
    <defaultValue>test</defaultValue>
</input-field>
```

#### disabled

You can add the `<disabled>` setting to any of your `<input-field>` elements to disable it.

Below, you'll find an example of how to use this setting.

```html
<input-field>
    <name>email</name>
    <disabled>true</disabled>
</input-field>
```

*Please note, `<disabled>` only accepts boolean values.*

#### required

You can add the `<required>` setting to any of your `<input-field>` elements to mark it accordingly.

Below, you'll find an example of how to use this setting.

```html
<input-field>
    <name>email</name>
    <required>true</required>
</input-field>
```

*Please note, `<required>` only accepts boolean values.*

#### copyable

You can add the `<copyable>` setting to your `<input-field>` which are of type `text` or extensions of it.
This will add a button at the right, which on click copies the content of your `<input-field>` into the clipboard.

Below, you'll find an example of how to use this setting.

```html
<input-field>
    <name>email</name>
    <copyable>true</copyable>
</input-field>
```

*Please note, that `<copyable>` only accepts boolean values*

#### Text length restrictions

You can add the `<minLength>`/`<maxLength>` settings to your `<input-field>` which are of type `text`, `url` or `password`.
With those you can restrict the length of the input.

Below, you'll find an example of how to use this setting.

```html
<input-field type="password">
    <name>token</name>
    <minLength>5</minLength>
    <maxLength>20</maxLength>
</input-field>
```

#### Number length restrictions

You can add the `<min>`/`<max>` settings to your `<input-field>` which are of type `int` or `float`.
With those you can restrict the minimum and maximum value of the input.

Below, you'll find an example of how to use this setting.

```html
<input-field type="int">
    <name>token</name>
    <min>5</min>
    <max>20</max>
</input-field>
```

#### options

You can use `<options>` to add settings to a `<input-field>` of the types `single-select` and `multi-select`.
Each `<option>` represents one setting you can select.

Below you'll find an example.

```html
<input-field type="single-select">
    <name>mailMethod</name>
    <options>
        <option>
            <id>smtp</id>
            <name>English label</name>
            <name lang="de-DE">German label</name>
        </option>
        <option>
            <id>pop3</id>
            <name>English label</name>
            <name lang="de-DE">German label</name>
        </option>
    </options>
</input-field>
```

Each `<options>` element must contain at least one `<option>` element.
Each `<option>` element must contain at least one `<id>` and one `<name>` element.
As you can see above, `<name>` elements are translatable via the `lang` attribute.

### Advanced custom input fields

For more complex and advanced configurations it is possible to declare a `<component name="componentName">` element.
This element can render many admin components.
It is also possible to render your own admin component which you could deliver with your plugin.
The name of the component has to match the components name in the Administration, for example `sw-entity-single-select`.
The component also needs a `<name>` element first.
All other elements within the component element will be passed to the rendered admin component as properties.
For some components you could also use [`label` and `placeholder`](add-plugin-configuration#label-placeholder-and-help-text).

Here are some examples:

### Entity single select for products

```html
<component name="sw-entity-single-select">
    <name>exampleProduct</name>
    <entity>product</entity>
    <label>Choose a product for the plugin configuration</label>
</component>
```

Stores the ID of the selected product into the system config.

### Entity multi ID select for products

```html
<component name="sw-entity-multi-id-select">
    <name>exampleMultiProductIds</name>
    <entity>product</entity>
    <label>Choose multiple products IDs for the plugin configuration</label>
</component>
```

Stores an array with IDs of the selected products into the system config.

### Media selection

```html
<component name="sw-media-field">
    <name>pluginMedia</name>
    <label>Upload media or choose one from the media manager</label>
</component>
```

### Text editor

```html
<component name="sw-text-editor">
    <name>textEditor</name>
    <label>Write some nice text with WYSIWYG editor</label>
</component>
```

### Snippet field

```html
<component name="sw-snippet-field">
    <name>snippetField</name>
    <label>Description</label>
    <snippet>myPlugin.test.snippet</snippet>
</component>
```

Allows you to edit snippet values within the configuration page.
This component does not store values in the system config, but changes the translations for the snippet key.
**Note: This field is only available from 6.3.4.0 onward.**

### Supported component types

Please Note: It is impossible to allow every component in the `config.xml`, due to their complexities.
If you can't efficiently resolve your plugin's necessities with, it is probably better to create an own module instead.
Therefore, Shopware supports the following components by default (also to be found in the [ConfigValidator class](https://github.com/shopware/shopware/blob/v6.6.7.0/src/Core/Framework/App/Validation/ConfigValidator.php#L18)):

* sw-entity-single-select
* sw-entity-multi-id-select
* sw-media-field
* sw-text-editor
* sw-snippet-field

## Example

Now all that's left to do is to present you a working example `config.xml` and show you the result.

```xml
<!--<plugin root>/src/Resources/config/config.xml-->
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/SystemConfig/Schema/config.xsd">

    <card>
        <title>Basic Configuration</title>
        <title lang="de-DE">Grundeinstellungen</title>

        <input-field>
            <name>email</name>
            <copyable>true</copyable>
            <label>eMail address</label>
            <label lang="de-DE">E-Mailadresse</label>
            <placeholder>you@example.com</placeholder>
            <placeholder lang="de-DE">du@beispiel.de</placeholder>
            <helpText>Please fill in your personal eMail address</helpText>
            <helpText lang="de-DE">Bitte trage deine persönliche E-Mailadresse ein</helpText>
        </input-field>

        <input-field type="single-select">
            <name>mailMethod</name>
            <options>
                <option>
                    <id>smtp</id>
                    <name>English smtp</name>
                    <name lang="de-DE">German smtp</name>
                </option>
                <option>
                    <id>pop3</id>
                    <name>English pop3</name>
                    <name lang="de-DE">German pop3</name>
                </option>
            </options>
            <defaultValue>smtp</defaultValue>
            <label>Mail method</label>
            <label lang="de-DE">Versand-Protokoll</label>
        </input-field>
    </card>

    <card>
        <title>Advanced Configuration</title>
        <title lang="de-DE">Erweiterte Einstellungen</title>

        <input-field type="password">
            <name>secret</name>
            <label>Secret token</label>
            <label lang="de-DE">Geheimschlüssel</label>
            <helpText>Your secret token for xyz...</helpText>
            <helpText lang="de-DE">Dein geheimer Schlüssel für xyz...</helpText>
        </input-field>
    </card>
</config>
```

## Add values to your configuration

After adding your input fields to the `config.xml`, you can add values to your configuration.
To do so, navigate from the sidebar to the `Extensions` > `My extensions` > `Apps` tab and click `Configure`.
Now you can see the `Configuration` tab and fill in the values for your input fields.

## Next steps

Now you've added your own plugin configuration.
But how do you actually read which configurations the shop owner used?
This will be covered in our guide about [Using the plugin configuration](use-plugin-configuration).

---

---
url: /docs/guides/plugins/plugins/dependencies/add-plugin-dependencies.md
---

# Add Plugin Dependencies

## Overview

Shopware 6 supports declaring dependencies on other plugins that must be installed in the system. This is done using Composer’s `require` feature. More information is available in the [official Composer documentation](https://getcomposer.org/doc/04-schema.md#package-links).

## Setup

Each plugin for Shopware 6 has to own a `composer.json` file for it to be a valid plugin. Creating a plugin is not explained here, make sure to read our [Plugin base guide](../plugin-base-guide.md) first.

Since every plugin has to own a `composer.json` file, you can simply refer to this plugin by its technical name and its version mentioned in the respective plugin's `composer.json`.

So, those are example lines of the `SwagBasicExample` plugin's `composer.json`:

```json
{
    "name": "swag/swag-basic-example",
    "description": "Plugin quick start plugin",
    "version": "v1.0.0",
    ...
}
```

Important to note is the `name` as well as the `version` mentioned here, the rest of the file is not important for this case here. You're going to need those two information to require them in your own plugin.

In order to require the `SwagBasicExample` plugin now, you simply have to add these two information to your own `composer.json` as a key value pair:

```javascript
// <plugin root>/composer.json
{
    "name": "swag/plugin-dependency",
    "description": "Plugin requiring other plugins",
    "version": "v1.0.0",
    "type": "shopware-platform-plugin",
    "license": "MIT",
    "authors": [
        {
            "name": "shopware AG",
            "role": "Manufacturer"
        }
    ],
    "require": {
        "shopware/core": "6.1.*",
        "swag/SwagBasicExample": "v1.0.0"
    },
    "extra": {
        "shopware-plugin-class": "Swag\\PluginDependency\\PluginDependency",
        "label": {
            "de-DE": "Plugin mit Plugin-Abhängigkeiten",
            "en-GB": "Plugin with plugin dependencies"
        },
        "description": {
            "de-DE": "Plugin mit Plugin-Abhängigkeiten",
            "en-GB": "Plugin with plugin dependencies"
        }
    },
    "autoload": {
        "psr-4": {
            "Swag\\PluginDependency\\": "src/"
        }
    }
}
```

Have a detailed look at the `require` keyword, which now requires both the Shopware 6 version, which **always** has to be mentioned in your `composer.json`, as well as the previously mentioned plugin and its version. Just as in composer itself, you can also use version wildcards, such as `v1.0.*` to only require the other plugin's minor version to be 1.1, not taking the patch version into account when it comes to find the matching plugin version.

Now your plugin isn't installable anymore, until that requirement is fulfilled.

## More interesting topics

* [Using Composer dependencies](using-composer-dependencies.md)
* [Using NPM dependencies](using-npm-dependencies.md)

---

---
url: >-
  /docs/v6.5/guides/plugins/plugins/plugin-fundamentals/add-plugin-dependencies.md
---

# Add Plugin Dependencies

New in Shopware 6 is the possibility to properly require on other plugins to be in the system. This is done using the `require` feature from composer. Further information about this can be found in the [official composer documentation](https://getcomposer.org/doc/04-schema.md#package-links).

## Setup

Each plugin for Shopware 6 has to own a `composer.json` file for it to be a valid plugin. Creating a plugin is not explained here, make sure to read our [Plugin base guide](../plugin-base-guide) first.

Since every plugin has to own a `composer.json` file, you can simply refer to this plugin by its technical name and its version mentioned in the respective plugin's `composer.json`.

So, those are example lines of the `SwagBasicExample` plugin's `composer.json`:

```json
{
    "name": "swag/swag-basic-example",
    "description": "Plugin quick start plugin",
    "version": "v1.0.0",
    ...
}
```

Important to note is the `name` as well as the `version` mentioned here, the rest of the file is not important for this case here. You're going to need those two information to require them in your own plugin.

In order to require the `SwagBasicExample` plugin now, you simply have to add these two information to your own `composer.json` as a key value pair:

```js
// <plugin root>/composer.json
{
    "name": "swag/plugin-dependency",
    "description": "Plugin requiring other plugins",
    "version": "v1.0.0",
    "type": "shopware-platform-plugin",
    "license": "MIT",
    "authors": [
        {
            "name": "shopware AG",
            "role": "Manufacturer"
        }
    ],
    "require": {
        "shopware/core": "6.1.*",
        "swag/SwagBasicExample": "v1.0.0"
    },
    "extra": {
        "shopware-plugin-class": "Swag\\PluginDependency\\PluginDependency",
        "label": {
            "de-DE": "Plugin mit Plugin-Abhängigkeiten",
            "en-GB": "Plugin with plugin dependencies"
        },
        "description": {
            "de-DE": "Plugin mit Plugin-Abhängigkeiten",
            "en-GB": "Plugin with plugin dependencies"
        }
    },
    "autoload": {
        "psr-4": {
            "Swag\\PluginDependency\\": "src/"
        }
    }
}
```

Have a detailed look at the `require` keyword, which now requires both the Shopware 6 version, which **always** has to be mentioned in your `composer.json`, as well as the previously mentioned plugin and its version. Just as in composer itself, you can also use version wildcards, such as `v1.0.*` to only require the other plugin's minor version to be 1.1, not taking the patch version into account when it comes to find the matching plugin version.

Now your plugin isn't installable anymore, until that requirement is fulfilled.

## More interesting topics

* [Using Composer dependencies](using-composer-dependencies)
* [Using NPM dependencies](using-npm-dependencies)

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/plugin-fundamentals/add-plugin-dependencies.md
---

# Add Plugin Dependencies

New in Shopware 6 is the possibility to properly require on other plugins to be in the system. This is done using the `require` feature from composer. Further information about this can be found in the [official composer documentation](https://getcomposer.org/doc/04-schema.md#package-links).

## Setup

Each plugin for Shopware 6 has to own a `composer.json` file for it to be a valid plugin. Creating a plugin is not explained here, make sure to read our [Plugin base guide](../plugin-base-guide) first.

Since every plugin has to own a `composer.json` file, you can simply refer to this plugin by its technical name and its version mentioned in the respective plugin's `composer.json`.

So, those are example lines of the `SwagBasicExample` plugin's `composer.json`:

```json
{
    "name": "swag/swag-basic-example",
    "description": "Plugin quick start plugin",
    "version": "v1.0.0",
    ...
}
```

Important to note is the `name` as well as the `version` mentioned here, the rest of the file is not important for this case here. You're going to need those two information to require them in your own plugin.

In order to require the `SwagBasicExample` plugin now, you simply have to add these two information to your own `composer.json` as a key value pair:

```javascript
// <plugin root>/composer.json
{
    "name": "swag/plugin-dependency",
    "description": "Plugin requiring other plugins",
    "version": "v1.0.0",
    "type": "shopware-platform-plugin",
    "license": "MIT",
    "authors": [
        {
            "name": "shopware AG",
            "role": "Manufacturer"
        }
    ],
    "require": {
        "shopware/core": "6.1.*",
        "swag/SwagBasicExample": "v1.0.0"
    },
    "extra": {
        "shopware-plugin-class": "Swag\\PluginDependency\\PluginDependency",
        "label": {
            "de-DE": "Plugin mit Plugin-Abhängigkeiten",
            "en-GB": "Plugin with plugin dependencies"
        },
        "description": {
            "de-DE": "Plugin mit Plugin-Abhängigkeiten",
            "en-GB": "Plugin with plugin dependencies"
        }
    },
    "autoload": {
        "psr-4": {
            "Swag\\PluginDependency\\": "src/"
        }
    }
}
```

Have a detailed look at the `require` keyword, which now requires both the Shopware 6 version, which **always** has to be mentioned in your `composer.json`, as well as the previously mentioned plugin and its version. Just as in composer itself, you can also use version wildcards, such as `v1.0.*` to only require the other plugin's minor version to be 1.1, not taking the patch version into account when it comes to find the matching plugin version.

Now your plugin isn't installable anymore, until that requirement is fulfilled.

## More interesting topics

* [Using Composer dependencies](using-composer-dependencies)
* [Using NPM dependencies](using-npm-dependencies)

---

---
url: >-
  /docs/resources/references/adr/2021-11-23-add-possibility-for-plugin-to-add-a-html-file.md
---

# Add possibility for plugins to add a HTML file

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2021-11-23-add-possibility-for-plugin-to-add-a-html-file.md)
:::

## Context

The new ExtensionAPI is based on a iFrame communication architecture. The old App system for the admin relies on the XML
file. And the normal plugin architecture in the admin is based on component overriding. The ideal way for developing
admin extensions will be the ExtensionAPI.

## Decision

To provide a smooth transition for plugin developer to the new ExtensionAPI which will be introduced soon we need to make sure that plugin can also
behave like Apps in the administration. To fulfill this we need to provide a solution to show their own iFrame views.
This is now directly possible when the plugin developer adds a `index.html` file to the plugin in the administration folder.

This file will automatically be used by webpack and can be used like a normal web application.

---

---
url: >-
  /docs/v6.5/resources/references/adr/2021-11-23-add-possibility-for-plugin-to-add-a-html-file.md
---

# Add possibility for plugins to add a HTML file

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2021-11-23-add-possibility-for-plugin-to-add-a-html-file.md)
:::

## Context

The new ExtensionAPI is based on a iFrame communication architecture. The old App system for the admin relies on the XML
file. And the normal plugin architecture in the admin is based on component overriding. The ideal way for developing
admin extensions will be the ExtensionAPI.

## Decision

To provide a smooth transition for plugin developer to the new ExtensionAPI which will be introduced soon we need to make sure that plugin can also
behave like Apps in the administration. To fulfill this we need to provide a solution to show their own iFrame views.
This is now directly possible when the plugin developer adds a `index.html` file to the plugin in the administration folder.

This file will automatically be used by webpack and can be used like a normal web application.

---

---
url: >-
  /docs/v6.6/resources/references/adr/2021-11-23-add-possibility-for-plugin-to-add-a-html-file.md
---

# Add possibility for plugins to add a HTML file

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2021-11-23-add-possibility-for-plugin-to-add-a-html-file.md)
:::

## Context

The new ExtensionAPI is based on a iFrame communication architecture. The old App system for the admin relies on the XML
file. And the normal plugin architecture in the admin is based on component overriding. The ideal way for developing
admin extensions will be the ExtensionAPI.

## Decision

To provide a smooth transition for plugin developer to the new ExtensionAPI which will be introduced soon we need to make sure that plugin can also
behave like Apps in the administration. To fulfill this we need to provide a solution to show their own iFrame views.
This is now directly possible when the plugin developer adds a `index.html` file to the plugin in the administration folder.

This file will automatically be used by webpack and can be used like a normal web application.

---

---
url: >-
  /docs/guides/plugins/plugins/framework/rate-limiter/add-rate-limiter-to-api-route.md
---

# Add Rate Limiter to API Route

## Overview

A rate limiter controls the rate or frequency at which API requests can be made. It sets limits on the number of requests that can be processed within a specified time period, preventing excessive usage and reducing the risk of brute-force attacks. This helps to maintain system stability, protect against misuse, and ensure fair resource allocation.

In this guide you'll learn how to secure API routes with a rate limit to reduce the risk against bruteforce attacks.
If you want to learn more about the configuration of the rate limiter in Shopware,
have a look at the [Rate limiter](../../../../hosting/infrastructure/rate-limiter.md) guide.

## Prerequisites

This guide is built upon both the [Plugin base guide](../../plugin-base-guide.md) as well as the [Dependency injection](../../services/dependency-injection.md) guide.

Furthermore you need an existing API route, to create a new one, head over to our [Add Store API route](../store-api/add-store-api-route.md) guide.

## Creating a new rate limit

### Basic configuration for plugins

First of all, we have to create a new configuration file for our rate limit. In this example we named it `rate_limiter.yaml` located in `<plugin root>/src/Resources/config/`.
The root key of the configuration is the name which has to be a unique key. In this example we named it `example_route`.

Each rate limit configuration needs the following keys:

* `enabled`: Enables / Disables the rate limit for the specific route (default value: true).
* `policy`: Possible policies are `fixed_window`, `sliding_window`, `token_bucket`, `time_backoff`. For more information check the [Symfony documentation](https://symfony.com/doc/current/rate_limiter.html#rate-limiting-policies).

If you plan to configure the `time_backoff` policy, head over to [rate limiter](../../../../hosting/infrastructure/rate-limiter.md#configuring-time-backoff-policy) guide.
Otherwise, check the [Symfony documentation](https://symfony.com/doc/current/rate_limiter.html#configuration) for the other keys you need for each policy.

```yaml
// <plugin root>/src/Resources/config/rate_limiter.yaml
example_route:
    enabled: true
    policy: 'time_backoff'
```

### Extending rate limit configuration in the DI-container

In this section we will create a small compiler pass called `RateLimiterCompilerPass`. If you are not very familiar with compiler passes,
head over to the [Symfony documentation](https://symfony.com/doc/current/service_container/compiler_passes.html).

### Creating compiler pass

```php
// <plugin root>/src/CompilerPass/RateLimiterCompilerPass.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\CompilerPass;

use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\Yaml\Yaml;

class RateLimiterCompilerPass implements CompilerPassInterface
{
    public function process(ContainerBuilder $container): void
    {
        /** @var array<string, array<string, string>> $rateLimiterConfig */
        $rateLimiterConfig = $container->getParameter('shopware.api.rate_limiter');

        $rateLimiterConfig += Yaml::parseFile(__DIR__ . '/../Resources/config/rate_limiter.yaml');

        $container->setParameter('shopware.api.rate_limiter', $rateLimiterConfig);
    }
}
```

As you can see, we're getting the current configuration of the rate limit from the DI-container and extend it by our `rate_limiter.yaml`
and reassign it with the merged configuration.

### Adding compiler pass to the container

Now, we have to add our compiler pass to the container. This will be done by overriding the `build()` method of
our `SwagBasicExample` plugin class. Important here is to use `Symfony\Component\DependencyInjection\Compiler\PassConfig::TYPE_BEFORE_OPTIMIZATION`
with a higher priority, otherwise it will be built too late.

```php
// <plugin root>/src/SwagBasicExample.php
<?php declare(strict_types=1);

namespace Swag\BasicExample;

use Swag\BasicExample\CompilerPass\RateLimiterCompilerPass;
use Shopware\Core\Framework\Plugin;
use Shopware\Core\Framework\Plugin\Context\InstallContext;
use Symfony\Component\DependencyInjection\Compiler\PassConfig;
use Symfony\Component\DependencyInjection\ContainerBuilder;

class SwagBasicExample extends Plugin
{
    public function build(ContainerBuilder $container): void
    {
        parent::build($container);

        $container->addCompilerPass(new RateLimiterCompilerPass(), PassConfig::TYPE_BEFORE_OPTIMIZATION, 500);
    }
}
```

## Implementing rate limit in API route

### Inject service

After we've configured our rate limit, we want to use it in our API route.
For this we need to inject the `Shopware\Core\Framework\RateLimiter\RateLimiter` service.

```php
// <plugin root>/src/Core/Content/Example/SalesChannel/ExampleRoute.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\SalesChannel;

use Shopware\Core\Framework\Routing\StoreApiRouteScope;
use Shopware\Core\PlatformRequest;
use Shopware\Core\Framework\RateLimiter\RateLimiter;
...

#[Route(defaults: [PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [StoreApiRouteScope::ID]])]
class ExampleRoute extends AbstractExampleRoute
{
    private RateLimiter $rateLimiter;

    public function __construct(RateLimiter $rateLimiter)
    {
        $this->rateLimiter = $rateLimiter;
    }

    ...
}
```

### Call the rate limiter

After we've injected the service into our API route, we can call the limiter in our route method.

To do this, we call the method `ensureAccepted` of the rate limiter which accepts the following arguments:

* `route`: Unique name of the rate limit, we defined in the configuration.
* `key`: Key we want to use to limit the request e.g., the client IP.

When calling the `ensureAccepted` method it counts the request for the key in the defined cache.
If the limit has been exceeded, it throws `Shopware\Core\Framework\RateLimiter\Exception\RateLimitExceededException`.

```php
// <plugin root>/src/Core/Content/Example/SalesChannel/ExampleRoute.php

#[Route(path: '/store-api/example', name: 'store-api.example.search', methods: ['GET','POST'])]
public function load(Request $request, SalesChannelContext $context): ExampleRouteResponse
{
    // Limit ip address
    $this->rateLimiter->ensureAccepted('example_route', $request->getClientIp());
    
    ...
}
```

### Reset the rate limit

Once we've made a successful request, we want to reset the rate limit for the client.
We just have to call the `reset` method as you can see below.

```php
// <plugin root>/src/Core/Content/Example/SalesChannel/ExampleRoute.php

#[Route(path: '/store-api/example', name: 'store-api.example.search', methods: ['GET','POST'])]
public function load(Request $request, SalesChannelContext $context): ExampleRouteResponse
{
    // Limit ip address for example
    $this->rateLimiter->ensureAccepted('example_route', $request->getClientIp());
    
    // if action was successfully, reset limit
    if ($this->doAction() === true) {
        $this->rateLimiter->reset('example_route', $request->getClientIp());
    }
    
    ...
}
```

---

---
url: >-
  /docs/v6.5/guides/plugins/plugins/framework/rate-limiter/add-rate-limiter-to-api-route.md
---

# Add Rate Limiter to API Route

## Overview

In this guide you'll learn how to secure API routes with a rate limit to reduce the risk against bruteforce attacks.
If you want to learn more about the configuration of the rate limiter in Shopware,
have a look at the [Rate limiter](../../../../hosting/infrastructure/rate-limiter) guide.

## Prerequisites

This guide is built upon both the [Plugin base guide](../../plugin-base-guide) as well as the [Dependency injection](../../plugin-fundamentals/dependency-injection) guide.

Furthermore you need an existing API route, to create a new one, head over to our [Add store API route](../store-api/add-store-api-route) guide.

## Creating a new rate limit

### Basic configuration for plugins

First of all, we have to create a new configuration file for our rate limit. In this example we named it `rate_limiter.yaml` located in `<plugin root>/src/Resources/config/`.
The root key of the configuration is the name which has to be a unique key. In this example we named it `example_route`.

Each rate limit configuration needs the following keys:

* `enabled`: Enables / Disables the rate limit for the specific route (default value: true).
* `policy`: Possible policies are `fixed_window`, `sliding_window`, `token_bucket`, `time_backoff`. For more information check the [Symfony documentation](https://symfony.com/doc/current/rate_limiter.html#rate-limiting-policies).

If you plan to configure the `time_backoff` policy, head over to [rate limiter](../../../../hosting/infrastructure/rate-limiter#configuring-time-backoff-policy) guide.
Otherwise, check the [Symfony documentation](https://symfony.com/doc/current/rate_limiter.html#configuration) for the other keys you need for each policy.

```yaml
// <plugin root>/src/Resources/config/rate_limiter.yaml
example_route:
    enabled: true
    policy: 'time_backoff'
```

### Extending rate limit configuration in the DI-container

In this section we will create a small compiler pass called `RateLimiterCompilerPass`. If you are not very familiar with compiler passes,
head over to the [Symfony documentation](https://symfony.com/doc/current/service_container/compiler_passes.html).

### Creating compiler pass

```php
// <plugin root>/src/CompilerPass/RateLimiterCompilerPass.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\CompilerPass;

use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\Yaml\Yaml;

class RateLimiterCompilerPass implements CompilerPassInterface
{
    public function process(ContainerBuilder $container): void
    {
        /** @var array<string, array<string, string>> $rateLimiterConfig */
        $rateLimiterConfig = $container->getParameter('shopware.api.rate_limiter');

        $rateLimiterConfig += Yaml::parseFile(__DIR__ . '/../Resources/config/rate_limiter.yaml');

        $container->setParameter('shopware.api.rate_limiter', $rateLimiterConfig);
    }
}
```

As you can see, we're getting the current configuration of the rate limit from the DI-container and extend it by our `rate_limiter.yaml`
and reassign it with the merged configuration.

### Adding compiler pass to the container

Now, we have to add our compiler pass to the container. This will be done by overriding the `build()` method of
our `SwagBasicExample` plugin class. Important here is to use `Symfony\Component\DependencyInjection\Compiler\PassConfig::TYPE_BEFORE_OPTIMIZATION`
with a higher priority, otherwise it will be built too late.

```php
// <plugin root>/src/SwagBasicExample.php
<?php declare(strict_types=1);

namespace Swag\BasicExample;

use Swag\BasicExample\CompilerPass\RateLimiterCompilerPass;
use Shopware\Core\Framework\Plugin;
use Shopware\Core\Framework\Plugin\Context\InstallContext;
use Symfony\Component\DependencyInjection\Compiler\PassConfig;
use Symfony\Component\DependencyInjection\ContainerBuilder;

class SwagBasicExample extends Plugin
{
    public function build(ContainerBuilder $container): void
    {
        parent::build($container);

        $container->addCompilerPass(new RateLimiterCompilerPass(), PassConfig::TYPE_BEFORE_OPTIMIZATION, 500);
    }
}
```

## Implementing rate limit in API route

### Inject service

After we've configured our rate limit, we want to use it in our API route.
For this we need to inject the `Shopware\Core\Framework\RateLimiter\RateLimiter` service.

```php
// <plugin root>/src/Core/Content/Example/SalesChannel/ExampleRoute.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\SalesChannel;

use Shopware\Core\Framework\RateLimiter\RateLimiter;
...

#[Route(defaults: ['_routeScope' => ['store-api']])]
class ExampleRoute extends AbstractExampleRoute
{
    private RateLimiter $rateLimiter;

    public function __construct(RateLimiter $rateLimiter)
    {
        $this->rateLimiter = $rateLimiter;
    }

    ...
}
```

### Call the rate limiter

After we've injected the service into our API route, we can call the limiter in our route method.

To do this, we call the method `ensureAccepted` of the rate limiter which accepts the following arguments:

* `route`: Unique name of the rate limit, we defined in the configuration.
* `key`: Key we want to use to limit the request e.g., the client IP.

When calling the `ensureAccepted` method it counts the request for the key in the defined cache.
If the limit has been exceeded, it throws `Shopware\Core\Framework\RateLimiter\Exception\RateLimitExceededException`.

```php
// <plugin root>/src/Core/Content/Example/SalesChannel/ExampleRoute.php

#[Route(path: '/store-api/example', name: 'store-api.example.search', methods: ['GET','POST'])]
public function load(Request $request, SalesChannelContext $context): ExampleRouteResponse
{
    // Limit ip address
    $this->rateLimiter->ensureAccepted('example_route', $request->getClientIp());
    
    ...
}
```

### Reset the rate limit

Once we've made a successful request, we want to reset the rate limit for the client.
We just have to call the `reset` method as you can see below.

```php
// <plugin root>/src/Core/Content/Example/SalesChannel/ExampleRoute.php

#[Route(path: '/store-api/example', name: 'store-api.example.search', methods: ['GET','POST'])]
public function load(Request $request, SalesChannelContext $context): ExampleRouteResponse
{
    // Limit ip address for example
    $this->rateLimiter->ensureAccepted('example_route', $request->getClientIp());
    
    // if action was successfully, reset limit 
    if ($this->doAction() === true) {
        $this->rateLimiter->reset('example_route', $request->getClientIp());
    }
    
    ...
}
```

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/framework/rate-limiter/add-rate-limiter-to-api-route.md
---

# Add Rate Limiter to API Route

## Overview

In this guide you'll learn how to secure API routes with a rate limit to reduce the risk against bruteforce attacks.
If you want to learn more about the configuration of the rate limiter in Shopware,
have a look at the [Rate limiter](../../../../hosting/infrastructure/rate-limiter) guide.

## Prerequisites

This guide is built upon both the [Plugin base guide](../../plugin-base-guide) as well as the [Dependency injection](../../plugin-fundamentals/dependency-injection) guide.

Furthermore you need an existing API route, to create a new one, head over to our [Add store API route](../store-api/add-store-api-route) guide.

## Creating a new rate limit

### Basic configuration for plugins

First of all, we have to create a new configuration file for our rate limit. In this example we named it `rate_limiter.yaml` located in `<plugin root>/src/Resources/config/`.
The root key of the configuration is the name which has to be a unique key. In this example we named it `example_route`.

Each rate limit configuration needs the following keys:

* `enabled`: Enables / Disables the rate limit for the specific route (default value: true).
* `policy`: Possible policies are `fixed_window`, `sliding_window`, `token_bucket`, `time_backoff`. For more information check the [Symfony documentation](https://symfony.com/doc/current/rate_limiter.html#rate-limiting-policies).

If you plan to configure the `time_backoff` policy, head over to [rate limiter](../../../../hosting/infrastructure/rate-limiter#configuring-time-backoff-policy) guide.
Otherwise, check the [Symfony documentation](https://symfony.com/doc/current/rate_limiter.html#configuration) for the other keys you need for each policy.

```yaml
// <plugin root>/src/Resources/config/rate_limiter.yaml
example_route:
    enabled: true
    policy: 'time_backoff'
```

### Extending rate limit configuration in the DI-container

In this section we will create a small compiler pass called `RateLimiterCompilerPass`. If you are not very familiar with compiler passes,
head over to the [Symfony documentation](https://symfony.com/doc/current/service_container/compiler_passes.html).

### Creating compiler pass

```php
// <plugin root>/src/CompilerPass/RateLimiterCompilerPass.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\CompilerPass;

use Symfony\Component\DependencyInjection\Compiler\CompilerPassInterface;
use Symfony\Component\DependencyInjection\ContainerBuilder;
use Symfony\Component\Yaml\Yaml;

class RateLimiterCompilerPass implements CompilerPassInterface
{
    public function process(ContainerBuilder $container): void
    {
        /** @var array<string, array<string, string>> $rateLimiterConfig */
        $rateLimiterConfig = $container->getParameter('shopware.api.rate_limiter');

        $rateLimiterConfig += Yaml::parseFile(__DIR__ . '/../Resources/config/rate_limiter.yaml');

        $container->setParameter('shopware.api.rate_limiter', $rateLimiterConfig);
    }
}
```

As you can see, we're getting the current configuration of the rate limit from the DI-container and extend it by our `rate_limiter.yaml`
and reassign it with the merged configuration.

### Adding compiler pass to the container

Now, we have to add our compiler pass to the container. This will be done by overriding the `build()` method of
our `SwagBasicExample` plugin class. Important here is to use `Symfony\Component\DependencyInjection\Compiler\PassConfig::TYPE_BEFORE_OPTIMIZATION`
with a higher priority, otherwise it will be built too late.

```php
// <plugin root>/src/SwagBasicExample.php
<?php declare(strict_types=1);

namespace Swag\BasicExample;

use Swag\BasicExample\CompilerPass\RateLimiterCompilerPass;
use Shopware\Core\Framework\Plugin;
use Shopware\Core\Framework\Plugin\Context\InstallContext;
use Symfony\Component\DependencyInjection\Compiler\PassConfig;
use Symfony\Component\DependencyInjection\ContainerBuilder;

class SwagBasicExample extends Plugin
{
    public function build(ContainerBuilder $container): void
    {
        parent::build($container);

        $container->addCompilerPass(new RateLimiterCompilerPass(), PassConfig::TYPE_BEFORE_OPTIMIZATION, 500);
    }
}
```

## Implementing rate limit in API route

### Inject service

After we've configured our rate limit, we want to use it in our API route.
For this we need to inject the `Shopware\Core\Framework\RateLimiter\RateLimiter` service.

```php
// <plugin root>/src/Core/Content/Example/SalesChannel/ExampleRoute.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\SalesChannel;

use Shopware\Core\Framework\RateLimiter\RateLimiter;
...

#[Route(defaults: ['_routeScope' => ['store-api']])]
class ExampleRoute extends AbstractExampleRoute
{
    private RateLimiter $rateLimiter;

    public function __construct(RateLimiter $rateLimiter)
    {
        $this->rateLimiter = $rateLimiter;
    }

    ...
}
```

### Call the rate limiter

After we've injected the service into our API route, we can call the limiter in our route method.

To do this, we call the method `ensureAccepted` of the rate limiter which accepts the following arguments:

* `route`: Unique name of the rate limit, we defined in the configuration.
* `key`: Key we want to use to limit the request e.g., the client IP.

When calling the `ensureAccepted` method it counts the request for the key in the defined cache.
If the limit has been exceeded, it throws `Shopware\Core\Framework\RateLimiter\Exception\RateLimitExceededException`.

```php
// <plugin root>/src/Core/Content/Example/SalesChannel/ExampleRoute.php

#[Route(path: '/store-api/example', name: 'store-api.example.search', methods: ['GET','POST'])]
public function load(Request $request, SalesChannelContext $context): ExampleRouteResponse
{
    // Limit ip address
    $this->rateLimiter->ensureAccepted('example_route', $request->getClientIp());
    
    ...
}
```

### Reset the rate limit

Once we've made a successful request, we want to reset the rate limit for the client.
We just have to call the `reset` method as you can see below.

```php
// <plugin root>/src/Core/Content/Example/SalesChannel/ExampleRoute.php

#[Route(path: '/store-api/example', name: 'store-api.example.search', methods: ['GET','POST'])]
public function load(Request $request, SalesChannelContext $context): ExampleRouteResponse
{
    // Limit ip address for example
    $this->rateLimiter->ensureAccepted('example_route', $request->getClientIp());
    
    // if action was successfully, reset limit 
    if ($this->doAction() === true) {
        $this->rateLimiter->reset('example_route', $request->getClientIp());
    }
    
    ...
}
```

---

---
url: >-
  /docs/v6.5/guides/plugins/plugins/administration/add-rule-assignment-configuration.md
---

# Add rule assignment configuration

::: info
The rule assignment configuration is available from Shopware Version 6.4.8.0
:::

## Overview

You want to create a custom card in the rule assignment, where you can add or delete assignments? This guide gets you covered on this topic. Based on an example of the configuration of the `Dynamic Access` plugin, you will see how to write your configuration.

![](../../../../assets/add-rule-assignment-configuration-0.png)

## Prerequisites

This guide **does not** explain how to create a new plugin for Shopware 6.
Head over to our Plugin base guide to learn how to create a plugin at first:

## Creating the index.js file

The first step is creating a new directory like so `<plugin root>/src/Resources/app/administration/src/module/sw-settings-rule/extension/sw-settings-rule-detail-assignments`.
Right afterwards, create a new file called `index.js` in there.

Your custom module directory isn't known to Shopware 6 yet.
The entry point of your plugin is the `main.js` file.
That's the file you need to change now, so that it loads your extended component.
For this, simply add the following line to your `main.js` file:

```javascript
// <plugin root>/src/Resources/app/administration/src/main.js
import './module/sw-settings-rule/extension/sw-settings-rule-detail-assignments';
```

Now your module's `index.js` will be executed.

## Override the component

Your `index.js` is still empty now, so let's override the `sw-settings-rule-detail-assignments` component.
This is technically done by calling the method `override` method of our [ComponentFactory](https://github.com/shopware/shopware/blob/trunk/src/Administration/Resources/app/administration/src/core/factory/async-component.factory.ts), which is available through our third party wrapper.
This method expects a name, and a configuration for the component you want to override.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-settings-rule/extension/sw-settings-rule-detail-assignments/index.js
Component.override('sw-settings-rule-detail-assignments', {
    // override configuration here
});
```

## Overriding the computed

Now your plugin is overriding the `sw-settings-rule-detail-assignments` component, but currently this has no effect.
In the `associationEntitiesConfig` computed property the configuration of the rule assignment is built and returned to the method which initiates the component.
Because of this, you have to override this computed property, get the computed property of the original component, add your own configuration of the rule assignment and return the whole configuration array.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-settings-rule/extension/sw-settings-rule-detail-assignments/index.js
Component.override('sw-settings-rule-detail-assignments', {
    computed: {
        associationEntitiesConfig() {
            const associationEntitiesConfig = this.$super('associationEntitiesConfig');
            associationEntitiesConfig.push(/* insert your configuration here */);
            return associationEntitiesConfig;
        },
    }
});
```

## Adding the configuration

The configuration of the rule assignment is passed as an object and offers a wide range of options.
Just have a look onto one example configuration item of the `Dynamic Access` plugin:

```javascript
// Example of a configuration item
getRuleAssignmentConfig()
{
    return [
        {
            id: 'swagDynamicAccessProducts',
            notAssignedDataTotal: 0,
            entityName: 'product',
            label: 'swag-dynamic-access.sw-settings-rule.detail.associations.productVisibility',
            criteria: () => {
                const criteria = new Criteria();
                criteria.setLimit(this.associationLimit);
                criteria.addFilter(Criteria.equals('swagDynamicAccessRules.id', this.rule.id));
                criteria.addAssociation('options.group');
                criteria.addAssociation('swagDynamicAccessRules');

                return criteria;
            },
            api: () => {
                const api = Object.assign({}, Context.api);
                api.inheritance = true;

                return api;
            },
            detailRoute: 'sw.product.detail.base',
            gridColumns: [
                {
                    property: 'name',
                    label: 'Name',
                    rawData: true,
                    sortable: true,
                    routerLink: 'sw.product.detail.prices',
                    allowEdit: false,
                },
            ],
            deleteContext: {
                type: 'many-to-many',
                entity: 'product',
                column: 'extensions.swagDynamicAccessRules',
            },
            addContext: {
                type: 'many-to-many',
                entity: 'swag_dynamic_access_product_rule',
                column: 'productId',
                searchColumn: 'name',
                criteria: () => {
                    const criteria = new Criteria();
                    criteria.addFilter(
                            Criteria.not('AND', [Criteria.equals('swagDynamicAccessRules.id', this.rule.id)]),
                    );
                    criteria.addAssociation('options.group');

                    return criteria;
                },
                gridColumns: [
                    {
                        property: 'name',
                        label: 'Name',
                        rawData: true,
                        sortable: true,
                        allowEdit: false,
                    },
                    // ...
                ],
            },
        },
    ];
}
```

Let's go through the most important entries, how to configure your rule assignment:

| Option | Description |
| :--- | :--- |
| id | Required identifier for the assignment, which is arbitrary but unique |
| entityName, criteria, api | Required for data loading of the assignment |
| gridColumns | To define the columns, which are shown in your assignment card. Have a look into the [data grid component](using-the-data-grid-component) for more information. |

### Provide to delete an assignment

If you want to provide to delete an assignment, you have to define the `deleteContext`. There are two types of the `deleteContext`.
The first one is the `one-to-many` type, which link to a column of the assignment entity like this:

```js
// Example of a one-to-many deleteContext
deleteContext: {
    type: 'one-to-many',
    entity: 'cms_block',
    column: 'extensions.swagCmsExtensionsBlockRule.visibilityRuleId',
},
```

The other type is `many-to-many`, which has to link to the `ManyToManyAssociationField` of the extension like this:

```js
// Example of a many-to-many deleteContext
deleteContext: {
    type: 'many-to-many',
    entity: 'category',
    column: 'extensions.swagDynamicAccessRules',
},
```

### Provide to add an assignment

If you want to provide to add an assignment, you have to define the `addContext`. This context has the same two types as the `deleteContext` (see above),
but the `addContext` has more options to fill out, because an add assignment modal has to be configured:

```js
// Example of a one-to-many addContext
addContext: {
    type: 'one-to-many',
    entity: 'shipping_method',
    column: 'availabilityRuleId',
    searchColumn: 'name',
    criteria: () => {
        const criteria = new Criteria();
        criteria.addFilter(Criteria.not(
            'AND',
            [Criteria.equals('availabilityRuleId', ruleId)],
        ));

        return criteria;
    },
    gridColumns: [
        {
            property: 'name',
            label: 'Name',
            rawData: true,
            sortable: true,
            allowEdit: false,
        },
        {
            property: 'description',
            label: 'Description',
            rawData: true,
            sortable: true,
            allowEdit: false,
        },
        {
            property: 'taxType',
            label: 'Tax calculation',
            rawData: true,
            sortable: true,
            allowEdit: false,
        },
        {
            property: 'active',
            label: 'Active',
            rawData: true,
            sortable: true,
            allowEdit: false,
        },
    ],
},
```

The `addContext` needs a definition of the `gridColumns`, the `entity` and the `criteria`, like in the general configuration.
Also, the context needs the `column` of the assignment and the `searchColumn` of the assigned entity.

A context of the `many-to-many` type would look like this:

```js
// Example of a many-to-many addContext
addContext: {
    type: 'many-to-many',
    entity: 'swag_dynamic_access_category_rule',
    column: 'categoryId',
    searchColumn: 'name',
    association: 'swagDynamicAccessRules',
    criteria: () => {
        const criteria = new Criteria();
        criteria.addFilter(Criteria.equals('parentId', null));

        return criteria;
    },
    gridColumns: [
        // Definition of columns
    ],
},
```

Beside the properties of a `one-to-many` type you have to define the `association` with the name of the `ManyToManyAssociationField`.

## Further reading

For more other information, refer to [Add custom rules](../framework/rule/add-custom-rules).

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/administration/advanced-configuration/add-rule-assignment-configuration.md
---

# Add rule assignment configuration

::: info
The rule assignment configuration is available from Shopware Version 6.4.8.0
:::

## Overview

You want to create a custom card in the rule assignment, where you can add or delete assignments? This guide gets you covered on this topic. Based on an example of the configuration of the `Dynamic Access` plugin, you will see how to write your configuration.

![Rule config](../../../../../assets/add-rule-assignment-configuration-0.png)

## Prerequisites

This guide **does not** explain how to create a new plugin for Shopware 6.
Head over to our Plugin base guide to learn how to create a plugin at first:

## Creating the index.js file

The first step is creating a new directory like so `<plugin root>/src/Resources/app/administration/src/module/sw-settings-rule/extension/sw-settings-rule-detail-assignments`.
Right afterward, create a new file called `index.js` in there.

Your custom module directory isn't known to Shopware 6 yet.
The entry point of your plugin is the `main.js` file.
That's the file you need to change now, so that it loads your extended component.
For this, simply add the following line to your `main.js` file:

```javascript
// <plugin root>/src/Resources/app/administration/src/main.js
import './module/sw-settings-rule/extension/sw-settings-rule-detail-assignments';
```

Now your module's `index.js` will be executed.

## Override the component

Your `index.js` is still empty now, so let's override the `sw-settings-rule-detail-assignments` component.
This is technically done by calling the method `override` method of our [ComponentFactory](https://github.com/shopware/shopware/blob/trunk/src/Administration/Resources/app/administration/src/core/factory/async-component.factory.ts), which is available through our third party wrapper.
This method expects a name, and a configuration for the component you want to override.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-settings-rule/extension/sw-settings-rule-detail-assignments/index.js
Component.override('sw-settings-rule-detail-assignments', {
    // override configuration here
});
```

## Overriding the computed

Now your plugin is overriding the `sw-settings-rule-detail-assignments` component, but currently this has no effect.
In the `associationEntitiesConfig` computed property the configuration of the rule assignment is built and returned to the method which initiates the component.
Because of this, you have to override this computed property, get the computed property of the original component, add your own configuration of the rule assignment and return the whole configuration array.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-settings-rule/extension/sw-settings-rule-detail-assignments/index.js
Component.override('sw-settings-rule-detail-assignments', {
    computed: {
        associationEntitiesConfig() {
            const associationEntitiesConfig = this.$super('associationEntitiesConfig');
            associationEntitiesConfig.push(/* insert your configuration here */);
            return associationEntitiesConfig;
        },
    }
});
```

## Adding the configuration

The configuration of the rule assignment is passed as an object and offers a wide range of options.
Just have a look onto one example configuration item of the `Dynamic Access` plugin:

```javascript
// Example of a configuration item
getRuleAssignmentConfig()
{
    return [
        {
            id: 'swagDynamicAccessProducts',
            notAssignedDataTotal: 0,
            entityName: 'product',
            label: 'swag-dynamic-access.sw-settings-rule.detail.associations.productVisibility',
            criteria: () => {
                const criteria = new Criteria();
                criteria.setLimit(this.associationLimit);
                criteria.addFilter(Criteria.equals('swagDynamicAccessRules.id', this.rule.id));
                criteria.addAssociation('options.group');
                criteria.addAssociation('swagDynamicAccessRules');

                return criteria;
            },
            api: () => {
                const api = Object.assign({}, Context.api);
                api.inheritance = true;

                return api;
            },
            detailRoute: 'sw.product.detail.base',
            gridColumns: [
                {
                    property: 'name',
                    label: 'Name',
                    rawData: true,
                    sortable: true,
                    routerLink: 'sw.product.detail.prices',
                    allowEdit: false,
                },
            ],
            deleteContext: {
                type: 'many-to-many',
                entity: 'product',
                column: 'extensions.swagDynamicAccessRules',
            },
            addContext: {
                type: 'many-to-many',
                entity: 'swag_dynamic_access_product_rule',
                column: 'productId',
                searchColumn: 'name',
                criteria: () => {
                    const criteria = new Criteria();
                    criteria.addFilter(
                            Criteria.not('AND', [Criteria.equals('swagDynamicAccessRules.id', this.rule.id)]),
                    );
                    criteria.addAssociation('options.group');

                    return criteria;
                },
                gridColumns: [
                    {
                        property: 'name',
                        label: 'Name',
                        rawData: true,
                        sortable: true,
                        allowEdit: false,
                    },
                    // ...
                ],
            },
        },
    ];
}
```

Let's go through the most important entries, how to configure your rule assignment:

| Option                    | Description                                                                                                                                                                                    |
|:--------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| id                        | Required identifier for the assignment, which is arbitrary but unique                                                                                                                          |
| entityName, criteria, api | Required for data loading of the assignment                                                                                                                                                    |
| gridColumns               | To define the columns, which are shown in your assignment card. Have a look into the [data grid component](../data-handling-processing/using-the-data-grid-component.md) for more information. |

### Provide to delete an assignment

If you want to provide to delete an assignment, you have to define the `deleteContext`. There are two types of the `deleteContext`.
The first one is the `one-to-many` type, which link to a column of the assignment entity like this:

```javascript
// Example of a one-to-many deleteContext
deleteContext: {
    type: 'one-to-many',
    entity: 'cms_block',
    column: 'extensions.swagCmsExtensionsBlockRule.visibilityRuleId',
},
```

The other type is `many-to-many`, which has to link to the `ManyToManyAssociationField` of the extension like this:

```javascript
// Example of a many-to-many deleteContext
deleteContext: {
    type: 'many-to-many',
    entity: 'category',
    column: 'extensions.swagDynamicAccessRules',
},
```

### Provide to add an assignment

If you want to provide to add an assignment, you have to define the `addContext`. This context has the same two types as the `deleteContext` (see above),
but the `addContext` has more options to fill out, because an add assignment modal has to be configured:

```javascript
// Example of a one-to-many addContext
addContext: {
    type: 'one-to-many',
    entity: 'shipping_method',
    column: 'availabilityRuleId',
    searchColumn: 'name',
    criteria: () => {
        const criteria = new Criteria();
        criteria.addFilter(Criteria.not(
            'AND',
            [Criteria.equals('availabilityRuleId', ruleId)],
        ));

        return criteria;
    },
    gridColumns: [
        {
            property: 'name',
            label: 'Name',
            rawData: true,
            sortable: true,
            allowEdit: false,
        },
        {
            property: 'description',
            label: 'Description',
            rawData: true,
            sortable: true,
            allowEdit: false,
        },
        {
            property: 'taxType',
            label: 'Tax calculation',
            rawData: true,
            sortable: true,
            allowEdit: false,
        },
        {
            property: 'active',
            label: 'Active',
            rawData: true,
            sortable: true,
            allowEdit: false,
        },
    ],
},
```

The `addContext` needs a definition of the `gridColumns`, the `entity` and the `criteria`, like in the general configuration.
Also, the context needs the `column` of the assignment and the `searchColumn` of the assigned entity.

A context of the `many-to-many` type would look like this:

```javascript
// Example of a many-to-many addContext
addContext: {
    type: 'many-to-many',
    entity: 'swag_dynamic_access_category_rule',
    column: 'categoryId',
    searchColumn: 'name',
    association: 'swagDynamicAccessRules',
    criteria: () => {
        const criteria = new Criteria();
        criteria.addFilter(Criteria.equals('parentId', null));

        return criteria;
    },
    gridColumns: [
        // Definition of columns
    ],
},
```

Beside the properties of a `one-to-many` type you have to define the `association` with the name of the `ManyToManyAssociationField`.

## Further reading

For more other information, refer to [Add custom rules](../../framework/rule/add-custom-rules.md).

---

---
url: >-
  /docs/guides/plugins/plugins/administration/advanced-configuration/add-rule-assignment-configuration.md
---

# Add Rule Assignment Configuration

::: info
The rule assignment configuration is available from Shopware Version 6.4.8.0
:::

## Overview

You want to create a custom card in the rule assignment, where you can add or delete assignments? This guide gets you covered on this topic. Based on an example of the configuration of the `Dynamic Access` plugin, you will see how to write your configuration.

![Rule config](../../../../../assets/add-rule-assignment-configuration-0.png)

## Prerequisites

This guide **does not** explain how to create a new plugin for Shopware 6.
Head over to our Plugin base guide to learn how to create a plugin at first:

## Creating the index.js file

The first step is creating a new directory like so `<plugin root>/src/Resources/app/administration/src/module/sw-settings-rule/extension/sw-settings-rule-detail-assignments`.
Right afterward, create a new file called `index.js` in there.

Your custom module directory isn't known to Shopware 6 yet.
The entry point of your plugin is the `main.js` file.
That's the file you need to change now, so that it loads your extended component.
For this, simply add the following line to your `main.js` file:

```javascript
// <plugin root>/src/Resources/app/administration/src/main.js
import './module/sw-settings-rule/extension/sw-settings-rule-detail-assignments';
```

Now your module's `index.js` will be executed.

## Override the component

Your `index.js` is still empty now, so let's override the `sw-settings-rule-detail-assignments` component.
This is technically done by calling the method `override` method of our [ComponentFactory](https://github.com/shopware/shopware/blob/trunk/src/Administration/Resources/app/administration/src/core/factory/async-component.factory.ts), which is available through our third party wrapper.
This method expects a name, and a configuration for the component you want to override.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-settings-rule/extension/sw-settings-rule-detail-assignments/index.js
Component.override('sw-settings-rule-detail-assignments', {
    // override configuration here
});
```

## Overriding the computed

Now your plugin is overriding the `sw-settings-rule-detail-assignments` component, but currently this has no effect.
In the `associationEntitiesConfig` computed property the configuration of the rule assignment is built and returned to the method which initiates the component.
Because of this, you have to override this computed property, get the computed property of the original component, add your own configuration of the rule assignment and return the whole configuration array.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/sw-settings-rule/extension/sw-settings-rule-detail-assignments/index.js
Component.override('sw-settings-rule-detail-assignments', {
    computed: {
        associationEntitiesConfig() {
            const associationEntitiesConfig = this.$super('associationEntitiesConfig');
            associationEntitiesConfig.push(/* insert your configuration here */);
            return associationEntitiesConfig;
        },
    }
});
```

## Adding the configuration

The configuration of the rule assignment is passed as an object and offers a wide range of options.
Just have a look onto one example configuration item of the `Dynamic Access` plugin:

```javascript
// Example of a configuration item
getRuleAssignmentConfig()
{
    return [
        {
            id: 'swagDynamicAccessProducts',
            notAssignedDataTotal: 0,
            entityName: 'product',
            label: 'swag-dynamic-access.sw-settings-rule.detail.associations.productVisibility',
            criteria: () => {
                const criteria = new Criteria();
                criteria.setLimit(this.associationLimit);
                criteria.addFilter(Criteria.equals('swagDynamicAccessRules.id', this.rule.id));
                criteria.addAssociation('options.group');
                criteria.addAssociation('swagDynamicAccessRules');

                return criteria;
            },
            api: () => {
                const api = Object.assign({}, Context.api);
                api.inheritance = true;

                return api;
            },
            detailRoute: 'sw.product.detail.base',
            gridColumns: [
                {
                    property: 'name',
                    label: 'Name',
                    rawData: true,
                    sortable: true,
                    routerLink: 'sw.product.detail.prices',
                    allowEdit: false,
                },
            ],
            deleteContext: {
                type: 'many-to-many',
                entity: 'product',
                column: 'extensions.swagDynamicAccessRules',
            },
            addContext: {
                type: 'many-to-many',
                entity: 'swag_dynamic_access_product_rule',
                column: 'productId',
                searchColumn: 'name',
                criteria: () => {
                    const criteria = new Criteria();
                    criteria.addFilter(
                            Criteria.not('AND', [Criteria.equals('swagDynamicAccessRules.id', this.rule.id)]),
                    );
                    criteria.addAssociation('options.group');

                    return criteria;
                },
                gridColumns: [
                    {
                        property: 'name',
                        label: 'Name',
                        rawData: true,
                        sortable: true,
                        allowEdit: false,
                    },
                    // ...
                ],
            },
        },
    ];
}
```

Let's go through the most important entries, how to configure your rule assignment:

| Option                    | Description                                                                                                                                                                                    |
|:--------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| id                        | Required identifier for the assignment, which is arbitrary but unique                                                                                                                          |
| entityName, criteria, api | Required for data loading of the assignment                                                                                                                                                    |
| gridColumns               | To define the columns, which are shown in your assignment card. Have a look into the [data grid component](../data-handling-processing/using-the-data-grid-component.md) for more information. |

### Provide to delete an assignment

If you want to provide to delete an assignment, you have to define the `deleteContext`. There are two types of the `deleteContext`.
The first one is the `one-to-many` type, which link to a column of the assignment entity like this:

```javascript
// Example of a one-to-many deleteContext
deleteContext: {
    type: 'one-to-many',
    entity: 'cms_block',
    column: 'extensions.swagCmsExtensionsBlockRule.visibilityRuleId',
},
```

The other type is `many-to-many`, which has to link to the `ManyToManyAssociationField` of the extension like this:

```javascript
// Example of a many-to-many deleteContext
deleteContext: {
    type: 'many-to-many',
    entity: 'category',
    column: 'extensions.swagDynamicAccessRules',
},
```

### Provide to add an assignment

If you want to provide to add an assignment, you have to define the `addContext`. This context has the same two types as the `deleteContext` (see above),
but the `addContext` has more options to fill out, because an add assignment modal has to be configured:

```javascript
// Example of a one-to-many addContext
addContext: {
    type: 'one-to-many',
    entity: 'shipping_method',
    column: 'availabilityRuleId',
    searchColumn: 'name',
    criteria: () => {
        const criteria = new Criteria();
        criteria.addFilter(Criteria.not(
            'AND',
            [Criteria.equals('availabilityRuleId', ruleId)],
        ));

        return criteria;
    },
    gridColumns: [
        {
            property: 'name',
            label: 'Name',
            rawData: true,
            sortable: true,
            allowEdit: false,
        },
        {
            property: 'description',
            label: 'Description',
            rawData: true,
            sortable: true,
            allowEdit: false,
        },
        {
            property: 'taxType',
            label: 'Tax calculation',
            rawData: true,
            sortable: true,
            allowEdit: false,
        },
        {
            property: 'active',
            label: 'Active',
            rawData: true,
            sortable: true,
            allowEdit: false,
        },
    ],
},
```

The `addContext` needs a definition of the `gridColumns`, the `entity` and the `criteria`, like in the general configuration.
Also, the context needs the `column` of the assignment and the `searchColumn` of the assigned entity.

A context of the `many-to-many` type would look like this:

```javascript
// Example of a many-to-many addContext
addContext: {
    type: 'many-to-many',
    entity: 'swag_dynamic_access_category_rule',
    column: 'categoryId',
    searchColumn: 'name',
    association: 'swagDynamicAccessRules',
    criteria: () => {
        const criteria = new Criteria();
        criteria.addFilter(Criteria.equals('parentId', null));

        return criteria;
    },
    gridColumns: [
        // Definition of columns
    ],
},
```

Beside the properties of a `one-to-many` type you have to define the `association` with the name of the `ManyToManyAssociationField`.

## Further reading

For more other information, refer to [Add custom rules](../../framework/rule/add-custom-rules.md).

---

---
url: /docs/guides/plugins/plugins/plugin-fundamentals/add-scheduled-task.md
---

# Add Scheduled Task

Quite often one might want to run any type of code on a regular basis, e.g. to clean up very old entries every once in a while, automatically. Usually known as "Cronjobs", Shopware 6 supports a `ScheduledTask` for this.

## Prerequisites

This guide builds on the [Plugin Base Guide](../plugin-base-guide.md). Familiarity with `services.php` is helpful — see [Dependency Injection](../services/dependency-injection.md) and [Creating a service](../services/add-custom-service.md).

::: info
Refer to this video on **[Adding scheduled tasks](https://www.youtube.com/watch?v=88S9P3x6wYE)**. Also, available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

## Registering a scheduled task in the DI container

A `ScheduledTask` and its respective `ScheduledTaskHandler` are registered in a plugin's `services.php`. For it to be found by Shopware 6 automatically, you need to place the `services.php` file in a `Resources/config/` directory, relative to the location of your plugin's base class. The path could look like this: `<plugin root>/src/Resources/config/services.php`.

Here's an example `services.php` containing a new `ScheduledTask` as well as a new `ScheduledTaskHandler`:

```php
// <plugin root>/src/Resources/config/services.php
<?php declare(strict_types=1);

use Swag\BasicExample\Service\ScheduledTask\ExampleTask;
use Swag\BasicExample\Service\ScheduledTask\ExampleTaskHandler;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(ExampleTask::class)
        ->tag('shopware.scheduled.task');

    $services->set(ExampleTaskHandler::class)
        ->args([
            service('scheduled_task.repository'),
            service('logger'),
        ])
        ->tag('messenger.message_handler');
};
```

Note the tags required for both the task and its respective handler, `shopware.scheduled.task` and `messenger.message_handler`. Your custom task will now be saved into the database once your plugin is activated.

## ScheduledTask and its handler

The `services.php` file references both the task and its handler from `Service/ScheduledTask`. This directory name is a convention — you can use a different path as long as the namespace matches.

Here's an example `ScheduledTask`:

```php
// <plugin root>/src/Service/ScheduledTask/ExampleTask.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service\ScheduledTask;

use Shopware\Core\Framework\MessageQueue\ScheduledTask\ScheduledTask;

class ExampleTask extends ScheduledTask
{
    public static function getTaskName(): string
    {
        return 'swag.example_task';
    }

    public static function getDefaultInterval(): int
    {
        return 300; // 5 minutes
    }
}
```

Your `ExampleTask` class has to extend from the `Shopware\Core\Framework\MessageQueue\ScheduledTask\ScheduledTask` class, which will force you to implement two methods:

* `getTaskName`: The technical name of your task. Make sure to add a vendor prefix to your custom task to prevent collisions with other plugins' scheduled tasks. In this example this is `swag`.
* `getDefaultInterval`: The interval in seconds at which your scheduled task should be executed.

The respective task handler:

```php
// <plugin root>/src/Service/ScheduledTask/ExampleTaskHandler.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service\ScheduledTask;

use Shopware\Core\Framework\MessageQueue\ScheduledTask\ScheduledTaskHandler;
use Symfony\Component\Messenger\Attribute\AsMessageHandler;

#[AsMessageHandler(handles: ExampleTask::class)]
class ExampleTaskHandler extends ScheduledTaskHandler
{
    public function run(): void
    {
        // ...
    }
}
```

The task handler, `ExampleTaskHandler` as defined previously in your `services.php`, will be annotated with `AsMessageHandler` handling the `ExampleTask` class. In addition, the `ScheduledTaskHandler` has to extend from the class `Shopware\Core\Framework\MessageQueue\ScheduledTask\ScheduledTaskHandler`. This also comes with one method that you need to implement first:

* `run`: This method is executed when the scheduled task runs. Implement your task logic here.

Every five minutes, Shopware will dispatch the task to the message bus and the handler's `run()` method will be executed.

## Dynamic rescheduling

::: info
Available since Shopware version 6.7.13.0
:::

By default, a scheduled task is rescheduled to run again after its configured `runInterval` (initially taken from `getDefaultInterval()`), i.e. `nextExecutionTime + runInterval` (capped to `now` if it would lie in the past). If you want to control *when* the task runs next based on your own domain data — for example, scheduling the next run to the timestamp of the next pending record instead of a fixed interval — let your handler implement the `Shopware\Core\Framework\MessageQueue\ScheduledTask\DynamicallyScheduledTaskHandler` interface.

Shopware asks the handler for the next execution time and persists it for you, so the handler only answers the "when", not the "how":

```php
// <plugin root>/src/Service/ScheduledTask/ExampleTaskHandler.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service\ScheduledTask;

use Shopware\Core\Framework\MessageQueue\ScheduledTask\DynamicallyScheduledTaskHandler;
use Shopware\Core\Framework\MessageQueue\ScheduledTask\ScheduledTask;
use Shopware\Core\Framework\MessageQueue\ScheduledTask\ScheduledTaskEntity;
use Shopware\Core\Framework\MessageQueue\ScheduledTask\ScheduledTaskHandler;
use Symfony\Component\Messenger\Attribute\AsMessageHandler;

#[AsMessageHandler(handles: ExampleTask::class)]
class ExampleTaskHandler extends ScheduledTaskHandler implements DynamicallyScheduledTaskHandler
{
    public function run(): void
    {
        // ...
    }

    public function getNextExecutionTime(ScheduledTask $task, ScheduledTaskEntity $taskEntity): ?\DateTimeInterface
    {
        // return the time the task should next run at,
        // or null to fall back to the default `now + runInterval` schedule
        return $this->resolveNextPendingTimestamp();
    }
}
```

`getNextExecutionTime()` is called after `run()` finishes. Returning `null` falls back to the default interval-based schedule. If the returned time lies in the past, Shopware runs the task again as soon as possible.

## Executing the scheduled task

Usually scheduled tasks are registered when installing or updating your plugin. If you don't want to reinstall your plugin in order to register your scheduled task, you can also use the following command to achieve this:
`bin/console scheduled-task:register`

In order to properly test your scheduled task, you first have to run the command `bin/console scheduled-task:run`. This will start the `ScheduledTaskRunner`, which takes care of your scheduled tasks and their respective timings. It will dispatch a message to the message bus once your scheduled task's interval is due.

Now you still need to run the command `bin/console messenger:consume` to actually execute the dispatched messages. Make sure, that the `status` of your scheduled task is set to `scheduled` in the `scheduled_task` table, otherwise it won't be executed. This is not necessary, when you're using the admin worker.

## Debugging scheduled tasks

You can directly run a single scheduled task without the queue. This is useful for debugging purposes or to have better control of when and which tasks are executed. You can use `bin/console scheduled-task:run-single <task-name>` to run a single task. Example:

```shell
bin/console scheduled-task:run-single log_entry.cleanup
```

::: info
Available starting with Shopware 6.7.2.0.
:::

You can schedule a scheduled task with the command `scheduled-task:schedule` or deactivate a scheduled task with the command `scheduled-task:deactivate`

```shell
bin/console scheduled-task:schedule log_entry.cleanup
bin/console scheduled-task:deactivate log_entry.cleanup
```

## Next steps

[Adding a custom command](add-custom-commands.md)

---

---
url: /docs/v6.5/guides/plugins/plugins/plugin-fundamentals/add-scheduled-task.md
---

# Add Scheduled Task

## Overview

Quite often one might want to run any type of code on a regular basis, e.g. to clean up very old entries every once in a while, automatically. Usually known as "Cronjobs", Shopware 6 supports a `ScheduledTask` for this.

## Prerequisites

This guide is built upon our [plugin base guide](../plugin-base-guide), but that one is not mandatory. Knowing how the `services.xml` file in a plugin works is also helpful, which will be taught in our guides about [Dependency Injection](dependency-injection) and [Creating a service](add-custom-service). It is shortly explained here as well though, so no worries!

::: info
Refer to this video on **[Adding scheduled tasks](https://www.youtube.com/watch?v=88S9P3x6wYE)**. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

## Registering scheduled task in the DI container

A `ScheduledTask` and its respective `ScheduledTaskHandler` are registered in a plugin's `services.xml`. For it to be found by Shopware 6 automatically, you need to place the `services.xml` file in a `Resources/config/` directory, relative to the location of your plugin's base class. The path could look like this: `<plugin root>/src/Resources/config/services.xml`.

Here's an example `services.xml` containing a new `ScheduledTask` as well as a new `ScheduledTaskHandler`:

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
    <services>
        <service id="Swag\BasicExample\Service\ScheduledTask\ExampleTask">
            <tag name="shopware.scheduled.task" />
        </service>
        <service id="Swag\BasicExample\Service\ScheduledTask\ExampleTaskHandler">
            <argument type="service" id="scheduled_task.repository" />
            <tag name="messenger.message_handler" />
        </service>
    </services>
</container>
```

Note the tags required for both the task and its respective handler, `shopware.scheduled.task` and `messenger.message_handler`. Your custom task will now be saved into the database once your plugin is activated.

## ScheduledTask and its handler

As you might have noticed, the `services.xml` file tries to find both the task itself as well as the new task handler in a directory called `Service/ScheduledTask`. This naming is up to you, Shopware 6 decided to use this name though.

Here's the an example `ScheduledTask`:

```php
// <plugin root>/src/Service/ScheduledTask/ExampleTask.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service\ScheduledTask;

use Shopware\Core\Framework\MessageQueue\ScheduledTask\ScheduledTask;

class ExampleTask extends ScheduledTask
{
    public static function getTaskName(): string
    {
        return 'swag.example_task';
    }

    public static function getDefaultInterval(): int
    {
        return 300; // 5 minutes
    }
}
```

Your `ExampleTask` class has to extend from the `Shopware\Core\Framework\MessageQueue\ScheduledTask\ScheduledTask` class, which will force you to implement two methods:

* `getTaskName`: The technical name of your task. Make sure to add a vendor prefix to your custom task, to prevent collisions with other plugin's scheduled tasks. In this example this is `swag`.
* `getDefaultInterval`: The interval in seconds at which your scheduled task should be executed.

And that's it for the `ExampleTask` class.

Following will be the respective task handler:

```php
// <plugin root>/src/Service/ScheduledTask/ExampleTaskHandler.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service\ScheduledTask;

use Shopware\Core\Framework\MessageQueue\ScheduledTask\ScheduledTaskHandler;

class ExampleTaskHandler extends ScheduledTaskHandler
{
    public static function getHandledMessages(): iterable
    {
        return [ ExampleTask::class ];
    }

    public function run(): void
    {
        file_put_contents('some/where/some/file.md', 'example');
    }
}
```

The respective task handler, `ExampleTaskHandler` as defined previously in your `services.xml`, has to extend from the class `Shopware\Core\Framework\MessageQueue\ScheduledTask\ScheduledTaskHandler`. This also comes with two methods, that you need to implement first:

* `getHandledMessages`: An iterable, or an array, of the scheduled tasks, that this handler will take care of. In this case this is only the `ExampleTask` class.
* `run`: This method is executed once your scheduled task is executed. Do everything, that your task is supposed to do here. In this example, it will just create a new file.

Now every five minutes, your task will be executed and it will print an output every time now.

## Executing the scheduled task

Usually scheduled tasks are registered when installing or updating your plugin. If you don't want to reinstall your plugin in order to register your scheduled task, you can also use the following command to achieve this:
`bin/console scheduled-task:register`

In order to properly test your scheduled task, you first have to run the command `bin/console scheduled-task:run`. This will start the `ScheduledTaskRunner`, which takes care of your scheduled tasks and their respective timings. It will dispatch a message to the message bus once your scheduled task's interval is due.

Now you still need to run the command `bin/console messenger:consume` to actually execute the dispatched messages. Make sure, that the `status` of your scheduled task is set to `scheduled` in the `scheduled_task` table, otherwise it won't be executed. This is not necessary, when you're using the admin worker.

## More interesting topics

* [Adding a custom command](add-custom-commands)

---

---
url: /docs/v6.6/guides/plugins/plugins/plugin-fundamentals/add-scheduled-task.md
---

# Add Scheduled Task

## Overview

Quite often one might want to run any type of code on a regular basis, e.g. to clean up very old entries every once in a while, automatically. Usually known as "Cronjobs", Shopware 6 supports a `ScheduledTask` for this.

## Prerequisites

This guide is built upon our [plugin base guide](../plugin-base-guide), but that one is not mandatory. Knowing how the `services.xml` file in a plugin works is also helpful, which will be taught in our guides about [Dependency Injection](dependency-injection) and [Creating a service](add-custom-service). It is shortly explained here as well though, so no worries!

::: info
Refer to this video on **[Adding scheduled tasks](https://www.youtube.com/watch?v=88S9P3x6wYE)**. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

## Registering scheduled task in the DI container

A `ScheduledTask` and its respective `ScheduledTaskHandler` are registered in a plugin's `services.xml`. For it to be found by Shopware 6 automatically, you need to place the `services.xml` file in a `Resources/config/` directory, relative to the location of your plugin's base class. The path could look like this: `<plugin root>/src/Resources/config/services.xml`.

Here's an example `services.xml` containing a new `ScheduledTask` as well as a new `ScheduledTaskHandler`:

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">
    <services>
        <service id="Swag\BasicExample\Service\ScheduledTask\ExampleTask">
            <tag name="shopware.scheduled.task" />
        </service>
        <service id="Swag\BasicExample\Service\ScheduledTask\ExampleTaskHandler">
            <argument type="service" id="scheduled_task.repository" />
            <tag name="messenger.message_handler" />
        </service>
    </services>
</container>
```

Note the tags required for both the task and its respective handler, `shopware.scheduled.task` and `messenger.message_handler`. Your custom task will now be saved into the database once your plugin is activated.

## ScheduledTask and its handler

As you might have noticed, the `services.xml` file tries to find both the task itself as well as the new task handler in a directory called `Service/ScheduledTask`. This naming is up to you, Shopware 6 decided to use this name though.

Here's the an example `ScheduledTask`:

```php
// <plugin root>/src/Service/ScheduledTask/ExampleTask.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service\ScheduledTask;

use Shopware\Core\Framework\MessageQueue\ScheduledTask\ScheduledTask;

class ExampleTask extends ScheduledTask
{
    public static function getTaskName(): string
    {
        return 'swag.example_task';
    }

    public static function getDefaultInterval(): int
    {
        return 300; // 5 minutes
    }
}
```

Your `ExampleTask` class has to extend from the `Shopware\Core\Framework\MessageQueue\ScheduledTask\ScheduledTask` class, which will force you to implement two methods:

* `getTaskName`: The technical name of your task. Make sure to add a vendor prefix to your custom task, to prevent collisions with other plugin's scheduled tasks. In this example this is `swag`.
* `getDefaultInterval`: The interval in seconds at which your scheduled task should be executed.

And that's it for the `ExampleTask` class.

Following will be the respective task handler:

```php
// <plugin root>/src/Service/ScheduledTask/ExampleTaskHandler.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service\ScheduledTask;

use Shopware\Core\Framework\MessageQueue\ScheduledTask\ScheduledTaskHandler;
use Symfony\Component\Messenger\Attribute\AsMessageHandler;

#[AsMessageHandler(handles: ExampleTask::class)]
class ExampleTaskHandler extends ScheduledTaskHandler
{
    public function run(): void
    {
        // ...
    }
}
```

The task handler, `ExampleTaskHandler` as defined previously in your `services.xml`, will be annotated with `AsMessageHandler` handling the `ExampleTask` class. In addition, the `ScheduledTaskHandler` has to extend from the class `Shopware\Core\Framework\MessageQueue\ScheduledTask\ScheduledTaskHandler`. This also comes with one method that you need to implement first:

* `run`: This method is executed once your scheduled task is executed. Do everything, that your task is supposed to do here. In this example, it will just create a new file.

Now every five minutes, your task will be executed and it will print an output every time now.

## Executing the scheduled task

Usually scheduled tasks are registered when installing or updating your plugin. If you don't want to reinstall your plugin in order to register your scheduled task, you can also use the following command to achieve this:
`bin/console scheduled-task:register`

In order to properly test your scheduled task, you first have to run the command `bin/console scheduled-task:run`. This will start the `ScheduledTaskRunner`, which takes care of your scheduled tasks and their respective timings. It will dispatch a message to the message bus once your scheduled task's interval is due.

Now you still need to run the command `bin/console messenger:consume` to actually execute the dispatched messages. Make sure, that the `status` of your scheduled task is set to `scheduled` in the `scheduled_task` table, otherwise it won't be executed. This is not necessary, when you're using the admin worker.

## Debugging scheduled tasks

You can directly run a single scheduled task without the queue. This is useful for debugging purposes or to have better control of when and which tasks are executed. You can use `bin/console scheduled-task:run-single <task-name>` to run a single task. Example:

```shell
bin/console scheduled-task:run-single log_entry.cleanup
```

## More interesting topics

* [Adding a custom command](add-custom-commands)

---

---
url: /docs/guides/plugins/themes/styling/add-css-js-to-theme.md
---

# Add SCSS Styling and JavaScript to a Theme

## Overview

This guide explains how you can add your custom styling via SCSS and add your custom JavaScript to your theme.

## Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files, as well as the command line. You also need to have an installed and activated theme which is assigned to a sales channel. Checkout the [Create a first theme](../create-a-theme.md) guide if you have not yet a working theme setup.

## Adding custom SCSS

When it comes to CSS and SCSS, they are processed by a PHP SASS compiler.

The main entry point to deploy your SCSS code is defined in the `theme.json` file. By default it is the `<plugin root>/app/storefront/src/scss/base.scss` file.

```javascript
// <plugin root>/src/Resources/theme.json
 {
   ...
   "style": [
     "app/storefront/src/scss/overrides.scss",
     "@Storefront",
     "app/storefront/src/scss/base.scss"
   ],
   ...
 }
```

When the Storefront gets compiled the PHP SASS compiler will look up the files declared in the `style` section of the theme configuration. You can define the SCSS entrypoints individually if you want to.

In order to add some custom SCSS in your theme, you just need to edit the `base.scss` file which in located in `<plugin root>/src/Resources/app/storefront/src/scss` directory.

```bash
.
├── composer.json
└── src
    ├── Resources
    │   ├── app
    │   │   └── storefront
    │   │       └── src
    │   │           └── scss
    │   │               └── base.scss <-- SCSS entry
    └── SwagBasicExampleTheme.php
```

To apply your styles and test them, please use some test code:

```css
// <plugin root>/src/Resources/app/storefront/src/scss/base.scss
body {
    background-color: blue;
}
```

Afterwards, you need to compile your theme by running the `bin/console theme:compile` command in terminal.

After your theme was compiled successfully, go and check your changes by opening the Storefront in your browser.

## Adding custom JS

JavaScript cannot be compiled by PHP, so [webpack](https://webpack.js.org/) is being used for that. All Javascript in Shopware 6 is written in EcmaScript 6. Of course you can write your code in EcmaScript 5 as well.

By default your plugin is using Shopware's default webpack configuration, as you must ship your theme with the JavaScript already compiled.

Since Shopware knows where your style files are located, they are automatically compiled, compressed and loaded into the Storefront. In the case of JavaScript, you have your `main.js` as entry point which has to be located the `src/Resources/app/storefront/src/` directory:

```bash
.
├── composer.json
└── src
    ├── Resources
    │   ├── app
    │   │   └── storefront
    │   │       └── src
    │   │           └── main.js <-- JS entry
    └── SwagBasicExampleTheme.php
```

Add some test code in order to see if it works out:

```javascript
// <plugin root>/src/Resources/app/storefront/src/js/main.js
console.log('SwagBasicExampleTheme JS loaded');
```

In the end, by running the command `shopware-cli project storefront-build` your custom JS plugin is loaded. By default, the compiled JavaScript file is saved as `<plugin root>/src/resources/app/storefront/dist/storefront/js/swag-basic-example-theme/swag-basic-example-theme.js`. It is detected by Shopware automatically and included in the Storefront. So you do not need to embed the JavaScript file yourself.

## Using the live reload

Of course, the theme compilation with `bin/console theme:compile` will get tedious if you change files a lot and want to check the changes in the browser. So there is a better way while you are developing your theme with the dev-server, which will give you the live reload feature.

To activate the dev-server, run the following command in your terminal.

```bash
shopware-cli project storefront-watch
```

```bash
# Since Shopware 6.7.11.0
composer run storefront:dev-server

# Before Shopware 6.7.11.0
composer run watch:storefront
```

This command starts a NodeJS web server on port `9998`. If you open the Storefront of your Shopware installation on `localhost:9998`, this page will be automatically updated when you make changes to your theme.

## Next steps

Now that you know how to customize the styling via SCSS and add JavaScript, here is a list of things you can do.

* [Override Bootstrap variables in a theme](override-bootstrap-variables-in-a-theme.md)
* [Customize templates](../../plugins/storefront/templates/customize-templates.md)

---

---
url: /docs/v6.5/guides/plugins/themes/add-css-js-to-theme.md
---

# Add SCSS Styling and JavaScript to a Theme

## Overview

This guide explains how you can add your custom styling via SCSS and add your custom JavaScript to your theme.

## Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files, as well as the command line. You also need to have an installed and activated theme which is assigned to a sales channel. Checkout the [Create a first theme](create-a-theme) guide if you have not yet a working theme setup.

## Adding custom SCSS

When it comes to CSS and SCSS, they are processed by a PHP SASS compiler.

The main entry point to deploy your SCSS code is defined in the `theme.json` file. By default it is the `<plugin root>/app/storefront/src/scss/base.scss` file.

```javascript
// <plugin root>/src/Resources/theme.json
 {
   ...
   "style": [
     "app/storefront/src/scss/overrides.scss",
     "@Storefront",
     "app/storefront/src/scss/base.scss"
   ],
   ...
 }
```

When the Storefront gets compiled the PHP SASS compiler will look up the files declared in the `style` section of the theme configuration. You can define the SCSS entrypoints individually if you want to.

In order to add some custom SCSS in your theme, you just need to edit the `base.scss` file which in located in `<plugin root>/src/Resources/app/storefront/src/scss` directory.

```bash
.
├── composer.json
└── src
    ├── Resources
    │   ├── app
    │   │   └── storefront
    │   │       └── src
    │   │           └── scss
    │   │               └── base.scss <-- SCSS entry
    └── SwagBasicExampleTheme.php
```

To apply your styles and test them, please use some test code:

```css
// <plugin root>/src/Resources/app/storefront/src/scss/base.scss
body {
    background-color: blue;
}
```

Afterwards, you need to compile your theme by running the `bin/console theme:compile` command in terminal.

After your theme was compiled successfully, go and check your changes by opening the Storefront in your browser.

## Adding custom JS

JavaScript cannot be compiled by PHP, so [webpack](https://webpack.js.org/) is being used for that. All Javascript in Shopware 6 is written in EcmaScript 6. Of course you can write your code in EcmaScript 5 as well.

By default your plugin is using Shopware's default webpack configuration, as you must ship your theme with the JavaScript already compiled.

Since Shopware knows where your style files are located, they are automatically compiled, compressed and loaded into the Storefront. In the case of JavaScript, you have your `main.js` as entry point which has to be located the `src/Resources/app/storefront/src/` directory:

```bash
.
├── composer.json
└── src
    ├── Resources
    │   ├── app
    │   │   └── storefront
    │   │       └── src
    │   │           └── main.js <-- JS entry
    └── SwagBasicExampleTheme.php
```

Add some test code in order to see if it works out:

```javascript
// <plugin root>/src/Resources/app/storefront/src/js/main.js
console.log('SwagBasicExampleTheme JS loaded');
```

In the end, by running the command `bin/build-storefront.sh` your custom JS plugin is loaded. By default, the compiled JavaScript file is saved as `<plugin root>/src/resources/app/storefront/dist/storefront/js/swag-basic-example-theme.js`. It is detected by Shopware automatically and included in the Storefront. So you do not need to embed the JavaScript file yourself.

## Using the hot-proxy (live reload)

Of course, the theme compilation with `bin/console theme:compile` will get tedious if you change files a lot and want to check the changes in the browser. So there is a better way while you are developing your theme with the `hot-proxy` option, which will give you the live reload feature.

To activate the hot-proxy, run the following command in your terminal.

```bash
./bin/watch-storefront.sh
```

```bash
composer run watch:storefront
```

This command starts a NodeJS web server on port `9998`. If you open the Storefront of your Shopware installation on `localhost:9998`, this page will be automatically updated when you make changes to your theme.

## Next steps

Now that you know how to customize the styling via SCSS and add JavaScript, here is a list of things you can do.

* [Override Bootstrap variables in a theme](override-bootstrap-variables-in-a-theme)
* [Customize templates](../plugins/storefront/customize-templates)

---

---
url: /docs/v6.6/guides/plugins/themes/add-css-js-to-theme.md
---

# Add SCSS Styling and JavaScript to a Theme

## Overview

This guide explains how you can add your custom styling via SCSS and add your custom JavaScript to your theme.

## Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files, as well as the command line. You also need to have an installed and activated theme which is assigned to a sales channel. Checkout the [Create a first theme](create-a-theme) guide if you have not yet a working theme setup.

## Adding custom SCSS

When it comes to CSS and SCSS, they are processed by a PHP SASS compiler.

The main entry point to deploy your SCSS code is defined in the `theme.json` file. By default it is the `<plugin root>/app/storefront/src/scss/base.scss` file.

```javascript
// <plugin root>/src/Resources/theme.json
 {
   ...
   "style": [
     "app/storefront/src/scss/overrides.scss",
     "@Storefront",
     "app/storefront/src/scss/base.scss"
   ],
   ...
 }
```

When the Storefront gets compiled the PHP SASS compiler will look up the files declared in the `style` section of the theme configuration. You can define the SCSS entrypoints individually if you want to.

In order to add some custom SCSS in your theme, you just need to edit the `base.scss` file which in located in `<plugin root>/src/Resources/app/storefront/src/scss` directory.

```bash
.
├── composer.json
└── src
    ├── Resources
    │   ├── app
    │   │   └── storefront
    │   │       └── src
    │   │           └── scss
    │   │               └── base.scss <-- SCSS entry
    └── SwagBasicExampleTheme.php
```

To apply your styles and test them, please use some test code:

```css
// <plugin root>/src/Resources/app/storefront/src/scss/base.scss
body {
    background-color: blue;
}
```

Afterwards, you need to compile your theme by running the `bin/console theme:compile` command in terminal.

After your theme was compiled successfully, go and check your changes by opening the Storefront in your browser.

## Adding custom JS

JavaScript cannot be compiled by PHP, so [webpack](https://webpack.js.org/) is being used for that. All Javascript in Shopware 6 is written in EcmaScript 6. Of course you can write your code in EcmaScript 5 as well.

By default your plugin is using Shopware's default webpack configuration, as you must ship your theme with the JavaScript already compiled.

Since Shopware knows where your style files are located, they are automatically compiled, compressed and loaded into the Storefront. In the case of JavaScript, you have your `main.js` as entry point which has to be located the `src/Resources/app/storefront/src/` directory:

```bash
.
├── composer.json
└── src
    ├── Resources
    │   ├── app
    │   │   └── storefront
    │   │       └── src
    │   │           └── main.js <-- JS entry
    └── SwagBasicExampleTheme.php
```

Add some test code in order to see if it works out:

```javascript
// <plugin root>/src/Resources/app/storefront/src/js/main.js
console.log('SwagBasicExampleTheme JS loaded');
```

In the end, by running the command `bin/build-storefront.sh` your custom JS plugin is loaded. By default, the compiled JavaScript file is saved as `<plugin root>/src/resources/app/storefront/dist/storefront/js/swag-basic-example-theme/swag-basic-example-theme.js`. It is detected by Shopware automatically and included in the Storefront. So you do not need to embed the JavaScript file yourself.

## Using the hot-proxy (live reload)

Of course, the theme compilation with `bin/console theme:compile` will get tedious if you change files a lot and want to check the changes in the browser. So there is a better way while you are developing your theme with the `hot-proxy` option, which will give you the live reload feature.

To activate the hot-proxy, run the following command in your terminal.

```bash
./bin/watch-storefront.sh
```

```bash
composer run watch:storefront
```

This command starts a NodeJS web server on port `9998`. If you open the Storefront of your Shopware installation on `localhost:9998`, this page will be automatically updated when you make changes to your theme.

## Next steps

Now that you know how to customize the styling via SCSS and add JavaScript, here is a list of things you can do.

* [Override Bootstrap variables in a theme](override-bootstrap-variables-in-a-theme)
* [Customize templates](../plugins/storefront/customize-templates)

---

---
url: /docs/v6.5/guides/plugins/plugins/storefront/add-scss-variables.md
---

# Add SCSS variables

::: info
The configuration flag `css` is available from Shopware Version 6.4.13.0
:::

## Overview

In order to add SCSS variables to your plugin, you can configure fields in your `config.xml` to be exposed as scss variables.

We recommend to use the declaration of SCSS variables via the `config.xml` but you can still use a subscriber if you need to be more flexible as described [here](./add-scss-variables-via-subscriber).

## Prerequisites

You won't learn how to create a plugin in this guide, head over to our Plugin base guide to create your first plugin:

## Setup a default value for a custom SCSS variable

Before you start adding your config fields as SCSS variables, you should provide a fallback value for your custom SCSS variable in your plugin `base.scss`:

```css
// <plugin root>/src/Resources/app/storefront/src/scss/base.scss
// The value will be overwritten when the plugin is installed and activated
$sass-plugin-header-bg-color: #ffcc00 !default;

.header-main {
    background-color: $sass-plugin-header-bg-color;
}
```

## Plugin config values as SCSS variables

Now you can declare a config field in your plugin `config.xml` to be available as scss variable.
The new tag is `<css>` and takes the name of the scss variable as its value.

```xml
<input-field>
    <name>sassPluginHeaderBgColor</name>
    <label>Header backgroundcolor</label>
    <label lang="de-DE">Kopfzeile Hintergrundfarbe</label>
    <css>sass-plugin-header-bg-color</css>
    <defaultValue>#eee</defaultValue>
</input-field>
```

This value will now be exposed as SCSS variable and will have the value set in the Administration or the default value if not set. **When this value is changed you still have to recompile the theme manually for the changes to take effect.**
Plugin configurations with declared SCSS variable in its config.xml have a notice in the Administration that changes can change the theme.

---

---
url: /docs/v6.6/guides/plugins/plugins/storefront/add-scss-variables.md
---

# Add SCSS variables

::: info
The configuration flag `css` is available from Shopware Version 6.4.13.0
:::

## Overview

In order to add SCSS variables to your plugin, you can configure fields in your `config.xml` to be exposed as scss variables.

We recommend to use the declaration of SCSS variables via the `config.xml` but you can still use a subscriber if you need to be more flexible as described [here](./add-scss-variables-via-subscriber).

## Prerequisites

You won't learn how to create a plugin in this guide, head over to our Plugin base guide to create your first plugin:

## Setup a default value for a custom SCSS variable

Before you start adding your config fields as SCSS variables, you should provide a fallback value for your custom SCSS variable in your plugin `base.scss`:

```css
// <plugin root>/src/Resources/app/storefront/src/scss/base.scss
// The value will be overwritten when the plugin is installed and activated
$sass-plugin-header-bg-color: #ffcc00 !default;

.header-main {
    background-color: $sass-plugin-header-bg-color;
}
```

## Plugin config values as SCSS variables

Now you can declare a config field in your plugin `config.xml` to be available as scss variable.
The new tag is `<css>` and takes the name of the scss variable as its value.

```xml
<input-field>
    <name>sassPluginHeaderBgColor</name>
    <label>Header backgroundcolor</label>
    <label lang="de-DE">Kopfzeile Hintergrundfarbe</label>
    <css>sass-plugin-header-bg-color</css>
    <defaultValue>#eee</defaultValue>
</input-field>
```

This value will now be exposed as SCSS variable and will have the value set in the Administration or the default value if not set. **When this value is changed you still have to recompile the theme manually for the changes to take effect.**
Plugin configurations with declared SCSS variable in its config.xml have a notice in the Administration that changes can change the theme.

---

---
url: /docs/guides/plugins/plugins/storefront/styling/add-scss-variables.md
---

# Add SCSS Variables

::: info
The configuration flag `css` is available from Shopware Version 6.4.13.0
:::

## Overview

In order to add SCSS variables to your plugin, you can configure fields in your `config.xml` to be exposed as scss variables.

We recommend using the declaration of SCSS variables via the `config.xml`. You can still use a subscriber if you need to be more flexible, as described [here](./add-scss-variables-via-subscriber.md).

## Prerequisites

You won't learn how to create a plugin in this guide, head over to our Plugin base guide to create your first plugin:

## Setup a default value for a custom SCSS variable

Before you start adding your config fields as SCSS variables, you should provide a fallback value for your custom SCSS variable in your plugin `base.scss`:

```css
// <plugin root>/src/Resources/app/storefront/src/scss/base.scss
// The value will be overwritten when the plugin is installed and activated
$sass-plugin-header-bg-color: #ffcc00 !default;

.header-main {
    background-color: $sass-plugin-header-bg-color;
}
```

## Plugin config values as SCSS variables

Now you can declare a config field in your plugin `config.xml` to be available as scss variable.
The new tag is `<css>` and takes the name of the scss variable as its value.

```xml
<input-field>
    <name>sassPluginHeaderBgColor</name>
    <label>Header backgroundcolor</label>
    <label lang="de-DE">Kopfzeile Hintergrundfarbe</label>
    <css>sass-plugin-header-bg-color</css>
    <defaultValue>#eee</defaultValue>
</input-field>
```

This value will now be exposed as SCSS variable and will have the value set in the Administration or the default value if not set. **When this value is changed you still have to recompile the theme manually for the changes to take effect.**
Plugin configurations with declared SCSS variable in its config.xml have a notice in the Administration that changes can change the theme.

---

---
url: >-
  /docs/v6.5/guides/plugins/plugins/storefront/add-scss-variables-via-subscriber.md
---

# Add SCSS Variables

## Overview

In order to add SCSS variables to your plugin, you can configure fields in your `config.xml` to be exposed as scss variables.

We recommend to use the declaration of [SCSS variables](./add-scss-variables) via the `config.xml` but you can still use a subscriber if you need to be more flexible as described below.

## Prerequisites

You won't learn how to create a plugin in this guide, head over to our Plugin base guide to create your first plugin:

You should also know how to listen to events:

## Setup a default value for a custom SCSS variable

Before you start adding your subscriber, you should provide a fallback value for your custom SCSS variable in your plugin `base.scss`:

```css
// <plugin root>/src/Resources/app/storefront/src/scss/base.scss
// The value will be overwritten by the subscriber when the plugin is installed and activated
$sass-plugin-header-bg-color: #ffcc00 !default;

.header-main {
    background-color: $sass-plugin-header-bg-color;
}
```

## Theme variables subscriber

You can add a new subscriber according to the [Listening to events](../plugin-fundamentals/listening-to-events) guide. In this example we name the subscriber `ThemeVariableSubscriber`. The subscriber listens to the `ThemeCompilerEnrichScssVariablesEvent`.

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Subscriber;

use Shopware\Storefront\Event\ThemeCompilerEnrichScssVariablesEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class ThemeVariableSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            ThemeCompilerEnrichScssVariablesEvent::class => 'onAddVariables'
        ];
    }

    public function onAddVariables(ThemeCompilerEnrichScssVariablesEvent $event): void
    {
        // Will render: $sass-plugin-header-bg-color: "#59ccff";
        $event->addVariable('sass-plugin-header-bg-color', '#59ccff');
    }
}
```

```xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Subscriber\ThemeVariableSubscriber">
            <tag name="kernel.event_subscriber"/>
        </service>
    </services>
</container>
```

The `ThemeCompilerEnrichScssVariablesEvent` provides the `addVariable()` method which takes the following parameters:

* `$name:` (string): The name of the SCSS variable. In your SCSS, the passed string will be used exactly as its stated here, so please be careful with special characters. We recommend using kebab-case here. The variable prefix `$` will be added automatically. We also recommend prefixing your variable name with your plugin's or company's name to prevent naming conflicts.
* `$value:` (string): The value which should be assigned to the SCSS variable.
* `$sanitize` (bool - optional): Optional parameter to remove special characters from the variables value. The parameter will also add quotes around the variables value. In most cases quotes are not needed e.g. for color hex values. However, there may be situations where you want to pass individual strings to your SCSS variable.

::: warning
Please note that plugins are not sales channel specific. Your SCSS variables are directly added in the SCSS compilation process and will be globally available throughout all themes and Storefront sales channels. If you want to change a variables value for each sales channel you should use plugin config fields and follow the next example.
:::

## Plugin config values as SCSS variables

Inside your `ThemeVariableSubscriber` you can also read values from the plugin configuration and assign those to a SCSS variable. This makes it also possible to have different values for each sales channel. Depending on the selected sales channel inside the plugin configuration in the Administration.

First, lets add a new plugin configuration field according to the [Plugin Configurations](../plugin-fundamentals/add-plugin-configuration):

```xml
// <plugin root>/src/Resources/config/config.xml
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/SystemConfig/Schema/config.xsd">

    <card>
        <title>Example configuration</title>
        <input-field type="colorpicker">
            <name>sassPluginHeaderBgColor</name>
            <label>Header background color</label>
        </input-field>
    </card>
</config>
```

As you can see in the example, we add an input field of the type colorpicker for our plugin. In the Administration, the component 'sw-colorpicker' will later be displayed for the selection of the value. You also can set a `defaultValue` which will be pre-selected like the following:

```xml
// <plugin root>/src/Resources/config/config.xml
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/SystemConfig/Schema/config.xsd">

    <card>
        <title>Example configuration</title>
        <input-field type="colorpicker">
            <name>sassPluginHeaderBgColor</name>
            <label>Header background color</label>
            <defaultValue>#fff</defaultValue>
        </input-field>
    </card>
</config>
```

In order to be able to read this config, you have to inject the `SystemConfigService` to your subscriber:

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Subscriber;

use Shopware\Core\System\SystemConfig\SystemConfigService;
use Shopware\Storefront\Theme\Event\ThemeCompilerEnrichScssVariablesEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class ThemeVariableSubscriber implements EventSubscriberInterface
{
    protected SystemConfigService $systemConfig;

    // add the `SystemConfigService` to your constructor
    public function __construct(SystemConfigService $systemConfig)
    {
        $this->systemConfig = $systemConfig;
    }

    public static function getSubscribedEvents(): array
    {
        return [
            ThemeCompilerEnrichScssVariablesEvent::class => 'onAddVariables'
        ];
    }

    public function onAddVariables(ThemeCompilerEnrichScssVariablesEvent $event): void
    {
        /** @var string $configExampleField */
        $configPluginHeaderBgColor = $this->systemConfig->get('SwagBasicExample.config.sassPluginHeaderBgColor', $event->getSalesChannelId());

        if ($configPluginHeaderBgColor) {
            // pass the value from `configPluginHeaderBgColor` to `addVariable`
            $event->addVariable('sass-plugin-header-bg-color', $configPluginHeaderBgColor);
        }
    }
}
```

```xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Subscriber\ThemeVariableSubscriber">
            <!-- add argument `SystemConfigService` -->
            <argument type="service" id="Shopware\Core\System\SystemConfig\SystemConfigService"/>
            <tag name="kernel.event_subscriber"/>
        </service>
    </services>
</container>
```

* The `SystemConfigService` provides a `get()` method where you can access the configuration structure in the first parameter with a dot notation syntax like `SwagBasicExample.config.fieldName`. The second parameter is the sales channel `id`. With this `id` the config fields can be accessed for each sales channel.
* You can get the sales channel id through the getter `getSalesChannelId()` of the `ThemeCompilerEnrichScssVariablesEvent`.
* Now your sass variables can have different values in each sales channel.

### All config fields as SCSS variables

Adding config fields via `$event->addVariable()` for every field individually may be a bit cumbersome in some cases. You could also loop over all config fields and call `addVariable()` for each one. However, this depends on your use case.

```php
// <plugin root>/src/Subscriber/ThemeVariableSubscriber.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Subscriber;

// ...
use Symfony\Component\Serializer\NameConverter\CamelCaseToSnakeCaseNameConverter;

class ThemeVariableSubscriber implements EventSubscriberInterface
{
    // ...

    public function onAddVariables(ThemeCompilerEnrichScssVariablesEvent $event): void
    {
        $configFields = $this->systemConfig->get('SwagBasicExample.config', $event->getSalesChannelId());

        foreach($configFields as $key => $value) {
            // convert `customVariableName` to `custom-variable-name`
            $kebabCased = str_replace('_', '-', (new CamelCaseToSnakeCaseNameConverter())->normalize($key));

            $event->addVariable($kebabCased, $value);
        }
    }
}
```

To avoid camelCase variable names when reading from the `config.xml`, we recommend using the `CamelCaseToSnakeCaseNameConverter` to format the variable before adding it.

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/storefront/add-scss-variables-via-subscriber.md
---

# Add SCSS Variables

## Overview

In order to add SCSS variables to your plugin, you can configure fields in your `config.xml` to be exposed as scss variables.

We recommend to use the declaration of [SCSS variables](./add-scss-variables) via the `config.xml` but you can still use a subscriber if you need to be more flexible as described below.

## Prerequisites

You won't learn how to create a plugin in this guide, head over to our Plugin base guide to create your first plugin:

You should also know how to listen to events:

## Setup a default value for a custom SCSS variable

Before you start adding your subscriber, you should provide a fallback value for your custom SCSS variable in your plugin `base.scss`:

```css
// <plugin root>/src/Resources/app/storefront/src/scss/base.scss
// The value will be overwritten by the subscriber when the plugin is installed and activated
$sass-plugin-header-bg-color: #ffcc00 !default;

.header-main {
    background-color: $sass-plugin-header-bg-color;
}
```

## Theme variables subscriber

You can add a new subscriber according to the [Listening to events](../plugin-fundamentals/listening-to-events) guide. In this example we name the subscriber `ThemeVariableSubscriber`. The subscriber listens to the `ThemeCompilerEnrichScssVariablesEvent`.

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Subscriber;

use Shopware\Storefront\Theme\Event\ThemeCompilerEnrichScssVariablesEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class ThemeVariableSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            ThemeCompilerEnrichScssVariablesEvent::class => 'onAddVariables'
        ];
    }

    public function onAddVariables(ThemeCompilerEnrichScssVariablesEvent $event): void
    {
        // Will render: $sass-plugin-header-bg-color: "#59ccff";
        $event->addVariable('sass-plugin-header-bg-color', '#59ccff');
    }
}
```

```xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Subscriber\ThemeVariableSubscriber">
            <tag name="kernel.event_subscriber"/>
        </service>
    </services>
</container>
```

The `ThemeCompilerEnrichScssVariablesEvent` provides the `addVariable()` method which takes the following parameters:

* `$name:` (string): The name of the SCSS variable. In your SCSS, the passed string will be used exactly as its stated here, so please be careful with special characters. We recommend using kebab-case here. The variable prefix `$` will be added automatically. We also recommend prefixing your variable name with your plugin's or company's name to prevent naming conflicts.
* `$value:` (string): The value which should be assigned to the SCSS variable.
* `$sanitize` (bool - optional): Optional parameter to remove special characters from the variables value. The parameter will also add quotes around the variables value. In most cases quotes are not needed e.g. for color hex values. However, there may be situations where you want to pass individual strings to your SCSS variable.

::: warning
Please note that plugins are not sales channel specific. Your SCSS variables are directly added in the SCSS compilation process and will be globally available throughout all themes and Storefront sales channels. If you want to change a variables value for each sales channel you should use plugin config fields and follow the next example.
:::

## Plugin config values as SCSS variables

Inside your `ThemeVariableSubscriber` you can also read values from the plugin configuration and assign those to a SCSS variable. This makes it also possible to have different values for each sales channel. Depending on the selected sales channel inside the plugin configuration in the Administration.

First, lets add a new plugin configuration field according to the [Plugin Configurations](../plugin-fundamentals/add-plugin-configuration):

```xml
// <plugin root>/src/Resources/config/config.xml
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/SystemConfig/Schema/config.xsd">

    <card>
        <title>Example configuration</title>
        <input-field type="colorpicker">
            <name>sassPluginHeaderBgColor</name>
            <label>Header background color</label>
        </input-field>
    </card>
</config>
```

As you can see in the example, we add an input field of the type colorpicker for our plugin. In the Administration, the component 'sw-colorpicker' will later be displayed for the selection of the value. You also can set a `defaultValue` which will be pre-selected like the following:

```xml
// <plugin root>/src/Resources/config/config.xml
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/SystemConfig/Schema/config.xsd">

    <card>
        <title>Example configuration</title>
        <input-field type="colorpicker">
            <name>sassPluginHeaderBgColor</name>
            <label>Header background color</label>
            <defaultValue>#fff</defaultValue>
        </input-field>
    </card>
</config>
```

In order to be able to read this config, you have to inject the `SystemConfigService` to your subscriber:

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Subscriber;

use Shopware\Core\System\SystemConfig\SystemConfigService;
use Shopware\Storefront\Event\ThemeCompilerEnrichScssVariablesEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class ThemeVariableSubscriber implements EventSubscriberInterface
{
    protected SystemConfigService $systemConfig;

    // add the `SystemConfigService` to your constructor
    public function __construct(SystemConfigService $systemConfig)
    {
        $this->systemConfig = $systemConfig;
    }

    public static function getSubscribedEvents(): array
    {
        return [
            ThemeCompilerEnrichScssVariablesEvent::class => 'onAddVariables'
        ];
    }

    public function onAddVariables(ThemeCompilerEnrichScssVariablesEvent $event): void
    {
        /** @var string $configExampleField */
        $configPluginHeaderBgColor = $this->systemConfig->get('SwagBasicExample.config.sassPluginHeaderBgColor', $event->getSalesChannelId());

        if ($configPluginHeaderBgColor) {
            // pass the value from `configPluginHeaderBgColor` to `addVariable`
            $event->addVariable('sass-plugin-header-bg-color', $configPluginHeaderBgColor);
        }
    }
}
```

```xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Subscriber\ThemeVariableSubscriber">
            <!-- add argument `SystemConfigService` -->
            <argument type="service" id="Shopware\Core\System\SystemConfig\SystemConfigService"/>
            <tag name="kernel.event_subscriber"/>
        </service>
    </services>
</container>
```

* The `SystemConfigService` provides a `get()` method where you can access the configuration structure in the first parameter with a dot notation syntax like `SwagBasicExample.config.fieldName`. The second parameter is the sales channel `id`. With this `id` the config fields can be accessed for each sales channel.
* You can get the sales channel id through the getter `getSalesChannelId()` of the `ThemeCompilerEnrichScssVariablesEvent`.
* Now your sass variables can have different values in each sales channel.

### All config fields as SCSS variables

Adding config fields via `$event->addVariable()` for every field individually may be a bit cumbersome in some cases. You could also loop over all config fields and call `addVariable()` for each one. However, this depends on your use case.

```php
// <plugin root>/src/Subscriber/ThemeVariableSubscriber.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Subscriber;

// ...
use Symfony\Component\Serializer\NameConverter\CamelCaseToSnakeCaseNameConverter;

class ThemeVariableSubscriber implements EventSubscriberInterface
{
    // ...

    public function onAddVariables(ThemeCompilerEnrichScssVariablesEvent $event): void
    {
        $configFields = $this->systemConfig->get('SwagBasicExample.config', $event->getSalesChannelId());

        foreach($configFields as $key => $value) {
            // convert `customVariableName` to `custom-variable-name`
            $kebabCased = str_replace('_', '-', (new CamelCaseToSnakeCaseNameConverter())->normalize($key));

            $event->addVariable($kebabCased, $value);
        }
    }
}
```

To avoid camelCase variable names when reading from the `config.xml`, we recommend using the `CamelCaseToSnakeCaseNameConverter` to format the variable before adding it.

---

---
url: >-
  /docs/guides/plugins/plugins/storefront/styling/add-scss-variables-via-subscriber.md
---

# Add SCSS Variables via Subscriber

## Overview

In order to add SCSS variables to your plugin, you can configure fields in your `config.xml` to be exposed as scss variables.

We recommend to use the declaration of [SCSS variables](add-scss-variables.md) via the `config.xml` but you can still use a subscriber if you need to be more flexible as described below.

## Prerequisites

You won't learn how to create a plugin in this guide, head over to our Plugin base guide to create your first plugin:

You should also know how to listen to events:

## Set up a default value for a custom SCSS variable

Before you start adding your subscriber, you should provide a fallback value for your custom SCSS variable in your plugin `base.scss`:

```css
// <plugin root>/src/Resources/app/storefront/src/scss/base.scss
// The value will be overwritten by the subscriber when the plugin is installed and activated
$sass-plugin-header-bg-color: #ffcc00 !default;

.header-main {
    background-color: $sass-plugin-header-bg-color;
}
```

## Theme variables subscriber

You can add a new subscriber according to the [Listening to events](../../framework/event/listening-to-events.md) guide. In this example we name the subscriber `ThemeVariableSubscriber`. The subscriber listens to the `ThemeCompilerEnrichScssVariablesEvent`.

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Subscriber;

use Shopware\Storefront\Theme\Event\ThemeCompilerEnrichScssVariablesEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class ThemeVariableSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            ThemeCompilerEnrichScssVariablesEvent::class => 'onAddVariables'
        ];
    }

    public function onAddVariables(ThemeCompilerEnrichScssVariablesEvent $event): void
    {
        // Will render: $sass-plugin-header-bg-color: "#59ccff";
        $event->addVariable('sass-plugin-header-bg-color', '#59ccff');
    }
}
```

```php
<?php declare(strict_types=1);

use Swag\BasicExample\Subscriber\ThemeVariableSubscriber;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(ThemeVariableSubscriber::class)
        ->tag('kernel.event_subscriber');
};
```

The `ThemeCompilerEnrichScssVariablesEvent` provides the `addVariable()` method which takes the following parameters:

* `$name:` (string): The name of the SCSS variable. In your SCSS, the passed string will be used exactly as its stated here, so please be careful with special characters. We recommend using kebab-case here. The variable prefix `$` will be added automatically. We also recommend prefixing your variable name with your plugin's or company's name to prevent naming conflicts.
* `$value:` (string): The value which should be assigned to the SCSS variable.
* `$sanitize` (bool - optional): Optional parameter to remove special characters from the variables value. The parameter will also add quotes around the variables value. In most cases quotes are not needed e.g. for color hex values. However, there may be situations where you want to pass individual strings to your SCSS variable.

::: warning
Please note that plugins are not sales channel specific. Your SCSS variables are directly added in the SCSS compilation process and will be globally available throughout all themes and Storefront sales channels. If you want to change a variables value for each sales channel you should use plugin config fields and follow the next example.
:::

## Plugin config values as SCSS variables

Inside your `ThemeVariableSubscriber` you can also read values from the plugin configuration and assign those to a SCSS variable. This makes it also possible to have different values for each sales channel. Depending on the selected sales channel inside the plugin configuration in the Administration.

First, lets add a new plugin configuration field according to the [Plugin Configurations](../../plugin-fundamentals/add-plugin-configuration.md):

```xml
// <plugin root>/src/Resources/config/config.xml
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/SystemConfig/Schema/config.xsd">

    <card>
        <title>Example configuration</title>
        <input-field type="colorpicker">
            <name>sassPluginHeaderBgColor</name>
            <label>Header background color</label>
        </input-field>
    </card>
</config>
```

As you can see in the example, we add an input field of the type colorpicker for our plugin. In the Administration, the component 'sw-colorpicker' will later be displayed for the selection of the value. You also can set a `defaultValue` which will be pre-selected like the following:

```xml
// <plugin root>/src/Resources/config/config.xml
<?xml version="1.0" encoding="UTF-8"?>
<config xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/SystemConfig/Schema/config.xsd">

    <card>
        <title>Example configuration</title>
        <input-field type="colorpicker">
            <name>sassPluginHeaderBgColor</name>
            <label>Header background color</label>
            <defaultValue>#fff</defaultValue>
        </input-field>
    </card>
</config>
```

In order to be able to read this config, you have to inject the `SystemConfigService` to your subscriber:

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Subscriber;

use Shopware\Core\System\SystemConfig\SystemConfigService;
use Shopware\Storefront\Event\ThemeCompilerEnrichScssVariablesEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class ThemeVariableSubscriber implements EventSubscriberInterface
{
    protected SystemConfigService $systemConfig;

    // add the `SystemConfigService` to your constructor
    public function __construct(SystemConfigService $systemConfig)
    {
        $this->systemConfig = $systemConfig;
    }

    public static function getSubscribedEvents(): array
    {
        return [
            ThemeCompilerEnrichScssVariablesEvent::class => 'onAddVariables'
        ];
    }

    public function onAddVariables(ThemeCompilerEnrichScssVariablesEvent $event): void
    {
        /** @var string $configExampleField */
        $configPluginHeaderBgColor = $this->systemConfig->get('SwagBasicExample.config.sassPluginHeaderBgColor', $event->getSalesChannelId());

        if ($configPluginHeaderBgColor) {
            // pass the value from `configPluginHeaderBgColor` to `addVariable`
            $event->addVariable('sass-plugin-header-bg-color', $configPluginHeaderBgColor);
        }
    }
}
```

```php
<?php declare(strict_types=1);

use Shopware\Core\System\SystemConfig\SystemConfigService;
use Swag\BasicExample\Subscriber\ThemeVariableSubscriber;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(ThemeVariableSubscriber::class)
        // add argument SystemConfigService
        ->args([service(SystemConfigService::class)])
        ->tag('kernel.event_subscriber');
};
```

* The `SystemConfigService` provides a `get()` method where you can access the configuration structure in the first parameter with a dot notation syntax like `SwagBasicExample.config.fieldName`. The second parameter is the sales channel `id`. With this `id` the config fields can be accessed for each sales channel.
* You can get the sales channel id through the getter `getSalesChannelId()` of the `ThemeCompilerEnrichScssVariablesEvent`.
* Now your sass variables can have different values in each sales channel.

### All config fields as SCSS variables

Adding config fields via `$event->addVariable()` for every field individually may be a bit cumbersome in some cases. You could also loop over all config fields and call `addVariable()` for each one. However, this depends on your use case.

```php
// <plugin root>/src/Subscriber/ThemeVariableSubscriber.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Subscriber;

// ...
use Symfony\Component\Serializer\NameConverter\CamelCaseToSnakeCaseNameConverter;

class ThemeVariableSubscriber implements EventSubscriberInterface
{
    // ...

    public function onAddVariables(ThemeCompilerEnrichScssVariablesEvent $event): void
    {
        $configFields = $this->systemConfig->get('SwagBasicExample.config', $event->getSalesChannelId());

        foreach($configFields as $key => $value) {
            // convert `customVariableName` to `custom-variable-name`
            $kebabCased = str_replace('_', '-', (new CamelCaseToSnakeCaseNameConverter())->normalize($key));

            $event->addVariable($kebabCased, $value);
        }
    }
}
```

To avoid camelCase variable names when reading from the `config.xml`, we recommend using the `CamelCaseToSnakeCaseNameConverter` to format the variable before adding it.

---

---
url: /docs/v6.5/guides/plugins/plugins/framework/store-api/add-store-api-route.md
---

# Add Store API route

## Overview

In this guide you will learn how to add a custom store API route. In this example, we will create a new route called `ExampleRoute` that searches entities of type `swag_example`. The route will be accessible under `/store-api/example`.

## Prerequisites

In order to add your own Store API route for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../../plugin-base-guide).

You also should have a look at our [Adding custom complex data](../data-handling/add-custom-complex-data) guide, since this guide is built upon it.

## Add Store API route

As you may already know from the [Adjusting a service](../../plugin-fundamentals/adjusting-service) guide, we use abstract classes to make our routes more decoratable.

::: warning
All fields that should be available through the API require the flag `ApiAware` in the definition.
:::

### Create abstract route class

First of all, we create an abstract class called `AbstractExampleRoute`. This class has to contain a method `getDecorated` and a method `load` with a `Criteria` and `SalesChannelContext` as parameter. The `load` method has to return an instance of `ExampleRouteResponse`, which we will create later on.

```php
// <plugin root>/src/Core/Content/Example/SalesChannel/AbstractExampleRoute.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\SalesChannel;

use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

abstract class AbstractExampleRoute
{
    abstract public function getDecorated(): AbstractExampleRoute;

    abstract public function load(Criteria $criteria, SalesChannelContext $context): ExampleRouteResponse;
}
```

### Create route class

Now we can create a new class `ExampleRoute` which uses our previously created `AbstractExampleRoute`.

```php
// <plugin root>/src/Core/Content/Example/SalesChannel/ExampleRoute.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\SalesChannel;

use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\Framework\Plugin\Exception\DecorationPatternException;
use Shopware\Core\Framework\Routing\Annotation\Entity;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Symfony\Component\Routing\Annotation\Route;

#[Route(defaults: ['_routeScope' => ['store-api']])]
class ExampleRoute extends AbstractExampleRoute
{
    protected EntityRepository $exampleRepository;

    public function __construct(EntityRepository $exampleRepository)
    {
        $this->exampleRepository = $exampleRepository;
    }

    public function getDecorated(): AbstractExampleRoute
    {
        throw new DecorationPatternException(self::class);
    }

    #[Route(path: '/store-api/example', name: 'store-api.example.search', methods: ['GET','POST'], defaults: ['_entity' => 'swag_example'])]
    public function load(Criteria $criteria, SalesChannelContext $context): ExampleRouteResponse
    {
        return new ExampleRouteResponse($this->exampleRepository->search($criteria, $context->getContext()));
    }
}
```

As you can see, our class is annotated with `@Route` and the defined \_routeScope `store-api`.

In our class constructor we've injected our `swag_example.repository`. The method `getDecorated()` must throw a `DecorationPatternException` because it has no decoration yet and the method `load`, which fetches the data, returns a new `ExampleRouteResponse` with the respective repository search result as argument.

The `@Entity` annotation just marks the entity that the api will return.

### Register route class

```xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Core\Content\Example\SalesChannel\ExampleRoute" >
            <argument type="service" id="swag_example.repository"/>
        </service>
    </services>
</container>
```

### Route response

After we have created our route, we need to create the mentioned `ExampleRouteResponse`. This class should extend from `Shopware\Core\System\SalesChannel\StoreApiResponse`, consequently inheriting a property `$object` of type `Shopware\Core\Framework\DataAbstractionLayer\Search\EntitySearchResult`. The `StoreApiResponse` parent constructor takes accepts one argument `$object` in order to set the value for the `$object` property (currently we provide this parameter our `ExampleRoute`). Finally, we add a method `getExamples` in which we return our entity collection that we got from the object.

```php
// <plugin root>/src/Core/Content/Example/SalesChannel/ExampleRouteResponse.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\SalesChannel;

use Shopware\Core\Framework\DataAbstractionLayer\Search\EntitySearchResult;
use Shopware\Core\System\SalesChannel\StoreApiResponse;
use Swag\BasicExample\Core\Content\Example\ExampleCollection;

/**
 * Class ExampleRouteResponse
 * @property EntitySearchResult $object
 */
class ExampleRouteResponse extends StoreApiResponse
{
    public function getExamples(): ExampleCollection
    {
        /** @var ExampleCollection $collection */
        $collection = $this->object->getEntities();

        return $collection;
    }
}
```

## Register route

The last thing we need to do now is to tell Shopware how to look for new routes in our plugin. This is done with a `routes.xml` file at `<plugin root>/src/Resources/config/` location. Have a look at the official [Symfony documentation](https://symfony.com/doc/current/routing.html) about routes and how they are registered.

```xml
// <plugin root>/src/Resources/config/routes.xml
<?xml version="1.0" encoding="UTF-8" ?>
<routes xmlns="http://symfony.com/schema/routing"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://symfony.com/schema/routing
        https://symfony.com/schema/routing/routing-1.0.xsd">

    <import resource="../../Core/**/*Route.php" type="annotation" />
</routes>
```

## Check route via Symfony debugger

To check, if your route was registered correctly, you can use the [Symfony route debugger](https://symfony.com/doc/current/routing.html#debugging-routes).

```bash
// 
$ ./bin/console debug:router store-api.example.search
```

## Add route to Swagger

To add the route to the Swagger page, a JSON file is needed in a specific [format](https://swagger.io/specification/#paths-object). It contains information about the paths, methods, parameters, and more. You must place the JSON file in `<plugin root>/src/Resources/Schema/StoreApi/` so the shopware internal OpenApi3Generator can find it (for Admin API endpoints, use `AdminApi`).

```js
// <plugin root>/src/Resources/Schema/StoreApi/example.json
{
  "openapi": "3.0.0",
  "info": [],
  "paths": {
    "/example": {
      "post": {
        "tags": [
          "Example",
          "Endpoints supporting Criteria "
        ],
        "summary": "Example entity endpoint",
        "description": "Returns a list of example entities.",
        "operationId": "example",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Criteria"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Returns a list of example entities.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Example"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    }
  }
}
```

### Check route in Swagger

To check, if your file has the correct format, you'll have to check Swagger. To do this, go to the following route: `/store-api/_info/swagger.html`.

Your generated request and response could look like this:

#### Request

```json
{
  "page": 0,
  "limit": 0,
  "term": "string",
  "filter": [
    {
      "type": "string",
      "field": "string",
      "value": "string"
    }
  ],
  "sort": [
    {
      "field": "string",
      "order": "string",
      "naturalSorting": true
    }
  ],
  "post-filter": [
    {
      "type": "string",
      "field": "string",
      "value": "string"
    }
  ],
  "associations": {},
  "aggregations": [
    {
      "name": "string",
      "type": "string",
      "field": "string"
    }
  ],
  "query": [
    {
      "score": 0,
      "query": {
        "type": "string",
        "field": "string",
        "value": "string"
      }
    }
  ],
  "grouping": [
    "string"
  ]
}
```

#### Response

```json
{
  "total": 0,
  "aggregations": {},
  "elements": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "active": true,
      "createdAt": "2021-03-24T13:18:46.503Z",
      "updatedAt": "2021-03-24T13:18:46.503Z"
    }
  ]
}
```

## Make the route available for the Storefront

If you want to access the functionality of your route also from the Storefront you need to make it available there by adding a custom [Storefront controller](../../storefront/add-custom-controller) that will wrap your just created route.

```php
// <plugin root>/src/Storefront/Controller/ExampleController.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Controller\StorefrontController;
use Swag\BasicExample\Core\Content\Example\SalesChannel\AbstractExampleRoute;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Annotation\Route;

#[Route(defaults: ['_routeScope' => ['storefront']])]
class ExampleController extends StorefrontController
{
    private AbstractExampleRoute $route;

    public function __construct(AbstractExampleRoute $route)
    {
        $this->route = $route;
    }

    #[Route(path: '/example', name: 'frontend.example.search', methods: ['GET', 'POST'], defaults: ['XmlHttpRequest' => 'true'])
    public function load(Criteria $criteria, SalesChannelContext $context): Response
    {
        return $this->route->load($criteria, $context);
    }
}
```

This looks very similar then what we did in the `ExampleRoute` itself. The main difference is that this route is registered for the `storefront` route scope.
Additionally, we also use the `defaults={"XmlHttpRequest"=true}` config option on the route, this will enable us to request that route via AJAX-calls from the Storefronts javascript.

### Register the Controller

```xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Core\Content\Example\SalesChannel\ExampleRoute" >
            <argument type="service" id="swag_example.repository"/>
        </service>
    
        <service id="Swag\BasicExample\Storefront\Controller\ExampleController" >
            <argument type="service" id="Swag\BasicExample\Core\Content\Example\SalesChannel\ExampleRoute"/>
        </service>
    </services>
</container>
```

### Register Storefront api-route

We need to tell Shopware that there is a new API-route for the `storefront` scope by extending the `routes.xml` to also include all Storefront controllers.

```xml
// <plugin root>/src/Resources/config/routes.xml
<?xml version="1.0" encoding="UTF-8" ?>
<routes xmlns="http://symfony.com/schema/routing"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://symfony.com/schema/routing
        https://symfony.com/schema/routing/routing-1.0.xsd">

    <import resource="../../Core/**/*Route.php" type="annotation" />
    <import resource="../../Storefront/**/*Controller.php" type="annotation" />
</routes>
```

### Requesting your route from the Storefront

You can request your new route from the Storefront from inside a [custom javascript plugin](../../storefront/add-custom-javascript).
We expect that you have followed that guide and know how to register your custom javascript plugin in the Storefront.

When you want to request your custom route you can use the existing `http-client` service for that.

```javascript
// <plugin root>/src/Resources/app/storefront/src/example-plugin/example-plugin.plugin.js
import Plugin from 'src/plugin-system/plugin.class';
import HttpClient from 'src/service/http-client.service';

export default class ExamplePlugin extends Plugin {
    init() {
        this._client = new HttpClient();
    }
    
    requestCustomRoute() {
        this._client.post('/example', { limit: 10, offset: 0}, (response) => {
            alert(response);
        });
    }
}
```

---

---
url: /docs/v6.6/guides/plugins/plugins/framework/store-api/add-store-api-route.md
---

# Add Store API route

## Overview

In this guide you will learn how to add a custom store API route. In this example, we will create a new route called `ExampleRoute` that searches entities of type `swag_example`. The route will be accessible under `/store-api/example`.

## Prerequisites

In order to add your own Store API route for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../../plugin-base-guide).

You also should have a look at our [Adding custom complex data](../data-handling/add-custom-complex-data) guide, since this guide is built upon it.

## Add Store API route

As you may already know from the [Adjusting a service](../../plugin-fundamentals/adjusting-service) guide, we use abstract classes to make our routes more decoratable.

::: warning
All fields that should be available through the API require the flag `ApiAware` in the definition.
:::

### Create abstract route class

First of all, we create an abstract class called `AbstractExampleRoute`. This class has to contain a method `getDecorated` and a method `load` with a `Criteria` and `SalesChannelContext` as parameter. The `load` method has to return an instance of `ExampleRouteResponse`, which we will create later on.

```php
// <plugin root>/src/Core/Content/Example/SalesChannel/AbstractExampleRoute.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\SalesChannel;

use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

abstract class AbstractExampleRoute
{
    abstract public function getDecorated(): AbstractExampleRoute;

    abstract public function load(Criteria $criteria, SalesChannelContext $context): ExampleRouteResponse;
}
```

### Create route class

Now we can create a new class `ExampleRoute` which uses our previously created `AbstractExampleRoute`.

```php
// <plugin root>/src/Core/Content/Example/SalesChannel/ExampleRoute.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\SalesChannel;

use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\Framework\Plugin\Exception\DecorationPatternException;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Symfony\Component\Routing\Attribute\Route;

#[Route(defaults: ['_routeScope' => ['store-api']])]
class ExampleRoute extends AbstractExampleRoute
{
    protected EntityRepository $exampleRepository;

    public function __construct(EntityRepository $exampleRepository)
    {
        $this->exampleRepository = $exampleRepository;
    }

    public function getDecorated(): AbstractExampleRoute
    {
        throw new DecorationPatternException(self::class);
    }

    #[Route(path: '/store-api/example', name: 'store-api.example.search', methods: ['GET','POST'], defaults: ['_entity' => 'swag_example'])]
    public function load(Criteria $criteria, SalesChannelContext $context): ExampleRouteResponse
    {
        return new ExampleRouteResponse($this->exampleRepository->search($criteria, $context->getContext()));
    }
}
```

As you can see, our class has the attribute `Route` and the defined \_routeScope `store-api`.

In our class constructor we've injected our `swag_example.repository`. The method `getDecorated()` must throw a `DecorationPatternException` because it has no decoration yet and the method `load`, which fetches the data, returns a new `ExampleRouteResponse` with the respective repository search result as argument.

The `_entity` in the defaults of the `Route` attribute just marks the entity that the api will return.

### Register route class

```xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Core\Content\Example\SalesChannel\ExampleRoute" >
            <argument type="service" id="swag_example.repository"/>
        </service>
    </services>
</container>
```

### Route response

After we have created our route, we need to create the mentioned `ExampleRouteResponse`. This class should extend from `Shopware\Core\System\SalesChannel\StoreApiResponse`, consequently inheriting a property `$object` of type `Shopware\Core\Framework\DataAbstractionLayer\Search\EntitySearchResult`. The `StoreApiResponse` parent constructor takes accepts one argument `$object` in order to set the value for the `$object` property (currently we provide this parameter our `ExampleRoute`). Finally, we add a method `getExamples` in which we return our entity collection that we got from the object.

```php
// <plugin root>/src/Core/Content/Example/SalesChannel/ExampleRouteResponse.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\SalesChannel;

use Shopware\Core\Framework\DataAbstractionLayer\Search\EntitySearchResult;
use Shopware\Core\System\SalesChannel\StoreApiResponse;
use Swag\BasicExample\Core\Content\Example\ExampleCollection;

/**
 * Class ExampleRouteResponse
 * @property EntitySearchResult<ExampleCollection> $object
 */
class ExampleRouteResponse extends StoreApiResponse
{
    public function getExamples(): ExampleCollection
    {
        return $this->object->getEntities();
    }
}
```

## Register route

The last thing we need to do now is to tell Shopware how to look for new routes in our plugin. This is done with a `routes.xml` file at `<plugin root>/src/Resources/config/` location. Have a look at the official [Symfony documentation](https://symfony.com/doc/current/routing.html) about routes and how they are registered.

```xml
// <plugin root>/src/Resources/config/routes.xml
<?xml version="1.0" encoding="UTF-8" ?>
<routes xmlns="http://symfony.com/schema/routing"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://symfony.com/schema/routing
        https://symfony.com/schema/routing/routing-1.0.xsd">

    <import resource="../../Core/**/*Route.php" type="attribute" />
</routes>
```

## Check route via Symfony debugger

To check, if your route was registered correctly, you can use the [Symfony route debugger](https://symfony.com/doc/current/routing.html#debugging-routes).

```bash
// 
$ ./bin/console debug:router store-api.example.search
```

## Add route to Swagger

To add the route to the Swagger page, a JSON file is needed in a specific [format](https://swagger.io/specification/#paths-object). It contains information about the paths, methods, parameters, and more. You must place the JSON file in `<plugin root>/src/Resources/Schema/StoreApi/` so the shopware internal OpenApi3Generator can find it (for Admin API endpoints, use `AdminApi`).

```javascript
// <plugin root>/src/Resources/Schema/StoreApi/example.json
{
  "openapi": "3.0.0",
  "info": [],
  "paths": {
    "/example": {
      "post": {
        "tags": [
          "Example",
          "Endpoints supporting Criteria "
        ],
        "summary": "Example entity endpoint",
        "description": "Returns a list of example entities.",
        "operationId": "example",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Criteria"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Returns a list of example entities.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Example"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    }
  }
}
```

### Check route in Swagger

To check, if your file has the correct format, you'll have to check Swagger. To do this, go to the following route: `/store-api/_info/swagger.html`.

Your generated request and response could look like this:

#### Request

```json
{
  "page": 0,
  "limit": 0,
  "term": "string",
  "filter": [
    {
      "type": "string",
      "field": "string",
      "value": "string"
    }
  ],
  "sort": [
    {
      "field": "string",
      "order": "string",
      "naturalSorting": true
    }
  ],
  "post-filter": [
    {
      "type": "string",
      "field": "string",
      "value": "string"
    }
  ],
  "associations": {},
  "aggregations": [
    {
      "name": "string",
      "type": "string",
      "field": "string"
    }
  ],
  "query": [
    {
      "score": 0,
      "query": {
        "type": "string",
        "field": "string",
        "value": "string"
      }
    }
  ],
  "grouping": [
    "string"
  ]
}
```

#### Response

```json
{
  "total": 0,
  "aggregations": {},
  "elements": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "active": true,
      "createdAt": "2021-03-24T13:18:46.503Z",
      "updatedAt": "2021-03-24T13:18:46.503Z"
    }
  ]
}
```

## Make the route available for the Storefront

If you want to access the functionality of your route also from the Storefront you need to make it available there by adding a custom [Storefront controller](../../storefront/add-custom-controller) that will wrap your just created route.

```php
// <plugin root>/src/Storefront/Controller/ExampleController.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Controller\StorefrontController;
use Swag\BasicExample\Core\Content\Example\SalesChannel\AbstractExampleRoute;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

#[Route(defaults: ['_routeScope' => ['storefront']])]
class ExampleController extends StorefrontController
{
    private AbstractExampleRoute $route;

    public function __construct(AbstractExampleRoute $route)
    {
        $this->route = $route;
    }

    #[Route(path: '/example', name: 'frontend.example.search', methods: ['GET', 'POST'], defaults: ['XmlHttpRequest' => 'true', '_entity' => 'swag_example'])]
    public function load(Criteria $criteria, SalesChannelContext $context): Response
    {
        return $this->route->load($criteria, $context);
    }
}
```

This looks very similar then what we did in the `ExampleRoute` itself. The main difference is that this route is registered for the `storefront` route scope.
Additionally, we also use the `'XmlHttpRequest' => true` config option on the route, this will enable us to request that route via AJAX-calls from the Storefronts javascript.

### Register the Controller

```xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Core\Content\Example\SalesChannel\ExampleRoute" >
            <argument type="service" id="swag_example.repository"/>
        </service>
    
        <service id="Swag\BasicExample\Storefront\Controller\ExampleController" >
            <argument type="service" id="Swag\BasicExample\Core\Content\Example\SalesChannel\ExampleRoute"/>
            <call method="setContainer">
                <argument type="service" id="service_container"/>
            </call>
        </service>
    </services>
</container>
```

### Register Storefront api-route

We need to tell Shopware that there is a new API-route for the `storefront` scope by extending the `routes.xml` to also include all Storefront controllers.

```xml
// <plugin root>/src/Resources/config/routes.xml
<?xml version="1.0" encoding="UTF-8" ?>
<routes xmlns="http://symfony.com/schema/routing"
        xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
        xsi:schemaLocation="http://symfony.com/schema/routing
        https://symfony.com/schema/routing/routing-1.0.xsd">

    <import resource="../../Core/**/*Route.php" type="attribute" />
    <import resource="../../Storefront/**/*Controller.php" type="attribute" />
</routes>
```

### Requesting your route from the Storefront

You can request your new route from the Storefront from inside a [custom javascript plugin](../../storefront/add-custom-javascript).
We expect that you have followed that guide and know how to register your custom javascript plugin in the Storefront.

When you want to request your custom route you can use the existing `http-client` service for that.

```javascript
// <plugin root>/src/Resources/app/storefront/src/example-plugin/example-plugin.plugin.js
const { PluginBaseClass } = window;

export default class ExamplePlugin extends PluginBaseClass {
    async requestCustomRoute() {
        const response = await fetch('/example', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
            },
            body: JSON.stringify({
                limit: 10,
                offset: 0,
            }),
        });
        
        if (!response.ok) {
            throw new Error('Request failed');
        }

        const data = await response.json();

        console.log(data);
    }
}
```

---

---
url: /docs/guides/plugins/plugins/framework/store-api/add-store-api-route.md
---

# Add Store API Route

## Overview

In this guide you will learn how to add a custom store API route. In this example, we will create a new route called `ExampleRoute` that searches entities of type `swag_example`. The route will be accessible under `/store-api/example`.

## Prerequisites

In order to add your own Store API route for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../../plugin-base-guide).

You also should have a look at our [Adding custom complex data](../data-handling/add-custom-complex-data) guide, since this guide is built upon it.

## Add Store API route

As you may already know from the [Adjusting a service](../../../plugins/services/adjusting-service.md) guide, we use abstract classes to make our routes more decoratable.

::: warning
All fields that should be available through the API require the flag `ApiAware` in the definition.
:::

### Create abstract route class

First of all, we create an abstract class called `AbstractExampleRoute`. This class has to contain a method `getDecorated` and a method `load` with a `Criteria` and `SalesChannelContext` as parameter. The `load` method has to return an instance of `ExampleRouteResponse`, which we will create later on.

```php
// <plugin root>/src/Core/Content/Example/SalesChannel/AbstractExampleRoute.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\SalesChannel;

use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

abstract class AbstractExampleRoute
{
    abstract public function getDecorated(): AbstractExampleRoute;

    abstract public function load(Criteria $criteria, SalesChannelContext $context): ExampleRouteResponse;
}
```

### Create route class

Now we can create a new class `ExampleRoute` which uses our previously created `AbstractExampleRoute`.

```php
// <plugin root>/src/Core/Content/Example/SalesChannel/ExampleRoute.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\SalesChannel;

use Shopware\Core\Framework\Routing\StoreApiRouteScope;
use Shopware\Core\PlatformRequest;
use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\Framework\Plugin\Exception\DecorationPatternException;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Symfony\Component\Routing\Attribute\Route;

#[Route(defaults: [PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [StoreApiRouteScope::ID]])]
class ExampleRoute extends AbstractExampleRoute
{
    protected EntityRepository $exampleRepository;

    public function __construct(EntityRepository $exampleRepository)
    {
        $this->exampleRepository = $exampleRepository;
    }

    public function getDecorated(): AbstractExampleRoute
    {
        throw new DecorationPatternException(self::class);
    }

    #[Route(path: '/store-api/example', name: 'store-api.example.search', methods: ['GET','POST'], defaults: ['_entity' => 'swag_example'])]
    public function load(Criteria $criteria, SalesChannelContext $context): ExampleRouteResponse
    {
        return new ExampleRouteResponse($this->exampleRepository->search($criteria, $context->getContext()));
    }
}
```

As you can see, our class has the attribute `Route` and the defined \_routeScope `store-api`.

In our class constructor we've injected our `swag_example.repository`. The method `getDecorated()` must throw a `DecorationPatternException` because it has no decoration yet and the method `load`, which fetches the data, returns a new `ExampleRouteResponse` with the respective repository search result as argument.

The `_entity` in the defaults of the `Route` attribute just marks the entity that the api will return.

### Register route class

```php
<?php declare(strict_types=1);

use Swag\BasicExample\Core\Content\Example\SalesChannel\ExampleRoute;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(ExampleRoute::class)
        ->args([service('swag_example.repository')]);
};
```

### Route response

After we have created our route, we need to create the mentioned `ExampleRouteResponse`. This class should extend from `Shopware\Core\System\SalesChannel\StoreApiResponse`, consequently inheriting a property `$object` of type `Shopware\Core\Framework\DataAbstractionLayer\Search\EntitySearchResult`. The `StoreApiResponse` parent constructor takes accepts one argument `$object` in order to set the value for the `$object` property (currently we provide this parameter our `ExampleRoute`). Finally, we add a method `getExamples` in which we return our entity collection that we got from the object.

```php
// <plugin root>/src/Core/Content/Example/SalesChannel/ExampleRouteResponse.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\SalesChannel;

use Shopware\Core\Framework\DataAbstractionLayer\Search\EntitySearchResult;
use Shopware\Core\System\SalesChannel\StoreApiResponse;
use Swag\BasicExample\Core\Content\Example\ExampleCollection;

/**
 * Class ExampleRouteResponse
 * @property EntitySearchResult<ExampleCollection> $object
 */
class ExampleRouteResponse extends StoreApiResponse
{
    public function getExamples(): ExampleCollection
    {
        return $this->object->getEntities();
    }
}
```

## Register route

The last thing we need to do now is to tell Shopware how to look for new routes in our plugin. This is done with a `routes.php` file at `<plugin root>/src/Resources/config/` location. Take a look at the official [Symfony documentation](https://symfony.com/doc/current/routing.html) about routes and how they are registered.

```php
// <plugin root>/src/Resources/config/routes.php
<?php declare(strict_types=1);

use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return static function (RoutingConfigurator $routes): void {
    $routes->import('../../Core/**/*Route.php', 'attribute');
};
```

## Check route via Symfony debugger

To check if your route was registered correctly, you can use the [Symfony route debugger](https://symfony.com/doc/current/routing.html#debugging-routes).

```bash
//
$ ./bin/console debug:router store-api.example.search
```

## Add a route to the OpenAPI schema

To add the route to the Stoplight page, a JSON file is needed in a specific [format](https://swagger.io/specification/#paths-object). It contains information about the paths, methods, parameters, and more. You must place the JSON file in `<plugin root>/src/Resources/Schema/StoreApi/` so the shopware internal OpenApi3Generator can find it (for Admin API endpoints, use `AdminApi`).

```javascript
// <plugin root>/src/Resources/Schema/StoreApi/example.json
{
  "openapi": "3.0.0",
  "info": [],
  "paths": {
    "/example": {
      "post": {
        "tags": [
          "Example",
          "Endpoints supporting Criteria "
        ],
        "summary": "Example entity endpoint",
        "description": "Returns a list of example entities.",
        "operationId": "example",
        "requestBody": {
          "required": false,
          "content": {
            "application/json": {
              "schema": {
                "allOf": [
                  {
                    "$ref": "#/components/schemas/Criteria"
                  }
                ]
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "Returns a list of example entities.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Example"
                }
              }
            }
          }
        },
        "security": [
          {
            "ApiKey": []
          }
        ]
      }
    }
  }
}
```

### Check route in Stoplight

To check if your file has the correct format, you'll have to check Stoplight. To do this, go to the following route: `/store-api/_info/stoplightio.html`.

Your generated request and response could look like this:

#### Request

```json
{
  "page": 0,
  "limit": 0,
  "term": "string",
  "filter": [
    {
      "type": "string",
      "field": "string",
      "value": "string"
    }
  ],
  "sort": [
    {
      "field": "string",
      "order": "string",
      "naturalSorting": true
    }
  ],
  "post-filter": [
    {
      "type": "string",
      "field": "string",
      "value": "string"
    }
  ],
  "associations": {},
  "aggregations": [
    {
      "name": "string",
      "type": "string",
      "field": "string"
    }
  ],
  "query": [
    {
      "score": 0,
      "query": {
        "type": "string",
        "field": "string",
        "value": "string"
      }
    }
  ],
  "grouping": [
    "string"
  ]
}
```

#### Response

```json
{
  "total": 0,
  "aggregations": {},
  "elements": [
    {
      "id": "string",
      "name": "string",
      "description": "string",
      "active": true,
      "createdAt": "2021-03-24T13:18:46.503Z",
      "updatedAt": "2021-03-24T13:18:46.503Z"
    }
  ]
}
```

## Make the route available for the Storefront

If you want to access the functionality of your route also from the Storefront you need to make it available there by adding a custom [Storefront controller](../../storefront/controllers/add-custom-controller.md) that will wrap your just created route.

```php
// <plugin root>/src/Storefront/Controller/ExampleController.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Storefront\Controller;

use Shopware\Core\PlatformRequest;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Shopware\Storefront\Controller\StorefrontController;
use Shopware\Storefront\Framework\Routing\StorefrontRouteScope;
use Swag\BasicExample\Core\Content\Example\SalesChannel\AbstractExampleRoute;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

#[Route(defaults: [PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [StorefrontRouteScope::ID]])]
class ExampleController extends StorefrontController
{
    private AbstractExampleRoute $route;

    public function __construct(AbstractExampleRoute $route)
    {
        $this->route = $route;
    }

    #[Route(path: '/example', name: 'frontend.example.search', methods: ['GET', 'POST'], defaults: ['XmlHttpRequest' => 'true', '_entity' => 'swag_example'])]
    public function load(Criteria $criteria, SalesChannelContext $context): Response
    {
        return $this->route->load($criteria, $context);
    }
}
```

This looks very similar then what we did in the `ExampleRoute` itself. The main difference is that this route is registered for the `storefront` route scope.
Additionally, we also use the `'XmlHttpRequest' => true` config option on the route, this will enable us to request that route via AJAX-calls from the Storefronts javascript.

### Register the Controller

```php
<?php declare(strict_types=1);

use Swag\BasicExample\Core\Content\Example\SalesChannel\ExampleRoute;
use Swag\BasicExample\Storefront\Controller\ExampleController;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(ExampleRoute::class)
        ->args([service('swag_example.repository')]);

    $services->set(ExampleController::class)
        ->args([service(ExampleRoute::class)])
        ->call('setContainer', [service('service_container')]);
};
```

### Register Storefront api-route

We need to tell Shopware that there is a new API-route for the `storefront` scope by extending the `routes.php` to also include all Storefront controllers.

```php
// <plugin root>/src/Resources/config/routes.php
<?php declare(strict_types=1);

use Symfony\Component\Routing\Loader\Configurator\RoutingConfigurator;

return static function (RoutingConfigurator $routes): void {
    $routes->import('../../Core/**/*Route.php', 'attribute');
    $routes->import('../../Storefront/**/*Controller.php', 'attribute');
};
```

### Requesting your route from the Storefront

You can request your new route from the Storefront from inside a [custom JavaScript plugin](../../storefront/javascript/add-custom-javascript.md).
We expect that you have followed that guide and know how to register your custom JavaScript plugin in the Storefront.

When you want to request your custom route you can use the existing `http-client` service for that.

```javascript
// <plugin root>/src/Resources/app/storefront/src/example-plugin/example-plugin.plugin.js
const { PluginBaseClass } = window;

export default class ExamplePlugin extends PluginBaseClass {
    async requestCustomRoute() {
        const response = await fetch('/example', {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
            },
            body: JSON.stringify({
                limit: 10,
                offset: 0,
            }),
        });

        if (!response.ok) {
            throw new Error('Request failed');
        }

        const data = await response.json();

        console.log(data);
    }
}
```

---

---
url: /docs/v6.5/guides/plugins/plugins/administration/add-new-tab.md
---

# Add tab to existing module

## Overview

You want to create a new tab in the Administration? This guide gets you covered on this subject. A realistic example would be adding a new association for an entity, which you want to configure on a separate tab on the entity detail page.

## Prerequisites

This guide requires you to already have a basic plugin running. If you don't know how to do this in the first place, have a look at our plugin base guide:

In the course of this guide, you need to create a custom route. If you want to learn on how to create a custom component, please refer to the guide on it:

Also, we will use a small, custom component to fill our custom tab. In order to get used to that, it might come in handy to read the corresponding guide first:

::: info

### Please remember

The main entry point to customize the Administration via plugin is the `main.js` file. It has to be placed into a `<plugin root>/src/Resources/app/administration/src` directory in order to be found by Shopware 6. So please use the file accordingly and refer to the [plugin base guide](../plugin-base-guide) for more details.
:::

## Creating a custom tab

### Find the block to extend

For this guide, we'll think about the following example: The product detail page is extended by a new tab, which then only contains a 'Hello world!'. In order to refer to this example, let's have a look at the twig code of the product detail page found here:

Let's imagine your first goal is to create a new tab on the product detail page. Having a look at the template, you might find the block `sw_product_detail_content_tabs`, which seems to contain all available tabs. It starts by creating a new `<sw-tabs>` element to contain all the tabs available. Here you can see excerpt of this block:

```twig
// platform/src/Administration/Resources/app/administration/src/module/sw-product/page/sw-product-detail/sw-product-detail.html.twig
{% block sw_product_detail_content_tabs %}
    <sw-tabs class="sw-product-detail-page__tabs" v-if="productId">
        {% block sw_product_detail_content_tabs_general %}
            <sw-tabs-item
                class="sw-product-detail__tab-general"
                :route="{ name: 'sw.product.detail.base', params: { id: $route.params.id } }"
                :hasError="swProductDetailBaseError"
                :title="$tc('sw-product.detail.tabGeneral')">
                {{ $tc('sw-product.detail.tabGeneral') }}
            </sw-tabs-item>
        {% endblock %}

        ...

        {% block sw_product_detail_content_tabs_reviews %}
            <sw-tabs-item
                class="sw-product-detail__tab-reviews"
                :route="{ name: 'sw.product.detail.reviews', params: { id: $route.params.id } }"
                :title="$tc('sw-product.detail.tabReviews')">
                {{ $tc('sw-product.detail.tabReviews') }}
            </sw-tabs-item>
        {% endblock %}
    </sw-tabs>
{% endblock %}
```

Unfortunately, you cannot use the block mentioned above, because then your new tab wouldn't be inside the `<sw-tabs>` element. Instead, you can choose the last available block inside the element, which is `sw_product_detail_content_tabs_reviews` at this moment.

### Create custom tab

Knowing the block you have to override in your plugin, you can now start doing exactly this: Add your custom tab by overriding this block called `sw_product_detail_content_tabs_reviews`.

::: danger
However, please keep in mind that "overriding" doesn't mean we want to replace the block completely with our new one. We want to add our tab, thus only extending the template. This will have some implications on our implementation.
:::

First, please re-create the directory structure from the core code in your plugin. In this case, you'll have to create a directory structure like the following: `<plugin root>/src/Resources/app/administration/src/page/sw-product-detail`

In there you create a new file `index.js`, which then contains the following code:

```javascript
// <plugin root>/src/Resources/app/administration/src/page/sw-product-detail/index.js
import template from './sw-product-detail.html.twig';

// Override your template here, using the actual template from the core
Shopware.Component.override('sw-product-detail', {
    template
});
```

All this file is doing is to basically override the `sw-product-detail` component with a new template. The new template does not exist yet though, so create a new file `sw-product-detail.html.twig` in the same directory as your `index.js` file. It then has to use the block we figured out earlier and override it by adding a new tab element:

```twig
// <plugin root>/src/Resources/app/administration/src/page/sw-product-detail/sw-product-detail.html.twig
{% block sw_product_detail_content_tabs_reviews %}

    {# This parent is very important as you don't want to override the review tab completely #}
    {% parent %}

{% endblock %}
```

::: warning
The block gets overridden and immediately the parent block is called, since you do not want to replace the 'Review' tab, you want to add a new tab instead.
:::

After that, we'll create the actual `sw-tabs-item` element, which, as the name suggests, represents a new tab item. We want this tab to have a custom route, so we're also adding this route directly. Don't worry, we'll explain this custom route in a bit. The product detail page's route contain the product's ID, which you also want to have in your custom tab: So make sure to also pass the ID in, like shown in the example above.

```twig
// <plugin root>/src/Resources/app/administration/src/page/sw-product-detail/sw-product-detail.html.twig
{% block sw_product_detail_content_tabs_reviews %}

    {% parent %}

    <!-- We'll define a custom route here, an explanation will follow later -->
    <sw-tabs-item :route="{ name: 'sw.product.detail.custom', params: { id: $route.params.id } }" title="Custom">
        Custom
    </sw-tabs-item>
{% endblock %}
```

The [route](add-custom-route) being used here has the name `sw.product.detail.custom`, this will become important again later on.

### Loading the new tab

You've now created a new tab, but your new template is not yet loaded. Remember, that the main entry point for custom javascript for the Administration is the your plugin's `main.js` file. And that's also the file you need to adjust now, so it loads your `sw-product-detail` override.

This is an example of what your `main.js` should look like in order to load your override:

```javascript
import './page/sw-product-detail';
```

::: info
Don't forget to rebuild the Administration after applying changes to your `main.js`.

```bash
./bin/build-administration.sh
```

```bash
composer run build:js:admin
```

## Registering the tab's new route

Your new tab should now already show up on the product detail page, but clicking it should always result in an error. It's basically pointing to a new route, which you never defined yet.

Next step would be the following: Create a new route and map it to your own component. This is done by registering a new dummy module, which then overrides the method `routeMiddleware` of a module. It gets called for each and every route that is called in the Administration. Once the `sw.product.detail` route is called, you want to add your new child route to it.

You can add those changes to your `main.js` file, which could then look like this:

```javascript
// <plugin root>/src/Resources/app/administration/src/main.js
import './page/sw-product-detail';
import './view/sw-product-detail-custom';

// Here you create your new route, refer to the mentioned guide for more information
Shopware.Module.register('sw-new-tab-custom', {
    routeMiddleware(next, currentRoute) {
        const customRouteName = 'sw.product.detail.custom';
    
        if (
            currentRoute.name === 'sw.product.detail' 
            && currentRoute.children.every((currentRoute) => currentRoute.name !== customRouteName)
        ) {
            currentRoute.children.push({
                name: customRouteName,
                path: '/sw/product/detail/:id/custom',
                component: 'sw-product-detail-custom',
                meta: {
                    parentPath: 'sw.product.index'
                }
            });
        }
        next(currentRoute);
    }
});
```

As already mentioned, you need to create a dummy module in order to override the `routeMiddleware` method. In there, you're listening for the current route, that got called. If the current route matches `sw.product.detail`, you want to add your new child route to it, and that's what's done here.

::: warning
Your child route defines the routes name, so make sure to use the name you're already defined earlier!
:::

The path should be identical to the default ones, which look like this: `/sw/product/detail/:id/base` Just replace the `base` here with `custom` or anything you like.

It then points to a component, which represents the routes actual content - so you'll have to create [a new component](add-custom-component) in the next step. Note the new import that's already part of this example: `view/sw-product-detail-custom`

## Creating your new component

As shown in the previous example, your custom component is expected to be in a directory `view/sw-product-detail-custom`, so create this directory in your plugin now. The directory structure inside of your Administration directory should then look like this:

```text
administration
├── src
│   └──page
│       └── sw-product-detail
│           ├── index.js
│           └── sw-product-detail.html.twig
|   └──view
│       └── sw-product-detail-custom
│           ├── index.js        
└── main.js
```

Since a component always gets initiated by a file called `index.js`, create such a new file in the `sw-product-detail-custom` directory:

```javascript
// <plugin root>/src/Resources/app/administration/src/view/sw-product-detail-custom/index.js
import template from './sw-product-detail-custom.html.twig';

Shopware.Component.register('sw-product-detail-custom', {
    template,

    metaInfo() {
        return {
            title: 'Custom'
        };
    },
});
```

This file mainly registers a new component with a custom title and a custom template. Once more, the referenced template is still missing, so make sure to create the file `sw-product-detail-custom.html.twig` next to your `index.js` file.

Here's what this new template could look like:

```html
// <plugin root>/src/Resources/app/administration/src/view/sw-product-detail-custom/sw-product-detail-custom.html.twig
<sw-card title="Custom">
    Hello world!
</sw-card>
```

It simply creates a new card with a title, which only contains a 'Hello world!' string. And that's it - your tab should now be fully functional.

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/administration/routing-navigation/add-new-tab.md
---

# Add tab to existing module

## Overview

You want to create a new tab in the Administration? This guide gets you covered on this subject. A realistic example would be adding a new association for an entity, which you want to configure on a separate tab on the entity detail page.

## Prerequisites

This guide requires you to already have a basic plugin running. If you don't know how to do this in the first place, have a look at our plugin base guide:

In the course of this guide, you need to create a custom route. If you want to learn on how to create a custom component, please refer to the guide on it:

Also, we will use a small, custom component to fill our custom tab. In order to get used to that, it might come in handy to read the corresponding guide first:

::: info

### Please remember

The main entry point to customize the Administration via plugin is the `main.js` file. It has to be placed into a `<plugin root>/src/Resources/app/administration/src` directory in order to be found by Shopware 6. So please use the file accordingly and refer to the [plugin base guide](../../plugin-base-guide.md) for more details.
:::

## Creating a custom tab

### Find the block to extend

For this guide, we'll think about the following example: The product detail page is extended by a new tab, which then only contains a 'Hello world!'. In order to refer to this example, let's have a look at the twig code of the product detail page found here:

Let's imagine your first goal is to create a new tab on the product detail page. Having a look at the template, you might find the block `sw_product_detail_content_tabs`, which seems to contain all available tabs. It starts by creating a new `<sw-tabs>` element to contain all the tabs available. Here you can see excerpt of this block:

```twig
// platform/src/Administration/Resources/app/administration/src/module/sw-product/page/sw-product-detail/sw-product-detail.html.twig
{% block sw_product_detail_content_tabs %}
    <sw-tabs class="sw-product-detail-page__tabs" v-if="productId">
        {% block sw_product_detail_content_tabs_general %}
            <sw-tabs-item
                class="sw-product-detail__tab-general"
                :route="{ name: 'sw.product.detail.base', params: { id: $route.params.id } }"
                :hasError="swProductDetailBaseError"
                :title="$tc('sw-product.detail.tabGeneral')">
                {{ $tc('sw-product.detail.tabGeneral') }}
            </sw-tabs-item>
        {% endblock %}

        ...

        {% block sw_product_detail_content_tabs_reviews %}
            <sw-tabs-item
                class="sw-product-detail__tab-reviews"
                :route="{ name: 'sw.product.detail.reviews', params: { id: $route.params.id } }"
                :title="$tc('sw-product.detail.tabReviews')">
                {{ $tc('sw-product.detail.tabReviews') }}
            </sw-tabs-item>
        {% endblock %}
    </sw-tabs>
{% endblock %}
```

Unfortunately, you cannot use the block mentioned above, because then your new tab wouldn't be inside the `<sw-tabs>` element. Instead, you can choose the last available block inside the element, which is `sw_product_detail_content_tabs_reviews` at this moment.

### Create custom tab

Knowing the block you have to override in your plugin, you can now start doing exactly this: Add your custom tab by overriding this block called `sw_product_detail_content_tabs_reviews`.

::: danger
However, please keep in mind that "overriding" doesn't mean we want to replace the block completely with our new one. We want to add our tab, thus only extending the template. This will have some implications on our implementation.
:::

First, please re-create the directory structure from the core code in your plugin. In this case, you'll have to create a directory structure like the following: `<plugin root>/src/Resources/app/administration/src/page/sw-product-detail`

In there you create a new file `index.js`, which then contains the following code:

```javascript
// <plugin root>/src/Resources/app/administration/src/page/sw-product-detail/index.js
import template from './sw-product-detail.html.twig';

// Override your template here, using the actual template from the core
Shopware.Component.override('sw-product-detail', {
    template
});
```

All this file is doing is to basically override the `sw-product-detail` component with a new template. The new template does not exist yet though, so create a new file `sw-product-detail.html.twig` in the same directory as your `index.js` file. It then has to use the block we figured out earlier and override it by adding a new tab element:

```twig
// <plugin root>/src/Resources/app/administration/src/page/sw-product-detail/sw-product-detail.html.twig
{% block sw_product_detail_content_tabs_reviews %}

    {# This parent is very important as you don't want to override the review tab completely #}
    {% parent %}

{% endblock %}
```

::: warning
The block gets overridden and immediately the parent block is called, since you do not want to replace the 'Review' tab, you want to add a new tab instead.
:::

After that, we'll create the actual `sw-tabs-item` element, which, as the name suggests, represents a new tab item. We want this tab to have a custom route, so we're also adding this route directly. Don't worry, we'll explain this custom route in a bit. The product detail page's route contain the product's ID, which you also want to have in your custom tab: So make sure to also pass the ID in, like shown in the example above.

```twig
// <plugin root>/src/Resources/app/administration/src/page/sw-product-detail/sw-product-detail.html.twig
{% block sw_product_detail_content_tabs_reviews %}

    {% parent %}

    <!-- We'll define a custom route here, an explanation will follow later -->
    <sw-tabs-item :route="{ name: 'sw.product.detail.custom', params: { id: $route.params.id } }" title="Custom">
        Custom
    </sw-tabs-item>
{% endblock %}
```

The [route](../routing-navigation/add-custom-route.md) being used here has the name `sw.product.detail.custom`, this will become important again later on.

### Loading the new tab

You've now created a new tab, but your new template is not yet loaded. Remember, that the main entry point for custom javascript for the Administration is the your plugin's `main.js` file. And that's also the file you need to adjust now, so it loads your `sw-product-detail` override.

This is an example of what your `main.js` should look like in order to load your override:

```javascript
import './page/sw-product-detail';
```

::: info
Don't forget to rebuild the Administration after applying changes to your `main.js`.

```bash
./bin/build-administration.sh
```

```bash
composer run build:js:admin
```

## Registering the tab's new route

Your new tab should now already show up on the product detail page, but clicking it should always result in an error. It's basically pointing to a new route, which you never defined yet.

Next step would be the following: Create a new route and map it to your own component. This is done by registering a new dummy module, which then overrides the method `routeMiddleware` of a module. It gets called for each and every route that is called in the Administration. Once the `sw.product.detail` route is called, you want to add your new child route to it.

You can add those changes to your `main.js` file, which could then look like this:

```javascript
// <plugin root>/src/Resources/app/administration/src/main.js
import './page/sw-product-detail';
import './view/sw-product-detail-custom';

// Here you create your new route, refer to the mentioned guide for more information
Shopware.Module.register('sw-new-tab-custom', {
    routeMiddleware(next, currentRoute) {
        const customRouteName = 'sw.product.detail.custom';
    
        if (
            currentRoute.name === 'sw.product.detail' 
            && currentRoute.children.every((currentRoute) => currentRoute.name !== customRouteName)
        ) {
            currentRoute.children.push({
                name: customRouteName,
                path: '/sw/product/detail/:id/custom',
                component: 'sw-product-detail-custom',
                meta: {
                    parentPath: 'sw.product.index'
                }
            });
        }
        next(currentRoute);
    }
});
```

As already mentioned, you need to create a dummy module in order to override the `routeMiddleware` method. In there, you're listening for the current route, that got called. If the current route matches `sw.product.detail`, you want to add your new child route to it, and that's what's done here.

::: warning
Your child route defines the routes name, so make sure to use the name you're already defined earlier!
:::

The path should be identical to the default ones, which look like this: `/sw/product/detail/:id/base` Just replace the `base` here with `custom` or anything you like.

It then points to a component, which represents the routes actual content - so you'll have to create [a new component](../module-component-management/add-custom-component.md) in the next step. Note the new import that's already part of this example: `view/sw-product-detail-custom`

## Creating your new component

As shown in the previous example, your custom component is expected to be in a directory `view/sw-product-detail-custom`, so create this directory in your plugin now. The directory structure inside of your Administration directory should then look like this:

```text
administration
├── src
│   └──page
│       └── sw-product-detail
│           ├── index.js
│           └── sw-product-detail.html.twig
|   └──view
│       └── sw-product-detail-custom
│           ├── index.js        
└── main.js
```

Since a component always gets initiated by a file called `index.js`, create such a new file in the `sw-product-detail-custom` directory:

```javascript
// <plugin root>/src/Resources/app/administration/src/view/sw-product-detail-custom/index.js
import template from './sw-product-detail-custom.html.twig';

Shopware.Component.register('sw-product-detail-custom', {
    template,

    metaInfo() {
        return {
            title: 'Custom'
        };
    },
});
```

This file mainly registers a new component with a custom title and a custom template. Once more, the referenced template is still missing, so make sure to create the file `sw-product-detail-custom.html.twig` next to your `index.js` file.

Here's what this new template could look like:

```html
// <plugin root>/src/Resources/app/administration/src/view/sw-product-detail-custom/sw-product-detail-custom.html.twig
<sw-card title="Custom">
    Hello world!
</sw-card>
```

It simply creates a new card with a title, which only contains a 'Hello world!' string. And that's it - your tab should now be fully functional.

---

---
url: /docs/guides/plugins/plugins/administration/routing-navigation/add-new-tab.md
---

# Add Tab to Existing Module

## Overview

This guide covers creating a new tab in the Administration. A realistic example would be adding a new association for an entity, which you want to configure on a separate tab on the entity detail page.

## Prerequisites

This guide requires you to already have a basic plugin running. If you don't know how to do this in the first place, have a look at our plugin base guide:

In the course of this guide, you need to create a custom route. If you want to learn on how to create a custom component, please refer to the guide on it:

Also, we will use a small, custom component to fill our custom tab. In order to get used to that, it might come in handy to read the corresponding guide first:

::: info

### Please remember

The main entry point to customize the Administration via plugin is the `main.js` file. It has to be placed into a `<plugin root>/src/Resources/app/administration/src` directory in order to be found by Shopware 6. So please use the file accordingly and refer to the [plugin base guide](../../plugin-base-guide.md) for more details.
:::

## Creating a custom tab

### Find the block to extend

For this guide, we'll think about the following example: The product detail page is extended by a new tab, which then only contains a 'Hello world!'. In order to refer to this example, let's have a look at the twig code of the product detail page found here:

Let's imagine your first goal is to create a new tab on the product detail page. Having a look at the template, you might find the block `sw_product_detail_content_tabs`, which seems to contain all available tabs. It starts by creating a new `<sw-tabs>` element to contain all the tabs available. Here you can see excerpt of this block:

```twig
// platform/src/Administration/Resources/app/administration/src/module/sw-product/page/sw-product-detail/sw-product-detail.html.twig
{% block sw_product_detail_content_tabs %}
    <sw-tabs class="sw-product-detail-page__tabs" v-if="productId">
        {% block sw_product_detail_content_tabs_general %}
            <sw-tabs-item
                class="sw-product-detail__tab-general"
                :route="{ name: 'sw.product.detail.base', params: { id: $route.params.id } }"
                :hasError="swProductDetailBaseError"
                :title="$tc('sw-product.detail.tabGeneral')">
                {{ $tc('sw-product.detail.tabGeneral') }}
            </sw-tabs-item>
        {% endblock %}

        ...

        {% block sw_product_detail_content_tabs_reviews %}
            <sw-tabs-item
                class="sw-product-detail__tab-reviews"
                :route="{ name: 'sw.product.detail.reviews', params: { id: $route.params.id } }"
                :title="$tc('sw-product.detail.tabReviews')">
                {{ $tc('sw-product.detail.tabReviews') }}
            </sw-tabs-item>
        {% endblock %}
    </sw-tabs>
{% endblock %}
```

Unfortunately, you cannot use the block mentioned above, because then your new tab wouldn't be inside the `<sw-tabs>` element. Instead, you can choose the last available block inside the element, which is `sw_product_detail_content_tabs_reviews` at this moment.

### Create custom tab

Knowing the block you have to override in your plugin, you can now start doing exactly this: Add your custom tab by overriding this block called `sw_product_detail_content_tabs_reviews`.

::: danger
However, please keep in mind that "overriding" doesn't mean we want to replace the block completely with our new one. We want to add our tab, thus only extending the template. This will have some implications on our implementation.
:::

First, please re-create the directory structure from the core code in your plugin. In this case, you'll have to create a directory structure like the following: `<plugin root>/src/Resources/app/administration/src/page/sw-product-detail`

In there you create a new file `index.js`, which then contains the following code:

```javascript
// <plugin root>/src/Resources/app/administration/src/page/sw-product-detail/index.js
import template from './sw-product-detail.html.twig';

// Override your template here, using the actual template from the core
Shopware.Component.override('sw-product-detail', {
    template
});
```

All this file is doing is to basically override the `sw-product-detail` component with a new template. The new template does not exist yet though, so create a new file `sw-product-detail.html.twig` in the same directory as your `index.js` file. It then has to use the block we figured out earlier and override it by adding a new tab element:

```twig
// <plugin root>/src/Resources/app/administration/src/page/sw-product-detail/sw-product-detail.html.twig
{% block sw_product_detail_content_tabs_reviews %}

    {# This parent is very important as you don't want to override the review tab completely #}
    {% parent %}

{% endblock %}
```

::: warning
The block gets overridden and immediately the parent block is called, since you do not want to replace the 'Review' tab, you want to add a new tab instead.
:::

After that, we'll create the actual `sw-tabs-item` element, which, as the name suggests, represents a new tab item. We want this tab to have a custom route, so we're also adding this route directly. Don't worry, we'll explain this custom route in a bit. The product detail page's route contain the product's ID, which you also want to have in your custom tab: So make sure to also pass the ID in, like shown in the example above.

```twig
// <plugin root>/src/Resources/app/administration/src/page/sw-product-detail/sw-product-detail.html.twig
{% block sw_product_detail_content_tabs_reviews %}

    {% parent %}

    <!-- We'll define a custom route here, an explanation will follow later -->
    <sw-tabs-item :route="{ name: 'sw.product.detail.custom', params: { id: $route.params.id } }" title="Custom">
        Custom
    </sw-tabs-item>
{% endblock %}
```

The [route](../routing-navigation/add-custom-route.md) being used here has the name `sw.product.detail.custom`, this will become important again later on.

### Loading the new tab

You've now created a new tab, but your new template is not yet loaded. Remember, that the main entry point for custom javascript for the Administration is the your plugin's `main.js` file. And that's also the file you need to adjust now, so it loads your `sw-product-detail` override.

This is an example of what your `main.js` should look like in order to load your override:

```javascript
import './page/sw-product-detail';
```

::: info
Don't forget to rebuild the Administration after applying changes to your `main.js`.

```bash
shopware-cli project admin-build
```

```bash
composer run build:js:admin
```

## Registering the tab's new route

Your new tab should now already show up on the product detail page, but clicking it should always result in an error. It's basically pointing to a new route, which you never defined yet.

Next step would be the following: Create a new route and map it to your own component. This is done by registering a new dummy module, which then overrides the method `routeMiddleware` of a module. It gets called for each and every route that is called in the Administration. Once the `sw.product.detail` route is called, you want to add your new child route to it.

You can add those changes to your `main.js` file, which could then look like this:

```javascript
// <plugin root>/src/Resources/app/administration/src/main.js
import './page/sw-product-detail';
import './view/sw-product-detail-custom';

// Here you create your new route, refer to the mentioned guide for more information
Shopware.Module.register('sw-new-tab-custom', {
    routeMiddleware(next, currentRoute) {
        const customRouteName = 'sw.product.detail.custom';
    
        if (
            currentRoute.name === 'sw.product.detail' 
            && currentRoute.children.every((currentRoute) => currentRoute.name !== customRouteName)
        ) {
            currentRoute.children.push({
                name: customRouteName,
                path: '/sw/product/detail/:id/custom',
                component: 'sw-product-detail-custom',
                meta: {
                    parentPath: 'sw.product.index'
                }
            });
        }
        next(currentRoute);
    }
});
```

As already mentioned, you need to create a dummy module in order to override the `routeMiddleware` method. In there, you're listening for the current route, that got called. If the current route matches `sw.product.detail`, you want to add your new child route to it, and that's what's done here.

::: warning
Your child route defines the routes name, so make sure to use the name you're already defined earlier!
:::

The path should be identical to the default ones, which look like this: `/sw/product/detail/:id/base` Just replace the `base` here with `custom` or anything you like.

It then points to a component, which represents the routes actual content - so you'll have to create [a new component](../module-component-management/add-custom-component.md) in the next step. Note the new import that's already part of this example: `view/sw-product-detail-custom`

## Creating your new component

As shown in the previous example, your custom component is expected to be in a directory `view/sw-product-detail-custom`, so create this directory in your plugin now. The directory structure inside of your Administration directory should then look like this:

```text
administration
├── src
│   └──page
│       └── sw-product-detail
│           ├── index.js
│           └── sw-product-detail.html.twig
|   └──view
│       └── sw-product-detail-custom
│           ├── index.js        
└── main.js
```

Since a component always gets initiated by a file called `index.js`, create such a new file in the `sw-product-detail-custom` directory:

```javascript
// <plugin root>/src/Resources/app/administration/src/view/sw-product-detail-custom/index.js
import template from './sw-product-detail-custom.html.twig';

Shopware.Component.register('sw-product-detail-custom', {
    template,

    metaInfo() {
        return {
            title: 'Custom'
        };
    },
});
```

This file mainly registers a new component with a custom title and a custom template. Once more, the referenced template is still missing, so make sure to create the file `sw-product-detail-custom.html.twig` next to your `index.js` file.

Here's what this new template could look like:

```html
// <plugin root>/src/Resources/app/administration/src/view/sw-product-detail-custom/sw-product-detail-custom.html.twig
<sw-card title="Custom">
    Hello world!
</sw-card>
```

It simply creates a new card with a title, which only contains a 'Hello world!' string. And that's it - your tab should now be fully functional.

---

---
url: /docs/resources/references/adr/2020-11-20-add-login-required-annotation.md
---

# Add the login required annotation

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2020-11-20-add-login-required-annotation.md)
:::

## Context

Some routes for the `sales-channel-api` and the `store-api/storefront` depend on `SalesChannelContext` to identify whether the Customer is logged or not.
For keeping clean code, consistency, and more easy to readable API. We create a new annotation for routing `\Core\Framework\Routing\Annotation\LoginRequired`.

## Decision

With the `store-api/storefront` routing needs requiring logged in for access, developers need to define annotation `@LoginRequired `for API.

This annotation to the following:

* `@LoginRequired`
  * This annotation is validating the `SalesChannelContext` has Customer return success, otherwise throw `CustomerNotLoggedInException`
* `@LoginRequired(allowGuest=true)`
  * This annotation is validating the `SalesChannelContext` has Customer and allow Guest admits, otherwise throw `CustomerNotLoggedInException`

An example looks like the following:

```php
/**
 * @Since("6.0.0.0")
 * @LoginRequired()
 * @Route(path="/store-api/v{version}/account/logout", name="store-api.account.logout", methods={"POST"})
 */

/**
 * @Since("6.2.0.0")
 * @LoginRequired(allowGuest=true)
 * @Route("/account/order/edit/{orderId}", name="frontend.account.edit-order.page", methods={"GET"})
 */
```

## Consequences

From the moment the `LoginRequired` annotation should be using every new `store-api/storefront` if the routing needs requiring logged in for access.
If `LoginRequired` is not using, that means the `store-api/storefront` can accept without a login.

---

---
url: >-
  /docs/v6.5/resources/references/adr/2020-11-20-add-login-required-annotation.md
---

# Add the login required annotation

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2020-11-20-add-login-required-annotation.md)
:::

## Context

Some routes for the `sales-channel-api` and the `store-api/storefront` depend on `SalesChannelContext` to identify whether the Customer is logged or not.
For keeping clean code, consistency, and more easy to readable API. We create a new annotation for routing `\Core\Framework\Routing\Annotation\LoginRequired`.

## Decision

With the `store-api/storefront` routing needs requiring logged in for access, developers need to define annotation `@LoginRequired `for API.

This annotation to the following:

* `@LoginRequired`
  * This annotation is validating the `SalesChannelContext` has Customer return success, otherwise throw `CustomerNotLoggedInException`
* `@LoginRequired(allowGuest=true)`
  * This annotation is validating the `SalesChannelContext` has Customer and allow Guest admits, otherwise throw `CustomerNotLoggedInException`

An example looks like the following:

```php
/**
 * @Since("6.0.0.0")
 * @LoginRequired()
 * @Route(path="/store-api/v{version}/account/logout", name="store-api.account.logout", methods={"POST"})
 */

/**
 * @Since("6.2.0.0")
 * @LoginRequired(allowGuest=true)
 * @Route("/account/order/edit/{orderId}", name="frontend.account.edit-order.page", methods={"GET"})
 */
```

## Consequences

From the moment the `LoginRequired` annotation should be using every new `store-api/storefront` if the routing needs requiring logged in for access.
If `LoginRequired` is not using, that means the `store-api/storefront` can accept without a login.

---

---
url: >-
  /docs/v6.6/resources/references/adr/2020-11-20-add-login-required-annotation.md
---

# Add the login required annotation

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2020-11-20-add-login-required-annotation.md)
:::

## Context

Some routes for the `sales-channel-api` and the `store-api/storefront` depend on `SalesChannelContext` to identify whether the Customer is logged or not.
For keeping clean code, consistency, and more easy to readable API. We create a new annotation for routing `\Core\Framework\Routing\Annotation\LoginRequired`.

## Decision

With the `store-api/storefront` routing needs requiring logged in for access, developers need to define annotation `@LoginRequired `for API.

This annotation to the following:

* `@LoginRequired`
  * This annotation is validating the `SalesChannelContext` has Customer return success, otherwise throw `CustomerNotLoggedInException`
* `@LoginRequired(allowGuest=true)`
  * This annotation is validating the `SalesChannelContext` has Customer and allow Guest admits, otherwise throw `CustomerNotLoggedInException`

An example looks like the following:

```php
/**
 * @Since("6.0.0.0")
 * @LoginRequired()
 * @Route(path="/store-api/v{version}/account/logout", name="store-api.account.logout", methods={"POST"})
 */

/**
 * @Since("6.2.0.0")
 * @LoginRequired(allowGuest=true)
 * @Route("/account/order/edit/{orderId}", name="frontend.account.edit-order.page", methods={"GET"})
 */
```

## Consequences

From the moment the `LoginRequired` annotation should be using every new `store-api/storefront` if the routing needs requiring logged in for access.
If `LoginRequired` is not using, that means the `store-api/storefront` can accept without a login.

---

---
url: /docs/v6.5/guides/plugins/plugins/storefront/add-translations.md
---

# Add translations

## Overview

In this guide you'll learn how to add translations to the Storefront and how to use them in your twig templates. To organize your snippets you can add them to `.json` files, so structuring and finding snippets you want to change is very easy.

## Prerequisites

To add your own custom translations for your plugin or app, you first need a base. Refer to either the [Plugin Base Guide](../plugin-base-guide) or the [App Base Guide](../../apps/app-base-guide) to create one.

## Snippet file structure

Shopware 6 automatically loads your snippet files when a standard file structure and a naming convention are followed. To do so, store your snippet files in the `<extension root>/src/Resources/snippet/<locale>/` directory of your extension. Also, you can further use subdirectories if you want to. Use `<name>.<locale>` as the naming pattern. The name can be freely defined, while the locale must map to the ISO string of the supported locale in this snippet file - for example `example.de-DE.json`.

In case you want to provide base translations (ship translations for a whole new language), indicate it with the suffix `.base` in your file name. Now the filename convention to be followed looks like this `<name>.<locale>.base.json` - for example, `example.de-AT.base.json`.

So your structure could then look like this:

```text
└── SwagBasicExample
    └── src
        ├─ Resources
        │  └─ snippet
        │     ├─ de_DE
        │     │  └─ example.de-DE.json
        │     └─ en_GB
        │        └─ example.en-GB.json
        └─ SwagBasicExample.php
```

## Creating the translation

Now that we know how the structure of snippets should be, we can create a new snippet file. In this example we are creating a snippet file for British English called `example.en-GB.json`. If you are using nested objects, you can access the values with `exampleOne.exampleTwo.exampleThree`. We can also use template variables, which we can assign values later in the template. There is no explicit syntax for variables in the Storefront. However, it is recommended to enclose them with `%` symbols to make their purpose clear.

Here's an example of an English translation file:

```json
// <extension root>/src/Resources/snippet/en\_GB/example.en-GB.json
{
  "header": {
    "example": "Our example header"
  },
  "soldProducts": "Sold about %count% products in %country%"
}
```

## Using the translation in templates

Now we want to use our previously created snippet in our twig template, we can do this with the `trans` filter. Below you can find two examples where we use our translation with placeholders and without.

Translation without placeholders:

```twig
<div class="product-detail-headline">
    {{ 'header.example' | trans }}
</div>
```

Translation with placeholders:

```twig
<div class="product-detail-headline">
    {{ 'soldProducts' | trans({'%count%': 3, '%country%': 'Germany'}) }}
</div>
```

## Using the translation in controllers

If we want to use our snippet in a controller, we have to use the `trans` function. Note that we have to extend our class from `Shopware\Storefront\Controller\StorefrontController`.

Translation without placeholders:

```php
$this->trans('header.example');
```

Translation with placeholders:

```php
$this->trans('soldProducts', ['%count%' => 3, '%country%' => 'Germany']);
```

## Using translation generally in PHP

If we need to use a snippet elsewhere in PHP, we can use [Dependency Injection](../plugin-fundamentals/dependency-injection) to inject the `translator`, which implements Symfony's `Symfony\Contracts\Translation\TranslatorInterface`:

```xml
<service id="Swag\Example\Service\SwagService" public="true" >
    <argument type="service" id="translator" />
</service>
```

```php
private TranslatorInterface $translator;

public function __construct(TranslatorInterface $translator)
{
    $this->translator = $translator;
}
```

Your class can then use translation similarly to controllers:

```php
$this->translator->trans('soldProducts', ['%count%' => 3, '%country%' => 'Germany']);
```

---

---
url: /docs/v6.6/guides/plugins/plugins/storefront/add-translations.md
---

# Add translations

## Overview

In this guide, you'll learn how to add translations to the Storefront and how to use them in your twig templates.
To organize your snippets you can add them to `.json` files, so structuring and finding snippets you want to change is very easy.

## Prerequisites

To add your own custom translations for your plugin or app, you first need a base.
Refer to either the [Plugin Base Guide](../plugin-base-guide) or the [App Base Guide](../../apps/app-base-guide) to create one.

## Snippet file structure

Shopware 6 automatically loads your snippet files when a standard file structure and a naming convention are followed.
To do so, store your snippet files in the `<extension root>/src/Resources/snippet/` directory of your plugin or `<extension root>/Resources/snippet/` for your app or theme.
Also, you can use further subdirectories if you want to.
Use `<name>.<locale>` as the naming pattern for the file.
The name can be freely defined, while the locale **must** map to the ISO string of the supported locale in this snippet file - for example `example.de-DE.json`.
More precisely, the ISO string is a combination of "ISO 639-1" language codes and "ISO 3166-1 alpha-2" country codes.
Later, this will be converted to the ICU format (`de_DE`), which is also used by [Symfony](https://symfony.com/doc/current/reference/constraints/Locale.html).

In case you want to provide base translations (ship translations for a whole new language), indicate it with the suffix `.base` in your file name.
Now the filename convention to be followed looks like this `<name>.<locale>.base.json` - for example, `example.de-AT.base.json`.

So your structure could then look like this:

```text
└── SwagBasicExample
    └── src // Without `src` in apps / themes
        ├─ Resources
        │  └─ snippet
        │     ├─ example.de-DE.json
        │     └─ some-directory // optional
        │        └─ example.en-GB.json
        └─ SwagBasicExample.php
```

## Creating translations

Now that we know how the structure of snippets should be, we can create a new snippet file.
In this example we are creating a snippet file for British English called `example.en-GB.json`.
If you are using nested objects, you can access the values with `exampleOne.exampleTwo.exampleThree`.
We can also use template variables, which we can assign values later in the template.
There is no explicit syntax for variables in the Storefront.
However, it is recommended to enclose them with `%` symbols to make their purpose clear.

Here's an example of an English translation file:

```json
// <extension root>/src/Resources/snippet/en_GB/example.en-GB.json
{
  "header": {
    "example": "Our example header"
  },
  "soldProducts": "Sold about %count% products in %country%"
}
```

## Using translations in templates

Now we want to use our previously created snippet in our twig template, we can do this with the `trans` filter.
Below, you can find two examples where we use our translation with placeholders and without.

Translation without placeholders:

```twig
<div class="product-detail-headline">
    {{ 'header.example' | trans }}
</div>
```

Translation with placeholders:

```twig
<div class="product-detail-headline">
    {{ 'soldProducts' | trans({'%count%': 3, '%country%': 'Germany'}) }}
</div>
```

## Using translations in controllers

If we want to use our snippet in a controller, we can use the `trans` method,
which is available if our class is extending from `Shopware\Storefront\Controller\StorefrontController`.
Or use injection via [DI container](#using-translation-generally-in-php).

Translation without placeholders:

```php
$this->trans('header.example');
```

Translation with placeholders:

```php
$this->trans('soldProducts', ['%count%' => 3, '%country%' => 'Germany']);
```

## General usage of translations in PHP

If we need to use a snippet elsewhere in PHP,
we can use [Dependency Injection](../plugin-fundamentals/dependency-injection) to inject the `translator` service,
which implements Symfony's `Symfony\Contracts\Translation\TranslatorInterface`:

```xml
<service id="Swag\Example\Service\SwagService" public="true" >
    <argument type="service" id="translator" />
</service>
```

```php
private TranslatorInterface $translator;

public function __construct(TranslatorInterface $translator)
{
    $this->translator = $translator;
}
```

Then, call the `trans` method, which has the same parameters as the method from controllers.

```php
$this->translator->trans('soldProducts', ['%count%' => 3, '%country%' => 'Germany']);
```

---

---
url: /docs/guides/plugins/plugins/storefront/styling/add-translations.md
---

# Add Translations

## Overview

In this guide, you'll learn how to add translations to the Storefront and how to use them in your twig templates.
To organize your snippets you can add them to `.json` files, so structuring and finding snippets you want to change is very easy.

## Prerequisites

To add your own custom translations for your plugin or app, you first need a base.
Refer to either the [Plugin Base Guide](../../plugin-base-guide.md) or the [App Base Guide](../../../apps/app-base-guide.md) to create one.

## Snippet file structure

Shopware 6 automatically loads your snippet files when you follow the standard file structure and naming convention.
To enable this, store your snippet files in the `<extension root>/src/Resources/snippet/` directory of your plugin or `<extension root>/Resources/snippet/` for your app or theme.

You can also use subdirectories if you prefer, although we recommend keeping a flat structure for better maintainability.
Use `<domain>.<locale>.json` as the naming pattern for the file.

The domain can be freely defined (we recommend your extension name in kebab case), while the locale **must** map to the ISO string of the supported locale in this snippet file — for example: `my-app.de.json`.
Locales should follow the ISO string of the supported language, such as `de`, `en`, or `es-AR`.
This format follows [IETF BCP 47](https://datatracker.ietf.org/doc/html/bcp47), restricted to [ISO 639-1 (2-letter) language codes](https://en.wikipedia.org/wiki/ISO_639-1) as used by [Symfony](https://symfony.com/doc/current/reference/constraints/Locale.html), but with dashes (`-`) instead of underscores (`_`).

For more information on selecting proper locales, see our documentation on [Fallback language selection](../../../../../concepts/framework/translations/fallback-language-selection.md).

In case you want to provide base translations (ship translations for a whole new language), indicate it with the suffix `.base` in your file name.
Now the filename convention to be followed looks like this `<name>.<locale>.base.json` - for example, `my-app.de.base.json`.

So your structure could then look like this:

```text
└── SwagBasicExample
    └── src // Without `src` in apps / themes
        ├─ Resources
        │  └─ snippet
        │     ├─ my-app.de.json
        │     ├─ my-app.en.json
        │     └─ some-directory // optional
        │        └─ some-special-case.en.json
        └─ SwagBasicExample.php
```

## Creating translations

Now that we know how the structure of snippets should be, we can create a new snippet file.
In this example we are creating a snippet file for (British) English called `example.en.json`.
If you are using nested objects, you can access the translation values with `exampleOne.exampleTwo.exampleThree`.
We can also use template variables, which we can assign values later in the template.
There is no explicit syntax for variables in the Storefront.
However, it is recommended to enclose them with `%` symbols to make their purpose clear.

Here's an example of an English translation file:

```json
// <extension root>/src/Resources/snippet/en_GB/example.en-GB.json
{
  "header": {
    "example": "Our example header"
  },
  "soldProducts": "Sold about %count% products in %country%"
}
```

## Using translations in templates

Now we want to use our previously created snippet in our twig template, we can do this with the `trans` filter.
Below, you can find two examples where we use our translation with placeholders and without.

Translation without placeholders:

```twig
<div class="product-detail-headline">
    {{ 'header.example' | trans }}
</div>
```

Translation with placeholders:

```twig
<div class="product-detail-headline">
    {{ 'soldProducts' | trans({'%count%': 3, '%country%': 'Germany'}) }}
</div>
```

## Using translations in controllers

If we want to use our snippet in a controller, we can use the `trans` method,
which is available if our class is extending from `Shopware\Storefront\Controller\StorefrontController`.
Or use injection via [DI container](#general-usage-of-translations-in-php).

Translation without placeholders:

```php
$this->trans('header.example');
```

Translation with placeholders:

```php
$this->trans('soldProducts', ['%count%' => 3, '%country%' => 'Germany']);
```

## General usage of translations in PHP

If we need to use a snippet elsewhere in PHP,
we can use [Dependency Injection](../../services/dependency-injection.md) to inject the `translator` service,
which implements Symfony's `Symfony\Contracts\Translation\TranslatorInterface`:

```php
$services->set(Swag\Example\Service\SwagService::class)
    ->args([service('translator')]);
```

```php
private TranslatorInterface $translator;

public function __construct(TranslatorInterface $translator)
{
    $this->translator = $translator;
}
```

Then, call the `trans` method, which has the same parameters as the method from controllers.

```php
$this->translator->trans('soldProducts', ['%count%' => 3, '%country%' => 'Germany']);
```

---

---
url: >-
  /docs/resources/references/adr/2022-06-24-add-typescript-support-for-storefront-js.md
---

# Add typescript support for storefront javascript

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-06-24-add-typescript-support-for-storefront-js.md)
:::

## Context

* We want to add TypeScript support to the Storefront, to make use of all of it's features increasing the overall developer experience, quality and maintainability.
* The main concern is the compatibility to existing Storefront plugins, which have been built in previous versions without TypeScript support.
* TypeScript files need to be compatible with JavaScript files and vice versa, for both the Storefront internally, and also for plugins.

## Decision

* To prevent any breaks in our current Storefront stack, we will add TypeScript language support to the current babel chain, using the preset `@babel/preset-typescript`.
* To prevent any breaks for existing Storefront plugins, we won't replace any publicly used .js files with .ts files, without proper deprecation.

## Consequences

* TypeScript (.ts and .tsx) files are now supported by the Storefront.
* Storefront plugins can now be developed using TypeScript and the actual Storefront JavaScript can be incrementally converted to .ts files from now on.
* TypeScript files and JavaScript files are compatible and can be imported to each other.

---

---
url: >-
  /docs/v6.5/resources/references/adr/2022-06-24-add-typescript-support-for-storefront-js.md
---

# Add typescript support for storefront javascript

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-06-24-add-typescript-support-for-storefront-js.md)
:::

## Context

* We want to add TypeScript support to the Storefront, to make use of all of it's features increasing the overall developer experience, quality and maintainability.
* The main concern is the compatibility to existing Storefront plugins, which have been built in previous versions without TypeScript support.
* TypeScript files need to be compatible with JavaScript files and vice versa, for both the Storefront internally, and also for plugins.

## Decision

* To prevent any breaks in our current Storefront stack, we will add TypeScript language support to the current babel chain, using the preset `@babel/preset-typescript`.
* To prevent any breaks for existing Storefront plugins, we won't replace any publicly used .js files with .ts files, without proper deprecation.

## Consequences

* TypeScript (.ts and .tsx) files are now supported by the Storefront.
* Storefront plugins can now be developed using TypeScript and the actual Storefront JavaScript can be incrementally converted to .ts files from now on.
* TypeScript files and JavaScript files are compatible and can be imported to each other.

---

---
url: >-
  /docs/v6.6/resources/references/adr/2022-06-24-add-typescript-support-for-storefront-js.md
---

# Add typescript support for storefront javascript

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-06-24-add-typescript-support-for-storefront-js.md)
:::

## Context

* We want to add TypeScript support to the Storefront, to make use of all of it's features increasing the overall developer experience, quality and maintainability.
* The main concern is the compatibility to existing Storefront plugins, which have been built in previous versions without TypeScript support.
* TypeScript files need to be compatible with JavaScript files and vice versa, for both the Storefront internally, and also for plugins.

## Decision

* To prevent any breaks in our current Storefront stack, we will add TypeScript language support to the current babel chain, using the preset `@babel/preset-typescript`.
* To prevent any breaks for existing Storefront plugins, we won't replace any publicly used .js files with .ts files, without proper deprecation.

## Consequences

* TypeScript (.ts and .tsx) files are now supported by the Storefront.
* Storefront plugins can now be developed using TypeScript and the actual Storefront JavaScript can be incrementally converted to .ts files from now on.
* TypeScript files and JavaScript files are compatible and can be imported to each other.

---

---
url: >-
  /docs/resources/references/adr/2025-09-01-adding-a-country-agnostic-language-layer.md
---

# Adding a country-agnostic language layer

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2025-09-01-adding-a-country-agnostic-language-layer.md)
:::

## Context

Currently, Shopware’s language system uses a specific language locale (e.g. `de-DE` for German in Germany) for its translation, while falling back to another specific locale (e.g. `en-GB` for English in Great Britain).

This works well, but it is quite maintenance-heavy. If you use multiple versions or dialects of a language, such as British and American English, it will result in a lot of duplicated snippets.

### Some facts and figures

* Shopware has approximately 12,000 snippets.
* By default, the US translation is an automated copy of the GB translation, which is later adjusted by our community via Crowdin.
* When running them through a comparison tool, we find about 70 differences. This means that roughly 99.5% of our American snippets are identical to the British ones.

### Current structure

```mermaid
flowchart LR
    subgraph "Specific language"
        deDE("<strong>de-DE</strong><br/><em>German in Germany</em>")
        deAT("<strong>de-AT</strong><br/><em>German in Austria</em>")
        esES("<strong>es-ES</strong><br/><em>Spanish in Spain</em>")
        esAR("<strong>es-AR</strong><br/><em>Spanish in Argentina</em>")
        enUS("<strong>en-US</strong><br/><em>English in the USA</em>")
    end
    subgraph "System default language"
        enGB("<strong>en-GB</strong><br/><em>English in Great Britain</em>")
    end
        
    deDE-->enGB
    deAT-->enGB

    esES-->enGB
    esAR-->enGB
    
    enUS-->enGB
```

## Decision

Another layer containing a country-agnostic language (e.g., `en` for both `en-GB` and `en-US`) will provide an additional fallback layer. This means dialects are now treated as patch files. In Shopware, `en-GB` will be renamed to `en`, as you have to select a base dialect, retaining its 12,000 snippets, while `en-US` will shrink to around 70 snippets. This also eliminates the need for tools to initially copy-paste or pre-translate from "English to English," which, of course, incurs costs.

## Consequences

* Every additional dialect’s snippet file (e.g., `en-US` for `en`) will shrink from around 12,000 entries to likely fewer than 100.
* We will also provide an additional layer to maximize compatibility with existing installations. This means that `en-GB` will still be available as a fallback for other languages like `de-DE`, but `en` will be the primary fallback for everything.
* We will also provide an additional layer to ensure maximum compatibility with existing translations (e.g. via extensions). This means `en-GB` will remain available as a fallback for other languages such as `de-DE` and `de`, while `en` will serve as the final fallback.
* Translations provided via the community (Crowdin) will show a lower coverage percentage, but will more accurately reflect the actual differences between `en-US` and `en`.
* In Crowdin and in our product, the base language is set declaratively, so we will inform the community that British English is our base language, and we simply refer to it as `en`.
* All snippet files in Shopware’s core will be renamed to the country-agnostic language
  * `en-GB.json` -> `en.json`, `messages.en-GB.base.json` -> `messages.en.base.json` and so on.
  * Similarly: `de-DE` -> `de`
* The community translations / language pack will update their locales to their country-agnostic versions as well (e.g., `es-ES` -> `es`).
* The system’s default language or active language handling will remain unchanged.
* Plugins and apps do not require immediate adjustments, as the previous structure will continue to function as before as well.

### New structure

```mermaid
flowchart LR
    subgraph "Specific language (German)"
        deDE("<strong>de-DE</strong><br/><em>German in Germany</em>")
        deAT("<strong>de-AT</strong><br/><em>German in Austria</em>")
        de("<strong>de</strong><br/><em>German</em>")
    end
    subgraph "Specific language (Spanish)"
        esES("<strong>es-ES</strong><br/><em>Spanish in Spain</em>")
        esAR("<strong>es-AR</strong><br/><em>Spanish in Argentina</em>")
        es("<strong>es</strong><br/><em>Spanish</em>")
    end
        subgraph "Specific language (English)"
        enUS("<strong>en-US</strong><br/><em>English in the USA</em>")
    end
    subgraph "Fallback (English)"
        enGB("<strong>en-GB</strong><br/><em>English in Great Britain</em>")
        en("<strong>en</strong><br/><em>English</em>")
    end

    deDE-->de
    deAT-->de
    de-->enGB

    esES-->es
    esAR-->es
    es-->enGB

    enUS-->en
    enGB-->en

    style de color:#6f6,stroke:#6f6
    style es color:#6f6,stroke:#6f6
    style en color:#6f6,stroke:#6f6
    
    style enGB stroke-dasharray: 5
```

---

---
url: /docs/products/extensions/b2b-suite-migration/development/adding-component.md
---

# Adding a New Component

This section guides developers on adding a new component to the migration process.

## Register a Migration Configurator

* Create a class extending `Shopware\Commercial\B2B\B2BSuiteMigration\Core\Domain\MappingConfigurator\AbstractB2BMigrationConfigurator`.
* Define the component name in lowercase snake\_case in `getName()`.
* Specify the [XML mapping](#create-xml-mapping-file) path in `configPath()`.
* Tag the class with `b2b.migration.configurator`.
  **Example**:

  ```php
  $services->set(Shopware\Commercial\B2B\B2BSuiteMigration\Components\EmployeeManagement\EmployeeManagementMigrationConfigurator::class)
      ->tag('b2b.migration.configurator', ['priority' => 9000]);
  ```

  ```PHP
  class EmployeeManagementMigrationConfigurator extends AbstractB2BMigrationConfigurator
  {
    public function getName(): string
    {
        return 'employee_management';
    }

    public function configPath(): string
    {
        return 'path/to/your/xml/mapping/file.xml';
    }
    ...
  }
  ```

  * The `priority` attribute in the tag determines the order of execution among multiple configurator. Higher values execute first.
    :::info
    You can run this command to see the order of execution:

    ```bash
    php bin/console debug:container --tag=b2b.migration.configurator
    ```

    The default priorities for existing configurator are:

    * `EmployeeManagementMigrationConfigurator` has a priority of `9000`.
    * `QuoteB2BMigrationConfigurator` has a priority of `8000`.
    * `ShoppingListMigrationConfigurator` has a priority of `7000`.
    * `BudgetManagementMigrationConfigurator` has a priority of `5000`.
      :::

## Create XML Mapping File

### Entity Definition

```XML
<migration xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../../../Core/Resources/Schema/Xml/migration-1.0.xsd">
 <entity>
   <name>migration_b2b_component_business_partner</name>
   <source>b2b_customer_data</source>
   <source_primary_key>customer_id</source_primary_key>
   <target>b2b_business_partner</target>
   <target_primary_key>id</target_primary_key>
   <conditions>
     <condition>foo = bar</condition>
   </conditions>
   <fields>
     ...
   </fields>
 </entity>
</migration>
```

* **name**: Unique migration process identifier.
* **source**: Source table name.
* **source\_primary\_key**: Source table primary key (default: `id`).
* **target**: Target table name.
* **target\_primary\_key**: Target table primary key (default: `id`).
* **conditions**: Optional conditions to filter source records (see [Conditions](#conditions)).
* **fields**: Field mappings between source and target tables (see [Field Mapping Configuration](./fields-mapping.md)).

## Conditions

```XML
<conditions>
    <condition>foo = bar</condition>
</conditions>
```

* Conditions allow you to filter which records from the source table are included in the migration process. They are defined in `<condition>` elements within the `<conditions>` block of the XML configuration for each entity.

**Example**:

```XML
<entity>
  <name>migration_b2b_component_business_partner</name>
  <source>b2b_customer_data</source>
  <target>b2b_business_partner</target>
  ...
  <conditions>
    <condition>is_debtor = 1</condition>
  </conditions>
  ...
</entity>
```

* **Explanation**: This filters the records from the `b2b_customer_data` source table (as specified in the XML configuration) to include only entries where the `is_debtor` field is set to `1`.
* **Key Points**:
  * Conditions are written as SQL-like expressions (e.g., `is_debtor = 1`, `status != 'inactive'`).
  * Multiple conditions can be specified, and they are combined with `AND` logic.

::: info
Ensure conditions are valid for the source table schema to avoid runtime errors.
:::

---

---
url: >-
  /docs/guides/plugins/plugins/framework/data-handling/add-complex-data-to-existing-entities.md
---

# Adding Complex Data to Existing Entities

## Overview

Sometimes you want to extend existing entities with some custom information. Extensions are technical and not configurable by the admin user. Also, they can deal with more complex types than scalar ones.

## Prerequisites

To create your own entity extension for your plugin, you first need a plugin as base. Please refer to the [Plugin Base Guide](../../plugin-base-guide).

Basic knowledge of [creating a custom entity](add-custom-complex-data) and [adding associations](add-data-associations) will also be helpful for this guide.

## Creating the extension

In this example, we're going to add a new string field to the `product` entity.

You can choose whether you want to save the new string field to the database or not. Therefore, you're going to see two sections, one for each way.

For both cases, you need to create a new "extension" class in the directory `<plugin root>/src/Extension/`. In this case, we want to extend the `product` entity, so we create a subdirectory `Content/Product/` since the entity location in the Core is the same. Our class needs to extend from the abstract `Shopware\Core\Framework\DataAbstractionLayer\EntityExtension` class, which forces you to implement the `getDefinitionClass` method. It has to point to the entity definition you want to extend, so `ProductDefinition` in this case.

You add new fields by overriding the method `extendFields` and add your new fields in there.

Here's an example class called `CustomExtension`:

```php
// <plugin root>/src/Extension/Content/Product/CustomExtension.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Extension\Content\Product;

use Shopware\Core\Content\Product\ProductDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\EntityExtension;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;

class CustomExtension extends EntityExtension
{
    public function extendFields(FieldCollection $collection): void
    {
        $collection->add(
            // new fields here
        );
    }

    public function getDefinitionClass(): string
    {
        return ProductDefinition::class;
    }
}
```

Now we have to register our extension via the DI-container, explained in greater detail in the [Add a custom class / service](../../services/add-custom-service.md) and [dependency injection](../../services/dependency-injection.md) guides.

Here's our `services.php`:

```php
// <plugin root>/src/Resources/config/services.php
<?php declare(strict_types=1);

use Swag\BasicExample\Extension\Content\Product\CustomExtension;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(CustomExtension::class)
        ->tag('shopware.entity.extension');
};
```

### Adding a field with a database

In this guide, you're extending the product entity in order to add a new string field to it. Since you must not extend the `product` table with a new column, you'll have to add a new table which contains the new data for the product. This new table will then be associated using a [OneToOne association](add-data-associations#One%20to%20One%20associations).

Let's start with the `CustomExtension` class by adding a new field in the `extendFields` method.

```php
// <plugin root>/src/Extension/Content/Product/CustomExtension.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Extension\Content\Product;
use Shopware\Core\Content\Product\ProductDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\EntityExtension;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\CascadeDelete;
use Shopware\Core\Framework\DataAbstractionLayer\Field\OneToOneAssociationField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;

class CustomExtension extends EntityExtension
{
    public function extendFields(FieldCollection $collection): void
    {
        $collection->add(
            (new OneToOneAssociationField('exampleExtension', 'id', 'product_id', ExampleExtensionDefinition::class, true))->addFlags(new CascadeDelete())
        );
    }

    public function getDefinitionClass(): string
    {
        return ProductDefinition::class;
    }
}
```

As you can see, we're adding a new `OneToOneAssociationField`. Its parameters are the following, in correct order:

* `propertyName`: The name of the property which should contain the associated entity of type `ExampleExtensionDefinition` in the `ProductDefinition`. Property names are usually camelCase, with the first character being lower cased.
* `storageName`: Use the `id` column here, which refers to the `id` field of your product. This will be used for the connection to your association. Storage names are always lowercase and snake\_cased.
* `referenceField`: In the `storageName` you defined one of the two connected columns, `id`. The name of the other column in the database, which you want to connect via this association, belongs into this parameter. In that case, it will be a column called `product_id`, which we will define in the `ExampleExtensionDefinition`.
* `referenceClass`: The class name of the definition that we want to connect via the association.
* `autoload`: As the name suggests, this parameter defines if this association should always be loaded by default when the product is loaded. In this case, we definitely want that.

Associations marked with the `CascadeDelete` flag are considered in the clone process. Take a look at the [clone behaviour](../../../../../resources/references/adr/2020-07-02-control-clone-behavior.md)
If the associated entity should not be cloned when cloning a product having it, change it to `CascadeDelete(false)` or remove the flag.

#### Creating ExampleExtensionDefinition

You most likely noticed the new class `ExampleExtensionDefinition`, which we're going to create now. It will contain the actual string field that we wanted to add to the product.

Creating a new entity is not explained in this guide, so make sure you know [this guide](add-custom-complex-data) beforehand.

Our new entity will be located in the same directory as our extension. Let's first have a look at it before going into the explanation:

```php
// <plugin root>/src/Extension/Content/Product/ExampleExtensionDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Extension\Content\Product;

use Shopware\Core\Content\Product\ProductDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Field\FkField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\PrimaryKey;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
use Shopware\Core\Framework\DataAbstractionLayer\Field\IdField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\OneToOneAssociationField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\StringField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;

class ExampleExtensionDefinition extends EntityDefinition
{
    public const ENTITY_NAME = 'swag_example_extension';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    public function getEntityClass(): string
    {
        return ExampleExtensionEntity::class;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
            new FkField('product_id', 'productId', ProductDefinition::class),
            (new StringField('custom_string', 'customString')),
            // ReferenceVersionField only needed on versioned entities
            new ReferenceVersionField(ProductDefinition::class, 'product_version_id'),
            new OneToOneAssociationField('product', 'product_id', 'id', ProductDefinition::class, false)
        ]);
    }
}
```

We've created a new entity definition called `ExampleExtensionDefinition`, as mentioned in the `CustomExtension` class. Its table name will be `swag_example_extension` and it will have a custom entity class called `ExampleExtensionEntity`, as you can see in the `getEntityClass` method. This will remain an example, creating the actual entity `ExampleExtensionEntity` is not part of this guide.

So let's have a look at the `defineFields` method. There's the default `IdField`, that almost every entity owns. The next field is the actual `product_id` column, which will be necessary in order to properly this entity with the product and vice versa. It has to be defined as `FkField` since that's what it is: a foreign key.

Now we're getting to the actual new data, in this example, this is just a new string field. It is called `customString` and can now be used in order to store new string data for the product in the database.

The last field is the inverse side of the `OneToOneAssociationField`. The first parameter defines the name of the property again, which will contain the `ProductEntity`. Now take a look at the second and third parameters. Those are the same as in the `ProductDefinition`, but the other way around. This order is important.

The fourth parameter is the class of the associated definition, the `ProductDefinition` in this case. The last parameter, once again, defines the autoloading. In this example, the product definition will **not** be loaded, when you're just trying to load this extension entity. Yet, the extension entity will always automatically be loaded when the product entity is loaded, just like we defined earlier.

Of course, this new definition also needs to be registered to the DI container:

```php
// <plugin root>/src/Resources/config/services.php
<?php declare(strict_types=1);

use Swag\BasicExample\Extension\Content\Product\CustomExtension;
use Swag\BasicExample\Extension\Content\Product\ExampleExtensionDefinition;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(CustomExtension::class)
        ->tag('shopware.entity.extension');

    $services->set(ExampleExtensionDefinition::class)
        ->tag('shopware.entity.definition', ['entity' => 'swag_example_extension']);
};
```

#### Adding the new database table

Of course, you have to add the new database table via a [Database migration](../../database/database-migrations.md). Look at the guide linked above to see how exactly this is done. Here's the example migration and how it could look like:

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Framework\Migration\MigrationStep;

class Migration1614903457ExampleExtension extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1614903457;
    }

    public function update(Connection $connection): void
    {
    // product_version_id only needed when extending a versioned entity
        $sql = <<<SQL
CREATE TABLE IF NOT EXISTS `swag_example_extension` (
    `id` BINARY(16) NOT NULL,
    `product_id` BINARY(16) NULL,
    `product_version_id` BINARY(16) NOT NULL,
    `custom_string` VARCHAR(255) NULL,
    `created_at` DATETIME(3) NOT NULL,
    `updated_at` DATETIME(3) NULL,
    PRIMARY KEY (`id`),
    CONSTRAINT `unique.swag_example_extension.product` UNIQUE (`product_id`, `product_version_id`),
    CONSTRAINT `fk.swag_example_extension.product_id` FOREIGN KEY (`product_id`, `product_version_id`) REFERENCES `product` (`id`, `version_id`) ON DELETE CASCADE ON UPDATE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
SQL;
        $connection->executeStatement($sql);
    }
}
```

##### Foreign keys

The `AssociationFields` take care of loading the data, but it is recommended to add [foreign key constraints](https://dev.mysql.com/doc/refman/8.0/en/create-table-foreign-keys.html) to your migration query. This will ensure that your data is consistent (checks if the foreign key exists); for example, it will delete the `swag_example_extension` entry when the linked product is deleted.

#### Writing into the new field

As already mentioned, your new association is automatically loaded every time a product entity is loaded. This section will show you how to write to the new field instead.

As with every [write operation](writing-data), this is done via the product repository in this example.

```php
$this->productRepository->upsert([[
    'id' => '<your product ID here>',
    'exampleExtension' => [
        'customString' => 'foo bar'
    ]
]], $context);
```

In this case, you'd write "foo bar" to the product with your desired ID. Note the keys `exampleExtension`, as defined in the product extension class `CustomExtension`, and the key `customString`, which is the property name that you defined in the `ExampleExtensionDefinition` class.

### Adding a field without a database

We can use the DAL event which gets fired every time the product entity is loaded. You can find those kinds of events in the respective entities' event class. In this case, it is `Shopware\Core\Content\Product\ProductEvents`.

Below, you can find an example implementation where we add our extension when the product gets loaded.

```php
// <plugin root>/src/Subscriber/ProductSubscriber.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Subscriber;

use Shopware\Core\Content\Product\ProductEntity;
use Shopware\Core\Framework\Struct\ArrayEntity;
use Shopware\Core\Framework\DataAbstractionLayer\Event\EntityLoadedEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Shopware\Core\Content\Product\ProductEvents;

class ProductSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            ProductEvents::PRODUCT_LOADED_EVENT => 'onProductsLoaded'
        ];
    }

    public function onProductsLoaded(EntityLoadedEvent $event): void
    {
        /** @var ProductEntity $productEntity */
        foreach ($event->getEntities() as $productEntity) {
            $productEntity->addExtension('custom_string', new ArrayEntity(['foo' => 'bar']));
        }
    }
}
```

We're registering to the `ProductEvents::PRODUCT_LOADED_EVENT` event, which is fired every time one or multiple products are requested. In the event listener method `onProductsLoaded`, we're then adding our own data to the new field via the method `addExtension`.

Please note that its second parameter, the actual value, has to be a struct and not just a string or other kind of scalar value.

After we've created our subscriber, we have to adjust our `services.php` to register it. Below you can find our `services.php`.

```php
// <plugin root>/src/Resources/config/services.php
<?php declare(strict_types=1);

use Swag\BasicExample\Subscriber\ProductSubscriber;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(ProductSubscriber::class)
        ->tag('kernel.event_subscriber');
};
```

## Entity extension vs. Custom fields

[Custom fields](../custom-field/add-custom-field) are by default configurable by the admin user in the Administration, and they mostly support scalar types, e.g. a text-field, a number field, or the likes. If you'd like to create associations between entities, you'll need to use an entity extension, just like we did here. Of course, you can also add scalar values without an association to an entity via an extension.

## Bulk entity extensions

::: info
This feature is available since Shopware 6.6.10.0
:::

In case your project or plugin requires many entity extensions, you can register a `BulkEntityExtension` which allows extending multiple entities at once:

```php
<?php

namespace Examples;

use Shopware\Core\Content\Product\ProductDefinition;
use Shopware\Core\Content\Category\CategoryDefinition;

class MyBulkExtension extends BulkEntityExtension
{
    public function collect(): \Generator
    {
        yield ProductDefinition::ENTITY_NAME => [
            new FkField('main_category_id', 'mainCategoryId', CategoryDefinition::class),
        ];

        yield CategoryDefinition::ENTITY_NAME => [
            new FkField('product_id', 'productId', ProductDefinition::class),
            new ManyToOneAssociationField('product', 'product_id', ProductDefinition::class),
        ];
    }
}
```

Each yield defines the entity name which should be extended and the array value defines the fields which should be added. In this example, the `product` and `category` entities are extended.

You must also register the extension in your `services.php` file and tag it with `shopware.bulk.entity.extension`.

```php
$services->set(\Examples\MyBulkExtension::class)
    ->tag('shopware.bulk.entity.extension');
```

---

---
url: >-
  /docs/v6.5/guides/plugins/plugins/framework/data-handling/add-complex-data-to-existing-entities.md
---

# Adding Complex Data to Existing Entities

## Overview

Sometimes you want to extend existing entities with some custom information. Extensions are technical and not configurable by the admin user. Also, they can deal with more complex types than scalar ones.

## Prerequisites

To create your own entity extension for your plugin, you first need a plugin as base. Please refer to the [Plugin Base Guide](../../plugin-base-guide).

Basic knowledge of [creating a custom entity](add-custom-complex-data) and [adding associations](add-data-associations) will also be helpful for this guide.

## Creating the extension

In this example, we're going to add a new string field to the `product` entity.

You can choose whether you want to save the new string field to the database or not. Therefore, you're going to see two sections, one for each way.

For both cases, you need to create a new "extension" class in the directory `<plugin root>/src/Extension/`. In this case, we want to extend the `product` entity, so we create a subdirectory `Content/Product/` since the entity location in the Core is the same. Our class needs to extend from the abstract `Shopware\Core\Framework\DataAbstractionLayer\EntityExtension` class, which forces you to implement the `getDefinitionClass` method. It has to point to the entity definition you want to extend, so `ProductDefinition` in this case.

You add new fields by overriding the method `extendFields` and add your new fields in there.

Here's an example class called `CustomExtension`:

```php
// <plugin root>/src/Extension/Content/Product/CustomExtension.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Extension\Content\Product;

use Shopware\Core\Content\Product\ProductDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\EntityExtension;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;

class CustomExtension extends EntityExtension
{
    public function extendFields(FieldCollection $collection): void
    {
        $collection->add(
            // new fields here
        );
    }

    public function getDefinitionClass(): string
    {
        return ProductDefinition::class;
    }
}
```

Now we have to register our extension via the DI-container. If you don't know how that's done in general, head over to our guide about registering a custom service [Add a custom class / service](../../plugin-fundamentals/add-custom-service) or our guide about the [dependency injection](../../plugin-fundamentals/dependency-injection).

Here's our `services.xml`:

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Extension\Content\Product\CustomExtension">
            <tag name="shopware.entity.extension"/>
        </service>
    </services>
</container>
```

### Adding a field with a database

In this guide, you're extending the product entity in order to add a new string field to it. Since you must not extend the `product` table with a new column, you'll have to add a new table which contains the new data for the product. This new table will then be associated using a [OneToOne association](add-data-associations#One%20to%20One%20associations).

Let's start with the `CustomExtension` class by adding a new field in the `extendFields` method.

```php
// <plugin root>/src/Extension/Content/Product/CustomExtension.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Extension\Content\Product;
use Shopware\Core\Content\Product\ProductDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\EntityExtension;
use Shopware\Core\Framework\DataAbstractionLayer\Field\OneToOneAssociationField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;

class CustomExtension extends EntityExtension
{
    public function extendFields(FieldCollection $collection): void
    {
        $collection->add(
            new OneToOneAssociationField('exampleExtension', 'id', 'product_id', ExampleExtensionDefinition::class, true)
        );
    }

    public function getDefinitionClass(): string
    {
        return ProductDefinition::class;
    }
}
```

As you can see, we're adding a new `OneToOneAssociationField`. Its parameters are the following, in correct order:

* `propertyName`: The name of the property which should contain the associated entity of type `ExampleExtensionDefinition` in the `ProductDefinition`. Property names are usually camelCase, with the first character being lower cased.
* `storageName`: Use the `id` column here, which refers to the `id` field of your product. This will be used for the connection to your association. Storage names are always lowercase and snake\_cased.
* `referenceField`: In the `storageName` you defined one of the two connected columns, `id`. The name of the other column in the database, which you want to connect via this association, belongs into this parameter. In that case, it will be a column called `product_id`, which we will define in the `ExampleExtensionDefinition`.
* `referenceClass`: The class name of the definition that we want to connect via the association.
* `autoload`: As the name suggests, this parameter defines if this association should always be loaded by default when the product is loaded. In this case, we definitely want that.

#### Creating ExampleExtensionDefinition

You most likely noticed the new class `ExampleExtensionDefinition`, which we're going to create now. It will contain the actual string field that we wanted to add to the product.

Creating a new entity is not explained in this guide, so make sure you know [this guide](add-custom-complex-data) beforehand.

Our new entity will be located in the same directory as our extension. Let's first have a look at it before going into the explanation:

```php
// <plugin root>/src/Extension/Content/Product/ExampleExtensionDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Extension\Content\Product;

use Shopware\Core\Content\Product\ProductDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Field\FkField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\PrimaryKey;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
use Shopware\Core\Framework\DataAbstractionLayer\Field\IdField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\OneToOneAssociationField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\StringField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;

class ExampleExtensionDefinition extends EntityDefinition
{
    public const ENTITY_NAME = 'swag_example_extension';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    public function getEntityClass(): string
    {
        return ExampleExtensionEntity::class;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
            new FkField('product_id', 'productId', ProductDefinition::class),
            (new StringField('custom_string', 'customString')),

            new OneToOneAssociationField('product', 'product_id', 'id', ProductDefinition::class, false)
        ]);
    }
}
```

We've created a new entity definition called `ExampleExtensionDefinition`, as mentioned in the `CustomExtension` class. Its table name will be `swag_example_extension` and it will have a custom entity class called `ExampleExtensionEntity`, as you can see in the `getEntityClass` method. This will remain an example, creating the actual entity `ExampleExtensionEntity` is not part of this guide.

So let's have a look at the `defineFields` method. There's the default `IdField`, that almost every entity owns. The next field is the actual `product_id` column, which will be necessary in order to properly this entity with the product and vice versa. It has to be defined as `FkField` since that's what it is: a foreign key.

Now we're getting to the actual new data, in this example, this is just a new string field. It is called `customString` and can now be used in order to store new string data for the product in the database.

The last field is the inverse side of the `OneToOneAssociationField`. The first parameter defines the name of the property again, which will contain the `ProductEntity`. Now take a look at the second and third parameters. Those are the same as in the `ProductDefinition`, but the other way around. This order is important.

The fourth parameter is the class of the associated definition, the `ProductDefinition` in this case. The last parameter, once again, defines the autoloading. In this example, the product definition will **not** be loaded, when you're just trying to load this extension entity. Yet, the extension entity will always automatically be loaded when the product entity is loaded, just like we defined earlier.

Of course, this new definition also needs to be registered to the DI container:

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Extension\Content\Product\CustomExtension">
            <tag name="shopware.entity.extension"/>
        </service>

        <service id="Swag\BasicExample\Extension\Content\Product\ExampleExtensionDefinition">
            <tag name="shopware.entity.definition" entity="swag_example_extension" />
        </service>
    </services>
</container>
```

#### Adding the new database table

Of course, you have to add the new database table via a [Database migration](../../plugin-fundamentals/database-migrations). Look at the guide linked above to see how exactly this is done. Here's the example migration and how it could look like:

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Framework\Migration\MigrationStep;

class Migration1614903457ExampleExtension extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1614903457;
    }

    public function update(Connection $connection): void
    {
        $sql = <<<SQL
CREATE TABLE IF NOT EXISTS `swag_example_extension` (
    `id` BINARY(16) NOT NULL,
    `product_id` BINARY(16) NULL,
    `custom_string` VARCHAR(255) NULL,
    `created_at` DATETIME(3) NOT NULL,
    `updated_at` DATETIME(3) NULL,
    PRIMARY KEY (`id`),
    KEY `fk.swag_example_extension.product_id` (`product_id`),
    CONSTRAINT `fk.swag_example_extension.product_id` FOREIGN KEY (`product_id`) REFERENCES `product` (`id`) ON DELETE CASCADE ON UPDATE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
SQL;
        $connection->executeStatement($sql);
    }

    public function updateDestructive(Connection $connection): void
    {
    }
}
```

##### Foreign keys

The `AssociationFields` take care of loading the data, but it is recommended to add [foreign key constraints](https://dev.mysql.com/doc/refman/8.0/en/create-table-foreign-keys.html) to your migration query. This will ensure that your data is consistent (checks if the foreign key exists); for example, it will delete the `swag_example_extension` entry when the linked product is deleted.

#### Writing into the new field

As already mentioned, your new association is automatically loaded every time a product entity is loaded. This section will show you how to write to the new field instead.

As with every [write operation](writing-data), this is done via the product repository in this example.

```php
$this->productRepository->upsert([[
    'id' => '<your product ID here>',
    'exampleExtension' => [
        'customString' => 'foo bar'
    ]
]], $context);
```

In this case, you'd write "foo bar" to the product with your desired ID. Note the keys `exampleExtension`, as defined in the product extension class `CustomExtension`, and the key `customString`, which is the property name that you defined in the `ExampleExtensionDefinition` class.

### Adding a field without a database

We can use the DAL event which gets fired every time the product entity is loaded. You can find those kinds of events in the respective entities' event class. In this case, it is `Shopware\Core\Content\Product\ProductEvents`.

Below, you can find an example implementation where we add our extension when the product gets loaded.

```php
// <plugin root>/src/Subscriber/ProductSubscriber.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Subscriber;

use Shopware\Core\Content\Product\ProductEntity;
use Shopware\Core\Framework\Struct\ArrayEntity;
use Shopware\Core\Framework\DataAbstractionLayer\Event\EntityLoadedEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Shopware\Core\Content\Product\ProductEvents;

class ProductSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            ProductEvents::PRODUCT_LOADED_EVENT => 'onProductsLoaded'
        ];
    }

    public function onProductsLoaded(EntityLoadedEvent $event): void
    {
        /** @var ProductEntity $productEntity */
        foreach ($event->getEntities() as $productEntity) {
            $productEntity->addExtension('custom_string', new ArrayEntity(['foo' => 'bar']));
        }
    }
}
```

We're registering to the `ProductEvents::PRODUCT_LOADED_EVENT` event, which is fired every time one or multiple products are requested. In the event listener method `onProductsLoaded`, we're then adding our own data to the new field via the method `addExtension`.

Please note that its second parameter, the actual value, has to be a struct and not just a string or other kind of scalar value.

After we've created our subscriber, we have to adjust our `services.xml` to register it. Below you can find our `services.xml`.

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Subscriber\ProductSubscriber">
            <tag name="kernel.event_subscriber"/>
        </service>
    </services>
</container>
```

## Entity extension vs. Custom fields

[Custom fields](../custom-field/add-custom-field) are by default configurable by the admin user in the Administration, and they mostly support scalar types, e.g. a text-field, a number field, or the likes. If you'd like to create associations between entities, you'll need to use an entity extension, just like we did here. Of course, you can also add scalar values without an association to an entity via an extension.

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/framework/data-handling/add-complex-data-to-existing-entities.md
---

# Adding Complex Data to Existing Entities

## Overview

Sometimes you want to extend existing entities with some custom information. Extensions are technical and not configurable by the admin user. Also, they can deal with more complex types than scalar ones.

## Prerequisites

To create your own entity extension for your plugin, you first need a plugin as base. Please refer to the [Plugin Base Guide](../../plugin-base-guide).

Basic knowledge of [creating a custom entity](add-custom-complex-data) and [adding associations](add-data-associations) will also be helpful for this guide.

## Creating the extension

In this example, we're going to add a new string field to the `product` entity.

You can choose whether you want to save the new string field to the database or not. Therefore, you're going to see two sections, one for each way.

For both cases, you need to create a new "extension" class in the directory `<plugin root>/src/Extension/`. In this case, we want to extend the `product` entity, so we create a subdirectory `Content/Product/` since the entity location in the Core is the same. Our class needs to extend from the abstract `Shopware\Core\Framework\DataAbstractionLayer\EntityExtension` class, which forces you to implement the `getDefinitionClass` method. It has to point to the entity definition you want to extend, so `ProductDefinition` in this case.

You add new fields by overriding the method `extendFields` and add your new fields in there.

Here's an example class called `CustomExtension`:

```php
// <plugin root>/src/Extension/Content/Product/CustomExtension.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Extension\Content\Product;

use Shopware\Core\Content\Product\ProductDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\EntityExtension;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;

class CustomExtension extends EntityExtension
{
    public function extendFields(FieldCollection $collection): void
    {
        $collection->add(
            // new fields here
        );
    }

    public function getDefinitionClass(): string
    {
        return ProductDefinition::class;
    }
}
```

Now we have to register our extension via the DI-container. If you don't know how that's done in general, head over to our guide about registering a custom service [Add a custom class / service](../../plugin-fundamentals/add-custom-service) or our guide about the [dependency injection](../../plugin-fundamentals/dependency-injection).

Here's our `services.xml`:

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Extension\Content\Product\CustomExtension">
            <tag name="shopware.entity.extension"/>
        </service>
    </services>
</container>
```

### Adding a field with a database

In this guide, you're extending the product entity in order to add a new string field to it. Since you must not extend the `product` table with a new column, you'll have to add a new table which contains the new data for the product. This new table will then be associated using a [OneToOne association](add-data-associations#One%20to%20One%20associations).

Let's start with the `CustomExtension` class by adding a new field in the `extendFields` method.

```php
// <plugin root>/src/Extension/Content/Product/CustomExtension.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Extension\Content\Product;
use Shopware\Core\Content\Product\ProductDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\EntityExtension;
use Shopware\Core\Framework\DataAbstractionLayer\Field\OneToOneAssociationField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;

class CustomExtension extends EntityExtension
{
    public function extendFields(FieldCollection $collection): void
    {
        $collection->add(
            new OneToOneAssociationField('exampleExtension', 'id', 'product_id', ExampleExtensionDefinition::class, true)
        );
    }

    public function getDefinitionClass(): string
    {
        return ProductDefinition::class;
    }
}
```

As you can see, we're adding a new `OneToOneAssociationField`. Its parameters are the following, in correct order:

* `propertyName`: The name of the property which should contain the associated entity of type `ExampleExtensionDefinition` in the `ProductDefinition`. Property names are usually camelCase, with the first character being lower cased.
* `storageName`: Use the `id` column here, which refers to the `id` field of your product. This will be used for the connection to your association. Storage names are always lowercase and snake\_cased.
* `referenceField`: In the `storageName` you defined one of the two connected columns, `id`. The name of the other column in the database, which you want to connect via this association, belongs into this parameter. In that case, it will be a column called `product_id`, which we will define in the `ExampleExtensionDefinition`.
* `referenceClass`: The class name of the definition that we want to connect via the association.
* `autoload`: As the name suggests, this parameter defines if this association should always be loaded by default when the product is loaded. In this case, we definitely want that.

#### Creating ExampleExtensionDefinition

You most likely noticed the new class `ExampleExtensionDefinition`, which we're going to create now. It will contain the actual string field that we wanted to add to the product.

Creating a new entity is not explained in this guide, so make sure you know [this guide](add-custom-complex-data) beforehand.

Our new entity will be located in the same directory as our extension. Let's first have a look at it before going into the explanation:

```php
// <plugin root>/src/Extension/Content/Product/ExampleExtensionDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Extension\Content\Product;

use Shopware\Core\Content\Product\ProductDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Field\FkField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\PrimaryKey;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
use Shopware\Core\Framework\DataAbstractionLayer\Field\IdField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\OneToOneAssociationField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\StringField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;

class ExampleExtensionDefinition extends EntityDefinition
{
    public const ENTITY_NAME = 'swag_example_extension';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    public function getEntityClass(): string
    {
        return ExampleExtensionEntity::class;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
            new FkField('product_id', 'productId', ProductDefinition::class),
            (new StringField('custom_string', 'customString')),
            // ReferenceVersionField only needed on versioned entities
            new ReferenceVersionField(ProductDefinition::class, 'product_version_id'),
            new OneToOneAssociationField('product', 'product_id', 'id', ProductDefinition::class, false)
        ]);
    }
}
```

We've created a new entity definition called `ExampleExtensionDefinition`, as mentioned in the `CustomExtension` class. Its table name will be `swag_example_extension` and it will have a custom entity class called `ExampleExtensionEntity`, as you can see in the `getEntityClass` method. This will remain an example, creating the actual entity `ExampleExtensionEntity` is not part of this guide.

So let's have a look at the `defineFields` method. There's the default `IdField`, that almost every entity owns. The next field is the actual `product_id` column, which will be necessary in order to properly this entity with the product and vice versa. It has to be defined as `FkField` since that's what it is: a foreign key.

Now we're getting to the actual new data, in this example, this is just a new string field. It is called `customString` and can now be used in order to store new string data for the product in the database.

The last field is the inverse side of the `OneToOneAssociationField`. The first parameter defines the name of the property again, which will contain the `ProductEntity`. Now take a look at the second and third parameters. Those are the same as in the `ProductDefinition`, but the other way around. This order is important.

The fourth parameter is the class of the associated definition, the `ProductDefinition` in this case. The last parameter, once again, defines the autoloading. In this example, the product definition will **not** be loaded, when you're just trying to load this extension entity. Yet, the extension entity will always automatically be loaded when the product entity is loaded, just like we defined earlier.

Of course, this new definition also needs to be registered to the DI container:

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Extension\Content\Product\CustomExtension">
            <tag name="shopware.entity.extension"/>
        </service>

        <service id="Swag\BasicExample\Extension\Content\Product\ExampleExtensionDefinition">
            <tag name="shopware.entity.definition" entity="swag_example_extension" />
        </service>
    </services>
</container>
```

#### Adding the new database table

Of course, you have to add the new database table via a [Database migration](../../plugin-fundamentals/database-migrations). Look at the guide linked above to see how exactly this is done. Here's the example migration and how it could look like:

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Framework\Migration\MigrationStep;

class Migration1614903457ExampleExtension extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1614903457;
    }

    public function update(Connection $connection): void
    {
    // product_version_id only needed when extending a versioned entity
        $sql = <<<SQL
CREATE TABLE IF NOT EXISTS `swag_example_extension` (
    `id` BINARY(16) NOT NULL,
    `product_id` BINARY(16) NULL,
    `product_version_id` BINARY(16) NOT NULL,
    `custom_string` VARCHAR(255) NULL,
    `created_at` DATETIME(3) NOT NULL,
    `updated_at` DATETIME(3) NULL,
    PRIMARY KEY (`id`),
    CONSTRAINT `unique.swag_example_extension.product` UNIQUE (`product_id`, `product_version_id`),
    CONSTRAINT `fk.swag_example_extension.product_id` FOREIGN KEY (`product_id`, `product_version_id`) REFERENCES `product` (`id`, `version_id`) ON DELETE CASCADE ON UPDATE CASCADE
) ENGINE=InnoDB DEFAULT CHARSET=utf8mb4 COLLATE=utf8mb4_unicode_ci;
SQL;
        $connection->executeStatement($sql);
    }

    public function updateDestructive(Connection $connection): void
    {
    }
}
```

##### Foreign keys

The `AssociationFields` take care of loading the data, but it is recommended to add [foreign key constraints](https://dev.mysql.com/doc/refman/8.0/en/create-table-foreign-keys.html) to your migration query. This will ensure that your data is consistent (checks if the foreign key exists); for example, it will delete the `swag_example_extension` entry when the linked product is deleted.

#### Writing into the new field

As already mentioned, your new association is automatically loaded every time a product entity is loaded. This section will show you how to write to the new field instead.

As with every [write operation](writing-data), this is done via the product repository in this example.

```php
$this->productRepository->upsert([[
    'id' => '<your product ID here>',
    'exampleExtension' => [
        'customString' => 'foo bar'
    ]
]], $context);
```

In this case, you'd write "foo bar" to the product with your desired ID. Note the keys `exampleExtension`, as defined in the product extension class `CustomExtension`, and the key `customString`, which is the property name that you defined in the `ExampleExtensionDefinition` class.

### Adding a field without a database

We can use the DAL event which gets fired every time the product entity is loaded. You can find those kinds of events in the respective entities' event class. In this case, it is `Shopware\Core\Content\Product\ProductEvents`.

Below, you can find an example implementation where we add our extension when the product gets loaded.

```php
// <plugin root>/src/Subscriber/ProductSubscriber.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Subscriber;

use Shopware\Core\Content\Product\ProductEntity;
use Shopware\Core\Framework\Struct\ArrayEntity;
use Shopware\Core\Framework\DataAbstractionLayer\Event\EntityLoadedEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Shopware\Core\Content\Product\ProductEvents;

class ProductSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            ProductEvents::PRODUCT_LOADED_EVENT => 'onProductsLoaded'
        ];
    }

    public function onProductsLoaded(EntityLoadedEvent $event): void
    {
        /** @var ProductEntity $productEntity */
        foreach ($event->getEntities() as $productEntity) {
            $productEntity->addExtension('custom_string', new ArrayEntity(['foo' => 'bar']));
        }
    }
}
```

We're registering to the `ProductEvents::PRODUCT_LOADED_EVENT` event, which is fired every time one or multiple products are requested. In the event listener method `onProductsLoaded`, we're then adding our own data to the new field via the method `addExtension`.

Please note that its second parameter, the actual value, has to be a struct and not just a string or other kind of scalar value.

After we've created our subscriber, we have to adjust our `services.xml` to register it. Below you can find our `services.xml`.

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Subscriber\ProductSubscriber">
            <tag name="kernel.event_subscriber"/>
        </service>
    </services>
</container>
```

## Entity extension vs. Custom fields

[Custom fields](../custom-field/add-custom-field) are by default configurable by the admin user in the Administration, and they mostly support scalar types, e.g. a text-field, a number field, or the likes. If you'd like to create associations between entities, you'll need to use an entity extension, just like we did here. Of course, you can also add scalar values without an association to an entity via an extension.

## Bulk entity extensions

::: info
This feature is available since Shopware 6.6.10.0
:::

In case your project or plugin requires many entity extensions, you can register a `BulkEntityExtension` which allows extending multiple entities at once:

```php
<?php

namespace Examples;

use Shopware\Core\Content\Product\ProductDefinition;
use Shopware\Core\Content\Category\CategoryDefinition;

class MyBulkExtension extends BulkEntityExtension
{
    public function collect(): \Generator
    {
        yield ProductDefinition::ENTITY_NAME => [
            new FkField('main_category_id', 'mainCategoryId', CategoryDefinition::class),
        ];

        yield CategoryDefinition::ENTITY_NAME => [
            new FkField('product_id', 'productId', ProductDefinition::class),
            new ManyToOneAssociationField('product', 'product_id', ProductDefinition::class),
        ];
    }
}
```

Each yield defines the entity name which should be extended and the array value defines the fields which should be added. In this example, the `product` and `category` entities are extended.

You must also register the extension in your `services.xml` file and tag it with `shopware.bulk.entity.extension`.

```xml
<service id="Examples\MyBulkExtension">
   <tag name="shopware.bulk.entity.extension"/>
</service>
```

---

---
url: /docs/guides/plugins/plugins/dependencies/using-composer-dependencies.md
---

# Adding Composer Dependencies

Use this guide when your extension needs another PHP package — for example, a library for exports, PDF generation, or an external API client. Like any PHP project, Shopware plugins declare such packages in their `composer.json` via the `require` section.

## Overview

How the dependency gets installed depends on how your plugin is set up:

* **Static plugins or Composer-managed plugins (recommended):** The project's root Composer installation resolves and installs your plugin's dependencies automatically. No extra steps are needed — this is one of the main reasons the [static plugin approach](../plugin-base-guide.md) is recommended.
* **Zip-installed plugins (e.g., distributed via the Shopware Store):** The dependencies are not resolved by the project. You must either let Shopware run Composer during installation by overriding `executeComposerCommands()`, or bundle the packages with your plugin. Both options are described below.

## Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files and a running plugin. Of course you'll have to understand PHP, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation.

## Adding a Composer package to the `composer.json` file

As an example, in this guide we will install [`exporter`](https://github.com/sebastianbergmann/exporter), a package that provides the functionality to export PHP variables for visualization.

Before installing, temporarily remove the `shopware/core` entry from the `require` section of your plugin's `composer.json`. Otherwise, Composer would download Shopware itself into your plugin's `vendor` directory.

Now run the following command in your plugin directory:

```bash
composer require sebastian/exporter
```

This adds the package to the `require` section of your plugin's `composer.json` and installs it. Afterwards, add the `shopware/core` requirement back in.

::: warning
The `vendor` directory, where the Composer saves the dependencies, has to be included in the plugin bundle. The plugin bundle size is not allowed to exceed 5 MB.
:::

## Executing composer commands during plugin installation

In order that the additional package our plugin requires are installed as well when our plugin is installed, shopware need to execute composer commands to do so.
Therefore, we need to overwrite the `executeComposerCommands` method in our plugin base class and return true.

```php
// <plugin root>/src/SwagBasicExample.php
<?php declare(strict_types=1);

namespace Swag\BasicExample;

use Shopware\Core\Framework\Plugin;

class SwagBasicExample extends Plugin
{
    public function executeComposerCommands(): bool
    {
        return true;
    }

}
```

## Using the Composer plugin

PHP doesn't require a build system, which means that we can just add `use` statements and then use the Composer dependency directly.

The following code sample imports `SebastianBergmann\Exporter\Exporter` and logs `hello, world!` to the Symfony profiler logs whenever the `NavigationPageLoadedEvent` is fired. Learn how to [register this listener](../framework/event/listening-to-events.md).

```php
// <plugin root>/src/SwagBasicExample.php
<?php
namespace SwagBasicExample\Subscriber;

use Shopware\Core\Framework\DataAbstractionLayer\Event\EntityLoadedEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Shopware\Storefront\Page\Navigation\NavigationPageLoadedEvent;

use Psr\Log\LoggerInterface;
use SebastianBergmann\Exporter\Exporter;

class MySubscriber implements EventSubscriberInterface
{
     private LoggerInterface $logger;

    public function __construct(
        LoggerInterface $logger
    ) {
        $this->logger = $logger;
    }

    public static function getSubscribedEvents(): array
    {
        // Return the events to listen to as array like this:  <event to listen to> => <method to execute>
        return [
            NavigationPageLoadedEvent::class => 'onNavigationPage'
        ];
    }

    public function onNavigationPage(NavigationPageLoadedEvent $event)
    {
        $exporter = new Exporter;
        $this->logger->info($exporter->export('hello, world!'));
    }
}
```

## Adding private Composer dependencies

You can bundle Composer dependencies with your plugin by adding them to the `/packages/` folder of your plugin.

Example structure:

```text
SwagBasicExample
├── packages
│   └── my-private-dependency/
│       ├── composer.json
│       └── src/
│           └── SomeCoolService.php
├── src/
│   └── SwagBasicExample.php
└── composer.json
```

You can then require them like other dependencies:

```text
"require": {
    "my-vendor-name/my-private-dependency": "^1.2.3",
}
```

## More interesting topics

* [Using NPM dependencies](using-npm-dependencies.md)
* [Adding plugin dependencies](add-plugin-dependencies.md)

---

---
url: >-
  /docs/v6.5/guides/plugins/plugins/plugin-fundamentals/using-composer-dependencies.md
---

# Adding Composer Dependencies

In this guide you'll learn how to add Composer dependencies to your project.

## Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files and a running plugin. Of course you'll have to understand PHP, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation. Further a basic understanding of Node and NPM is required.

## Adding a Composer plugin to the `composer.json` file

In this guide we will install [`exporter`](https://github.com/sebastianbergmann/exporter), which provides the functionality to export PHP variables for visualization.

Now we can simply install the `exporter` package by adding `"sebastian/exporter": "*"` to the list in `require` section of the `composer.json` of our plugin.

Now we can simply install `exporter` by running `composer require sebastian/exporter` in your plugin directory.

After that we have to add our dependency to shopware back in.

::: warning
The `vendor` directory, where the Composer saves the dependencies, has to be included in the plugin bundle. The plugin bundle size is not allowed to exceed 5 MB.
:::

## Executing composer commands during plugin installation

In order that the additional package our plugin requires are installed as well when our plugin is installed, shopware need to execute composer commands to do so.
Therefore, we need to overwrite the `executeComposerCommands` method in our plugin base class and return true.

```php
// <plugin root>/src/SwagBasicExample.php
<?php declare(strict_types=1);

namespace Swag\BasicExample;

use Shopware\Core\Framework\Plugin;

class SwagBasicExample extends Plugin
{
    public function executeComposerCommands(): bool
    {
        return true;
    }

}
```

## Using the Composer plugin

PHP doesn't require a build system, which means that we can just add `use` statements and then use the Composer dependency directly.

The following code sample imports `SebastianBergmann\Exporter\Exporter` and logs `hello, world!` to the Symfony profiler logs whenever the `NavigationPageLoadedEvent` is fired. Learn how to [register this listener](listening-to-events).

```php
// <plugin root>/src/SwagBasicExample.php
<?php
namespace SwagBasicExample\Subscriber;

use Shopware\Core\Framework\DataAbstractionLayer\Event\EntityLoadedEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Shopware\Storefront\Page\Navigation\NavigationPageLoadedEvent;

use Psr\Log\LoggerInterface;
use SebastianBergmann\Exporter\Exporter;

class MySubscriber implements EventSubscriberInterface
{
     private LoggerInterface $logger;

    public function __construct(
        LoggerInterface $logger
    ) {
        $this->logger = $logger;
    }

    public static function getSubscribedEvents(): array
    {
        // Return the events to listen to as array like this:  <event to listen to> => <method to execute>
        return [
            NavigationPageLoadedEvent::class => 'onNavigationPage'
        ];
    }

    public function onNavigationPage(NavigationPageLoadedEvent $event)
    {
        $exporter = new Exporter;
        $this->logger->info($exporter->export('hello, world!'));
    }
}
```

## Adding private Composer dependencies

You can bundle Composer dependencies with your plugin by adding them to the `/packages/` folder of your plugin.

Example structure:

```text
SwagBasicExample
├── packages
│   └── my-private-dependency/
│       ├── composer.json
│       └── src/
│           └── SomeCoolService.php
├── src/
│   └── SwagBasicExample.php
└── composer.json
```

You can then require them like other dependencies:

```text
"require": {
    "my-vendor-name/my-private-dependency": "^1.2.3",
}
```

## More interesting topics

* [Using NPM dependencies](using-npm-dependencies)
* [Adding plugin dependencies](add-plugin-dependencies)

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/plugin-fundamentals/using-composer-dependencies.md
---

# Adding Composer Dependencies

In this guide you'll learn how to add Composer dependencies to your project.

## Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files and a running plugin. Of course you'll have to understand PHP, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation. Further a basic understanding of Node and NPM is required.

## Adding a Composer plugin to the `composer.json` file

In this guide we will install [`exporter`](https://github.com/sebastianbergmann/exporter), which provides the functionality to export PHP variables for visualization.

Now we can simply install the `exporter` package by adding `"sebastian/exporter": "*"` to the list in `require` section of the `composer.json` of our plugin.

Now we can simply install `exporter` by running `composer require sebastian/exporter` in your plugin directory.

After that we have to add our dependency to shopware back in.

::: warning
The `vendor` directory, where the Composer saves the dependencies, has to be included in the plugin bundle. The plugin bundle size is not allowed to exceed 5 MB.
:::

## Executing composer commands during plugin installation

In order that the additional package our plugin requires are installed as well when our plugin is installed, shopware need to execute composer commands to do so.
Therefore, we need to overwrite the `executeComposerCommands` method in our plugin base class and return true.

```php
// <plugin root>/src/SwagBasicExample.php
<?php declare(strict_types=1);

namespace Swag\BasicExample;

use Shopware\Core\Framework\Plugin;

class SwagBasicExample extends Plugin
{
    public function executeComposerCommands(): bool
    {
        return true;
    }

}
```

## Using the Composer plugin

PHP doesn't require a build system, which means that we can just add `use` statements and then use the Composer dependency directly.

The following code sample imports `SebastianBergmann\Exporter\Exporter` and logs `hello, world!` to the Symfony profiler logs whenever the `NavigationPageLoadedEvent` is fired. Learn how to [register this listener](listening-to-events).

```php
// <plugin root>/src/SwagBasicExample.php
<?php
namespace SwagBasicExample\Subscriber;

use Shopware\Core\Framework\DataAbstractionLayer\Event\EntityLoadedEvent;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;
use Shopware\Storefront\Page\Navigation\NavigationPageLoadedEvent;

use Psr\Log\LoggerInterface;
use SebastianBergmann\Exporter\Exporter;

class MySubscriber implements EventSubscriberInterface
{
     private LoggerInterface $logger;

    public function __construct(
        LoggerInterface $logger
    ) {
        $this->logger = $logger;
    }

    public static function getSubscribedEvents(): array
    {
        // Return the events to listen to as array like this:  <event to listen to> => <method to execute>
        return [
            NavigationPageLoadedEvent::class => 'onNavigationPage'
        ];
    }

    public function onNavigationPage(NavigationPageLoadedEvent $event)
    {
        $exporter = new Exporter;
        $this->logger->info($exporter->export('hello, world!'));
    }
}
```

## Adding private Composer dependencies

You can bundle Composer dependencies with your plugin by adding them to the `/packages/` folder of your plugin.

Example structure:

```text
SwagBasicExample
├── packages
│   └── my-private-dependency/
│       ├── composer.json
│       └── src/
│           └── SomeCoolService.php
├── src/
│   └── SwagBasicExample.php
└── composer.json
```

You can then require them like other dependencies:

```text
"require": {
    "my-vendor-name/my-private-dependency": "^1.2.3",
}
```

## More interesting topics

* [Using NPM dependencies](using-npm-dependencies)
* [Adding plugin dependencies](add-plugin-dependencies)

---

---
url: >-
  /docs/guides/plugins/plugins/framework/data-handling/add-custom-complex-data.md
---

# Adding Custom Complex Data

## Overview

Plugins often need to save data into a custom database table. Shopware 6's data abstraction layer (DAL) fully supports custom entities, so you don't have to take care of the data handling at all.

## Prerequisites

This guide builds upon the [Plugin base guide](../../../plugins/plugin-base-guide.md), but any plugin will work here. Just note that all examples reference that plugin.

Before creating a custom DAL entity you'll need to create a database table, which requires an understanding of [plugin migrations](../../database/database-migrations.md). Familiarity with [Dependency injection](../../services/dependency-injection.md) is also required, because the entity definition is registered as a service.

## Creating the database table

We'll start with creating a new database table. Make sure to always add your individual prefix to your plugin's database tables, e.g. your manufacturer name.

In this guide we'll name our table `swag_example`, you'll find this name a few more times in here, so make sure to remember that one.

As already mentioned in the prerequisites, creating a database table is done via [plugin migrations](../../database/database-migrations.md) - use the guide to understand how this example works.

```php
// <plugin root>/src/Migration/Migration1611664789Example.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Framework\Migration\MigrationStep;

class Migration1611664789Example extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1611664789;
    }

    public function update(Connection $connection): void
    {
        $sql = <<<SQL
CREATE TABLE IF NOT EXISTS `swag_example` (
    `id` BINARY(16) NOT NULL,
    `name` VARCHAR(255) COLLATE utf8mb4_unicode_ci,
    `description` VARCHAR(255) COLLATE utf8mb4_unicode_ci,
    `active` TINYINT(1) COLLATE utf8mb4_unicode_ci,
    `created_at` DATETIME(3) NOT NULL,
    `updated_at` DATETIME(3),
    PRIMARY KEY (`id`)
)
    ENGINE = InnoDB
    DEFAULT CHARSET = utf8mb4
    COLLATE = utf8mb4_unicode_ci;
SQL;
        $connection->executeStatement($sql);
    }
}
```

After reinstalling your plugin, you should see your new database table `swag_example`.

## Creating an entity

### EntityDefinition class

Introducing the table to Shopware 6 is done by adding a so called `EntityDefinition` for your table. As the name suggests, it defines your own entity, including its fields and name, the latter also represents the table name and therefore has to perfectly match.

Your custom entity definition should be placed inside a folder named after the domain it handles, e.g. "Checkout" if you were to include a Checkout entity. Thus, a good location for this example could be in a directory like `<plugin root>/src/Core/Content/Example`. This will also be the case for the `Entity` class itself, as well as the `EntityCollection` class, but those are explained later in this guide.

Start of with creating a new file named `ExampleDefinition.php` in the directory `<plugin root>/src/Core/Content/Example/ExampleDefinition.php`. Below you can see our example definition, which is explained afterwards:

```php
// <plugin root>/src/Core/Content/Example/ExampleDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example;

use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;

class ExampleDefinition extends EntityDefinition
{
    public const ENTITY_NAME = 'swag_example';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([]);
    }
}
```

First of all, your own definition has to extend from the class `Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition`, which enforces you to implement two methods: `getEntityName` and `defineFields`.

The method `getEntityName` returns a string equal to your table name. In this example it is `swag_example`. Keep in mind, that the return of your `getEntityName` method will be used for two cases:

* The database table name
* The repository name in the DI container (`<the-name>.repository`)

The method `defineFields` contains all the fields, that your entity or table consists of.

As you can see in your migration, your table consists of the following fields: You've got an `id` field, a `name` field, a `description` and an `active` field. Other than that, the other two columns `created_at` and `updated_at` don't have to be defined in your definition, since they're included by default. You're asked to return a `Shopware\Core\Framework\DataAbstractionLayer\FieldCollection` instance here, which then has to contain an array of your fields. There's several field classes, e.g. an `Shopware\Core\Framework\DataAbstractionLayer\Field\IdField` or a `Shopware\Core\Framework\DataAbstractionLayer\Field\StringField`, which you have to create and pass into the `FieldCollection`, so let's do that.

```php
// <plugin root>/src/Core/Content/Example/ExampleDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example;

use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;
use Shopware\Core\Framework\DataAbstractionLayer\Field\BoolField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\PrimaryKey;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
use Shopware\Core\Framework\DataAbstractionLayer\Field\IdField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\StringField;

class ExampleDefinition extends EntityDefinition
{
    public const ENTITY_NAME = 'swag_example';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
            (new StringField('name', 'name')),
            (new StringField('description', 'description')),
            (new BoolField('active', 'active'))
        ]);
    }
}
```

As you can see, we've implemented an `IdField` for the `id` column, a `StringField` for the `name` and the `description`, as well as a `BoolField` for the `active` column. Most `Field` classes ask for two parameters, such as the `IdField`:

* A storage name, which represents the name of the field in the storage, e.g. the column in an SQL database.
* A property name, which defines how you can access this field later on. Make sure to remember those for the next step.

The `storageName` is written in snake\_case, while the `propertyName` must be written in lowerCamelCase.

Another thing to note is the `addFlags` call on the `IdField`. Those flags are like attributes to fields, such a required field being marked by using the `Required` flag.

If you want to know more about the flags and how to use them, head over to our guide on how to use flags [Using flags](using-flags).

All that's left to do now, is to introduce your `ExampleDefinition` to Shopware by registering your class in your `services.php` file and by using the `shopware.entity.definition` tag, because Shopware is looking for definitions this way. If your plugin does not have a `services.php` file yet or you don't know how that's done, head over to our guide about registering a custom service [Add a custom class / service](../../services/add-custom-service.md), or our guide about the [Dependency injection](../../services/dependency-injection.md).

Here's the `services.php` as it should look like:

```php
<?php declare(strict_types=1);

use Swag\BasicExample\Core\Content\Example\ExampleDefinition;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(ExampleDefinition::class)
        ->tag('shopware.entity.definition', ['entity' => 'swag_example']);
};
```

Please note the tag for your definition and the respective `entity` attribute, which has to contain the technical name of your entity, which you provided in your entity definition. In this case this must be `swag_example`.

And basically that's it already for your definition class. Theoretically you could start using your entity now by injecting the `swag_example.repository` service to other services and start working with the repository, e.g. to [read data](reading-data) or to [write data](writing-data).

Yet, we highly recommend you to create a custom `Entity` class, as well as a custom `EntityCollection` class. This is not mandatory, but those will be replaced with generic classes otherwise.

### Entity class

The entity class itself is a simple key-value object, like a struct, which contains as many properties as fields in the definition, ignoring the ID field, which is handled by the `EntityIdTrait`.

::: warning
The properties of your entity class have to be at least `protected`, otherwise the data abstraction layer won't be able to set the values.
For the same reason `readonly` properties are not allowed. This holds true not just for `Entity` classes, but for all classes that extend the generic `Struct` class.
:::

```php
// <plugin root>/src/Core/Content/Example/ExampleEntity.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example;

use Shopware\Core\Framework\DataAbstractionLayer\Entity;
use Shopware\Core\Framework\DataAbstractionLayer\EntityIdTrait;

class ExampleEntity extends Entity
{
    use EntityIdTrait;

    protected ?string $name;

    protected ?string $description;

    protected bool $active;

    public function getName(): ?string
    {
        return $this->name;
    }

    public function setName(?string $name): void
    {
        $this->name = $name;
    }

    public function getDescription(): ?string
    {
        return $this->description;
    }

    public function setDescription(?string $description): void
    {
        $this->description = $description;
    }

    public function isActive(): bool
    {
        return $this->active;
    }

    public function setActive(bool $active): void
    {
        $this->active = $active;
    }
}
```

As you can see, it only holds the properties and its respective getters and setters, for the fields mentioned in the `EntityDefinition` class.

Now you need your definition to know its custom entity class. This is done by overriding the method `getEntityClass` in your `ExampleDefinition`.

```php
// <plugin root>/src/Core/Content/Example/ExampleDefinition.php
class ExampleDefinition extends EntityDefinition
{
    [...]

    public function getEntityClass(): string
    {
        return ExampleEntity::class;
    }
}
```

That's it. Instead of generic `ArrayEntity` instances, you'll get `ExampleEntity` class instances now if you were to read your data using the repository.

### EntityCollection

Just like the `Entity` class, you do want to create your own `EntityCollection` class.

So create a `ExampleCollection` class in the same directory as your `ExampleDefinition` and `ExampleEntity`. Extending from `Shopware\Core\Framework\DataAbstractionLayer\EntityCollection`, it comes with a method called `getExpectedClass`, which once again returns the fully qualified class name of the `Entity` class to be used. Go ahead and override this method and return your `ExampleEntity` here. Additionally, you can provide helper methods in your custom `EntityCollection`, such as filtering the result set by certain conditions, but that's up to you.

This is how your collection class could then look like:

```php
// <plugin root>/src/Core/Content/Example/ExampleCollection.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example;

use Shopware\Core\Framework\DataAbstractionLayer\EntityCollection;

/**
 * @extends EntityCollection<ExampleEntity>
 */
class ExampleCollection extends EntityCollection
{
    protected function getExpectedClass(): string
    {
        return ExampleEntity::class;
    }
}
```

The class documentation is just another helper to have a proper auto-completion when working with your `ExampleCollection`.

Now it's time to introduce your custom collection to your `ExampleDefinition` again. This is done by overriding its `getCollectionClass` method.

```php
// <plugin root>/src/Core/Content/Example/ExampleDefinition.php
class ExampleDefinition extends EntityDefinition
{
    [...]

    public function getCollectionClass(): string
    {
        return ExampleCollection::class;
    }
}
```

That's it, your definition is now completely registered to Shopware 6! From here on your custom entity is accessible throughout the API and you can fully use it for CRUD operations with its repository.

## Next steps

You've now got a simple entity about a single database table. However, your entity will most likely be even more complex.

For example we also have a guide about [Associations](add-data-associations), since you most likely will have multiple tables that have a relation to each other. Furthermore, the fields in this example are already [Using flags](using-flags). When dealing with products, you are also dealing with [Inheritance](field-inheritance), which we also got covered.

Learn how to connect your database table to an already existing database table/entity from the [Adding Complex Data to Existing Entities guide](add-complex-data-to-existing-entities).

---

---
url: >-
  /docs/v6.5/guides/plugins/plugins/framework/data-handling/add-custom-complex-data.md
---

# Adding Custom Complex Data

## Overview

Quite often, your plugin has to save data into a custom database table. Shopware 6's data abstraction layer fully supports custom entities, so you don't have to take care of the data handling at all.

## Prerequisites

This guide is built upon the [Plugin base guide](../../plugin-base-guide), but any plugin will work here. Just note that all examples are using the plugin mentioned above. In order to create a database table, you need to understand plugin migrations [Plugin migrations](../../plugin-fundamentals/database-migrations). Also, you'll have to understand how the [Dependency injection](../../plugin-fundamentals/dependency-injection) works as well.

::: info
Refer to this video on **[Creating a custom entity](https://www.youtube.com/watch?v=mTHTyof4gPk)**. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

## Creating the database table

We'll start with creating a new database table. Make sure to always add your individual prefix to your plugin's database tables, e.g. your manufacturer name.

In this guide we'll name our table `swag_example`, you'll find this name a few more times in here, so make sure to remember that one.

As already mentioned in the prerequisites, creating a database table is done via plugin migrations [Plugin migrations](../../plugin-fundamentals/database-migrations), head over to this guide to understand how this example works.

```php
// <plugin root>/src/Migration/Migration1611664789Example.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Framework\Migration\MigrationStep;

class Migration1611664789Example extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1611664789;
    }

    public function update(Connection $connection): void
    {
        $sql = <<<SQL
CREATE TABLE IF NOT EXISTS `swag_example` (
    `id` BINARY(16) NOT NULL,
    `name` VARCHAR(255) COLLATE utf8mb4_unicode_ci,
    `description` VARCHAR(255) COLLATE utf8mb4_unicode_ci,
    `active` TINYINT(1) COLLATE utf8mb4_unicode_ci,
    `created_at` DATETIME(3) NOT NULL,
    `updated_at` DATETIME(3),
    PRIMARY KEY (`id`)
)
    ENGINE = InnoDB
    DEFAULT CHARSET = utf8mb4
    COLLATE = utf8mb4_unicode_ci;
SQL;
        $connection->executeStatement($sql);
    }

    public function updateDestructive(Connection $connection): void
    {
    }
}
```

After reinstalling your plugin, you should see your new database table `swag_example`.

## Creating an entity

### EntityDefinition class

Introducing the table to Shopware 6 is done by adding a so called `EntityDefinition` for your table. As the name suggests, it defines your own entity, including its fields and name, the latter also represents the table name and therefore has to perfectly match.

Your custom entity definition should be placed inside a folder named after the domain it handles, e.g. "Checkout" if you were to include a Checkout entity. Thus, a good location for this example could be in a directory like this: `<plugin root>/src/Core/Content/Example`\
This will also be the case for the `Entity` class itself, as well as the `EntityCollection` class, but those are explained later in this guide.

Start of with creating a new file named `ExampleDefinition.php` in the directory `<plugin root>/src/Core/Content/Example/ExampleDefinition.php`. Below you can see our example definition, which is explained afterwards:

```php
// <plugin root>/src/Core/Content/Example/ExampleDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example;

use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;

class ExampleDefinition extends EntityDefinition
{
    public const ENTITY_NAME = 'swag_example';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([]);
    }
}
```

First of all, your own definition has to extend from the class `Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition`, which enforces you to implement two methods: `getEntityName` and `defineFields`.

The method `getEntityName` returns a string equal to your table name. In this example it is `swag_example`. Keep in mind, that the return of your `getEntityName` method will be used for two cases:

* The database table name
* The repository name in the DI container (`<the-name>.repository`)

The method `defineFields` contains all the fields, that your entity or table consists of.

As you can see in your migration, your table consists of the following fields: You've got an `id` field, a `name` field, a `description` and an `active` field. Other than that, the other two columns `created_at` and `updated_at` don't have to be defined in your definition, since they're included by default. You're asked to return a `Shopware\Core\Framework\DataAbstractionLayer\FieldCollection` instance here, which then has to contain an array of your fields. There's several field classes, e.g. an `Shopware\Core\Framework\DataAbstractionLayer\Field\IdField` or a `Shopware\Core\Framework\DataAbstractionLayer\Field\StringField`, which you have to create and pass into the `FieldCollection`, so let's do that.

```php
// <plugin root>/src/Core/Content/Example/ExampleDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example;

use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;
use Shopware\Core\Framework\DataAbstractionLayer\Field\BoolField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\PrimaryKey;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
use Shopware\Core\Framework\DataAbstractionLayer\Field\IdField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\StringField;

class ExampleDefinition extends EntityDefinition
{
    public const ENTITY_NAME = 'swag_example';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
            (new StringField('name', 'name')),
            (new StringField('description', 'description')),
            (new BoolField('active', 'active'))
        ]);
    }
}
```

As you can see, we've implemented an `IdField` for the `id` column, a `StringField` for the `name` and the `description`, as well as a `BoolField` for the `active` column. Most `Field` classes ask for two parameters, such as the `IdField`:

* A storage name, which represents the name of the field in the storage, e.g. the column in an SQL database.
* A property name, which defines how you can access this field later on. Make sure to remember those for the next step.

The `storageName` is written in snake\_case, while the `propertyName` must be written in lowerCamelCase.

Another thing to note is the `addFlags` call on the `IdField`. Those flags are like attributes to fields, such a required field being marked by using the `Required` flag.

If you want to know more about the flags and how to use them, head over to our guide on how to use flags [Using flags](using-flags).

All that's left to do now, is to introduce your `ExampleDefinition` to Shopware by registering your class in your `services.xml` file and by using the `shopware.entity.definition` tag, because Shopware is looking for definitions this way. If your plugin does not have a `services.xml` file yet or you don't know how that's done, head over to our guide about registering a custom service [Add a custom class / service](../../plugin-fundamentals/add-custom-service) or our guide about the [Dependency injection](../../plugin-fundamentals/dependency-injection).

Here's the `services.xml` as it should look like:

```xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Core\Content\Example\ExampleDefinition">
            <tag name="shopware.entity.definition" entity="swag_example" />
        </service>
    </services>
</container>
```

Please note the tag for your definition and the respective `entity` attribute, which has to contain the technical name of your entity, which you provided in your entity definition. In this case this must be `swag_example`.

And basically that's it already for your definition class. Theoretically you could start using your entity now by injecting the `swag_example.repository` service to other services and start working with the repository, e.g. to [read data](reading-data) or to [write data](writing-data).

Yet, we highly recommend you to create a custom `Entity` class, as well as a custom `EntityCollection` class. This is not mandatory, but those will be replaced with generic classes otherwise.

### Entity class

The entity class itself is a simple key-value object, like a struct, which contains as many properties as fields in the definition, ignoring the ID field, which is handled by the `EntityIdTrait`.

::: warning
The properties of your entity class have to be at least `protected`, otherwise the data abstraction layer won't be able to set the values.
:::

```php
// <plugin root>/src/Core/Content/Example/ExampleEntity.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example;

use Shopware\Core\Framework\DataAbstractionLayer\Entity;
use Shopware\Core\Framework\DataAbstractionLayer\EntityIdTrait;

class ExampleEntity extends Entity
{
    use EntityIdTrait;

    protected ?string $name;

    protected ?string $description;

    protected bool $active;

    public function getName(): ?string
    {
        return $this->name;
    }

    public function setName(?string $name): void
    {
        $this->name = $name;
    }

    public function getDescription(): ?string
    {
        return $this->description;
    }

    public function setDescription(?string $description): void
    {
        $this->description = $description;
    }

    public function isActive(): bool
    {
        return $this->active;
    }

    public function setActive(bool $active): void
    {
        $this->active = $active;
    }
}
```

As you can see, it only holds the properties and its respective getters and setters, for the fields mentioned in the `EntityDefinition` class.

Now you need your definition to know its custom entity class. This is done by overriding the method `getEntityClass` in your `ExampleDefinition`.

```php
// <plugin root>/src/Core/Content/Example/ExampleDefinition.php
class ExampleDefinition extends EntityDefinition
{
    [...]

    public function getEntityClass(): string
    {
        return ExampleEntity::class;
    }
}
```

That's it. Instead of generic `ArrayEntity` instances, you'll get `ExampleEntity` class instances now if you were to read your data using the repository.

### EntityCollection

Just like the `Entity` class, you do want to create your own `EntityCollection` class.

So create a `ExampleCollection` class in the same directory as your `ExampleDefinition` and `ExampleEntity`. Extending from `Shopware\Core\Framework\DataAbstractionLayer\EntityCollection`, it comes with a method called `getExpectedClass`, which once again returns the fully qualified class name of the `Entity` class to be used. Go ahead and override this method and return your `ExampleEntity` here. Additionally, you can provide helper methods in your custom `EntityCollection`, such as filtering the result set by certain conditions, but that's up to you.

This is how your collection class could then look like:

```php
// <plugin root>/src/Core/Content/Example/ExampleCollection.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example;

use Shopware\Core\Framework\DataAbstractionLayer\EntityCollection;

/**
 * @method void               add(ExampleEntity $entity)
 * @method void               set(string $key, ExampleEntity $entity)
 * @method ExampleEntity[]    getIterator()
 * @method ExampleEntity[]    getElements()
 * @method ExampleEntity|null get(string $key)
 * @method ExampleEntity|null first()
 * @method ExampleEntity|null last()
 */
class ExampleCollection extends EntityCollection
{
    protected function getExpectedClass(): string
    {
        return ExampleEntity::class;
    }
}
```

The class documentation is just another helper to have a proper auto-completion when working with your `ExampleCollection`.

Now it's time to introduce your custom collection to your `ExampleDefinition` again. This is done by overriding its `getCollectionClass` method.

```php
// <plugin root>/src/Core/Content/Example/ExampleDefinition.php
class ExampleDefinition extends EntityDefinition
{
    [...]

    public function getCollectionClass(): string
    {
        return ExampleCollection::class;
    }
}
```

That's it, your definition is now completely registered to Shopware 6! From here on your custom entity is accessible throughout the API and you can fully use it for CRUD operations with its repository.

## Next steps

You've now got a simple entity about a single database table. However, your entity will most likely be even more complex.

For example we also have a guide about [Associations](add-data-associations), since you most likely will have multiple tables that have a relation to each other. Furthermore, the fields in this example are already [Using flags](using-flags). When dealing with products, you are also dealing with [Inheritance](field-inheritance), which we also got covered.

One more thing: Maybe you want to connect your database table to an already existing database table, hence an already existing entity. This is done by [extending the said existing entity](add-complex-data-to-existing-entities).

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/framework/data-handling/add-custom-complex-data.md
---

# Adding Custom Complex Data

## Overview

Quite often, your plugin has to save data into a custom database table. Shopware 6's data abstraction layer fully supports custom entities, so you don't have to take care of the data handling at all.

## Prerequisites

This guide is built upon the [Plugin base guide](../../plugin-base-guide), but any plugin will work here. Just note that all examples are using the plugin mentioned above. In order to create a database table, you need to understand plugin migrations [Plugin migrations](../../plugin-fundamentals/database-migrations). Also, you'll have to understand how the [Dependency injection](../../plugin-fundamentals/dependency-injection) works as well.

::: info
Refer to this video on **[Creating a custom entity](https://www.youtube.com/watch?v=mTHTyof4gPk)**. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

## Creating the database table

We'll start with creating a new database table. Make sure to always add your individual prefix to your plugin's database tables, e.g. your manufacturer name.

In this guide we'll name our table `swag_example`, you'll find this name a few more times in here, so make sure to remember that one.

As already mentioned in the prerequisites, creating a database table is done via plugin migrations [Plugin migrations](../../plugin-fundamentals/database-migrations), head over to this guide to understand how this example works.

```php
// <plugin root>/src/Migration/Migration1611664789Example.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Framework\Migration\MigrationStep;

class Migration1611664789Example extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1611664789;
    }

    public function update(Connection $connection): void
    {
        $sql = <<<SQL
CREATE TABLE IF NOT EXISTS `swag_example` (
    `id` BINARY(16) NOT NULL,
    `name` VARCHAR(255) COLLATE utf8mb4_unicode_ci,
    `description` VARCHAR(255) COLLATE utf8mb4_unicode_ci,
    `active` TINYINT(1) COLLATE utf8mb4_unicode_ci,
    `created_at` DATETIME(3) NOT NULL,
    `updated_at` DATETIME(3),
    PRIMARY KEY (`id`)
)
    ENGINE = InnoDB
    DEFAULT CHARSET = utf8mb4
    COLLATE = utf8mb4_unicode_ci;
SQL;
        $connection->executeStatement($sql);
    }

    public function updateDestructive(Connection $connection): void
    {
    }
}
```

After reinstalling your plugin, you should see your new database table `swag_example`.

## Creating an entity

### EntityDefinition class

Introducing the table to Shopware 6 is done by adding a so called `EntityDefinition` for your table. As the name suggests, it defines your own entity, including its fields and name, the latter also represents the table name and therefore has to perfectly match.

Your custom entity definition should be placed inside a folder named after the domain it handles, e.g. "Checkout" if you were to include a Checkout entity. Thus, a good location for this example could be in a directory like this: `<plugin root>/src/Core/Content/Example`\
This will also be the case for the `Entity` class itself, as well as the `EntityCollection` class, but those are explained later in this guide.

Start of with creating a new file named `ExampleDefinition.php` in the directory `<plugin root>/src/Core/Content/Example/ExampleDefinition.php`. Below you can see our example definition, which is explained afterwards:

```php
// <plugin root>/src/Core/Content/Example/ExampleDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example;

use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;

class ExampleDefinition extends EntityDefinition
{
    public const ENTITY_NAME = 'swag_example';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([]);
    }
}
```

First of all, your own definition has to extend from the class `Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition`, which enforces you to implement two methods: `getEntityName` and `defineFields`.

The method `getEntityName` returns a string equal to your table name. In this example it is `swag_example`. Keep in mind, that the return of your `getEntityName` method will be used for two cases:

* The database table name
* The repository name in the DI container (`<the-name>.repository`)

The method `defineFields` contains all the fields, that your entity or table consists of.

As you can see in your migration, your table consists of the following fields: You've got an `id` field, a `name` field, a `description` and an `active` field. Other than that, the other two columns `created_at` and `updated_at` don't have to be defined in your definition, since they're included by default. You're asked to return a `Shopware\Core\Framework\DataAbstractionLayer\FieldCollection` instance here, which then has to contain an array of your fields. There's several field classes, e.g. an `Shopware\Core\Framework\DataAbstractionLayer\Field\IdField` or a `Shopware\Core\Framework\DataAbstractionLayer\Field\StringField`, which you have to create and pass into the `FieldCollection`, so let's do that.

```php
// <plugin root>/src/Core/Content/Example/ExampleDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example;

use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;
use Shopware\Core\Framework\DataAbstractionLayer\Field\BoolField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\PrimaryKey;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
use Shopware\Core\Framework\DataAbstractionLayer\Field\IdField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\StringField;

class ExampleDefinition extends EntityDefinition
{
    public const ENTITY_NAME = 'swag_example';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
            (new StringField('name', 'name')),
            (new StringField('description', 'description')),
            (new BoolField('active', 'active'))
        ]);
    }
}
```

As you can see, we've implemented an `IdField` for the `id` column, a `StringField` for the `name` and the `description`, as well as a `BoolField` for the `active` column. Most `Field` classes ask for two parameters, such as the `IdField`:

* A storage name, which represents the name of the field in the storage, e.g. the column in an SQL database.
* A property name, which defines how you can access this field later on. Make sure to remember those for the next step.

The `storageName` is written in snake\_case, while the `propertyName` must be written in lowerCamelCase.

Another thing to note is the `addFlags` call on the `IdField`. Those flags are like attributes to fields, such a required field being marked by using the `Required` flag.

If you want to know more about the flags and how to use them, head over to our guide on how to use flags [Using flags](using-flags).

All that's left to do now, is to introduce your `ExampleDefinition` to Shopware by registering your class in your `services.xml` file and by using the `shopware.entity.definition` tag, because Shopware is looking for definitions this way. If your plugin does not have a `services.xml` file yet or you don't know how that's done, head over to our guide about registering a custom service [Add a custom class / service](../../plugin-fundamentals/add-custom-service) or our guide about the [Dependency injection](../../plugin-fundamentals/dependency-injection).

Here's the `services.xml` as it should look like:

```xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Core\Content\Example\ExampleDefinition">
            <tag name="shopware.entity.definition" entity="swag_example" />
        </service>
    </services>
</container>
```

Please note the tag for your definition and the respective `entity` attribute, which has to contain the technical name of your entity, which you provided in your entity definition. In this case this must be `swag_example`.

And basically that's it already for your definition class. Theoretically you could start using your entity now by injecting the `swag_example.repository` service to other services and start working with the repository, e.g. to [read data](reading-data) or to [write data](writing-data).

Yet, we highly recommend you to create a custom `Entity` class, as well as a custom `EntityCollection` class. This is not mandatory, but those will be replaced with generic classes otherwise.

### Entity class

The entity class itself is a simple key-value object, like a struct, which contains as many properties as fields in the definition, ignoring the ID field, which is handled by the `EntityIdTrait`.

::: warning
The properties of your entity class have to be at least `protected`, otherwise the data abstraction layer won't be able to set the values.
For the same reason `readonly` properties are not allowed. This holds true not just for `Entity` classes, but for all classes that extend the generic `Struct` class.
:::

```php
// <plugin root>/src/Core/Content/Example/ExampleEntity.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example;

use Shopware\Core\Framework\DataAbstractionLayer\Entity;
use Shopware\Core\Framework\DataAbstractionLayer\EntityIdTrait;

class ExampleEntity extends Entity
{
    use EntityIdTrait;

    protected ?string $name;

    protected ?string $description;

    protected bool $active;

    public function getName(): ?string
    {
        return $this->name;
    }

    public function setName(?string $name): void
    {
        $this->name = $name;
    }

    public function getDescription(): ?string
    {
        return $this->description;
    }

    public function setDescription(?string $description): void
    {
        $this->description = $description;
    }

    public function isActive(): bool
    {
        return $this->active;
    }

    public function setActive(bool $active): void
    {
        $this->active = $active;
    }
}
```

As you can see, it only holds the properties and its respective getters and setters, for the fields mentioned in the `EntityDefinition` class.

Now you need your definition to know its custom entity class. This is done by overriding the method `getEntityClass` in your `ExampleDefinition`.

```php
// <plugin root>/src/Core/Content/Example/ExampleDefinition.php
class ExampleDefinition extends EntityDefinition
{
    [...]

    public function getEntityClass(): string
    {
        return ExampleEntity::class;
    }
}
```

That's it. Instead of generic `ArrayEntity` instances, you'll get `ExampleEntity` class instances now if you were to read your data using the repository.

### EntityCollection

Just like the `Entity` class, you do want to create your own `EntityCollection` class.

So create a `ExampleCollection` class in the same directory as your `ExampleDefinition` and `ExampleEntity`. Extending from `Shopware\Core\Framework\DataAbstractionLayer\EntityCollection`, it comes with a method called `getExpectedClass`, which once again returns the fully qualified class name of the `Entity` class to be used. Go ahead and override this method and return your `ExampleEntity` here. Additionally, you can provide helper methods in your custom `EntityCollection`, such as filtering the result set by certain conditions, but that's up to you.

This is how your collection class could then look like:

```php
// <plugin root>/src/Core/Content/Example/ExampleCollection.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example;

use Shopware\Core\Framework\DataAbstractionLayer\EntityCollection;

/**
 * @extends EntityCollection<ExampleEntity>
 */
class ExampleCollection extends EntityCollection
{
    protected function getExpectedClass(): string
    {
        return ExampleEntity::class;
    }
}
```

The class documentation is just another helper to have a proper auto-completion when working with your `ExampleCollection`.

Now it's time to introduce your custom collection to your `ExampleDefinition` again. This is done by overriding its `getCollectionClass` method.

```php
// <plugin root>/src/Core/Content/Example/ExampleDefinition.php
class ExampleDefinition extends EntityDefinition
{
    [...]

    public function getCollectionClass(): string
    {
        return ExampleCollection::class;
    }
}
```

That's it, your definition is now completely registered to Shopware 6! From here on your custom entity is accessible throughout the API and you can fully use it for CRUD operations with its repository.

## Next steps

You've now got a simple entity about a single database table. However, your entity will most likely be even more complex.

For example we also have a guide about [Associations](add-data-associations), since you most likely will have multiple tables that have a relation to each other. Furthermore, the fields in this example are already [Using flags](using-flags). When dealing with products, you are also dealing with [Inheritance](field-inheritance), which we also got covered.

One more thing: Maybe you want to connect your database table to an already existing database table, hence an already existing entity. This is done by [extending the said existing entity](add-complex-data-to-existing-entities).

---

---
url: /docs/guides/plugins/plugins/framework/data-handling/add-data-associations.md
---

# Adding Data Associations

## Overview

In this guide you will learn how to add associations to your entities. Every possible kind of association will be covered here, so "One to One", "Many to One" or "One to Many" respectively, and "Many to many" associations.

In every example we'll be working with two example entities, that we want to connect with an association: `FooEntity` and `BarEntity`.

They are **not** created in this guide though!

## Prerequisites

This guide is built upon the [Plugin Base Guide](../../plugin-base-guide), but any plugin will work here. Just note that all examples are using the plugin mentioned above.

In order to add data associations you need an existing entity, as this guide is based on the [Adding custom complex data](add-custom-complex-data) guide, you should have a look at it first.

## Associations

In the following paragraphs, there will be examples for each kind of association. Those are simplified, which means that this guide will not cover how to create entities in the first place. Head over to our guide regarding [Adding custom complex data](add-custom-complex-data).

## Example entity definitions

As already mentioned, this guide will always use the same two example entities for each type of association. They both contain only an ID field, nothing else. For the sake of clarity, here are those example entity definitions:

```php
// <plugin root>/src/Core/Content/Bar/BarDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Bar;

use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\PrimaryKey;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
use Shopware\Core\Framework\DataAbstractionLayer\Field\IdField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;

class BarDefinition extends EntityDefinition
{
    public const ENTITY_NAME = 'bar';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
            // Other fields here
        ]);
    }
}
```

```php
// <plugin root>/src/Core/Content/Foo/FooDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Foo;

use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\PrimaryKey;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
use Shopware\Core\Framework\DataAbstractionLayer\Field\IdField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;

class FooDefinition extends EntityDefinition
{
    public const ENTITY_NAME = 'foo';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
            // Other fields here
        ]);
    }
}
```

### One to One associations

One to One associations require you to define a foreign key for one of the two connected associations. E.g. the `bar` table has to contain a `foo_id` column, or the other way around: A `bar_id` column in the `foo` table. In this example it will be `foo_id` in the `BarDefinition`.

Let's have a look at the `defineFields` methods of both entity definitions:

```php
// <plugin root>/src/Core/Content/Bar/BarDefinition.php
protected function defineFields(): FieldCollection
{
    return new FieldCollection([
        (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
        (new FkField('foo_id', 'fooId', FooDefinition::class))->addFlags(new Required()),
        (new StringField('name', 'name'))->addFlags(new Required()),

        new OneToOneAssociationField('foo', 'foo_id', 'id', FooDefinition::class, false)
    ]);
}
```

Note the new `FkField`, which basically is the mentioned `foo_id` column. Its parameters are the name of the column in your database(snake\_case), the property name in your definition (lowerCamelCase) and the respective definition class.

Additional to that, we've got the `OneToOneAssociationField`. Here you supply the name of the property, which should contain the associated entity, in your respective definition, e.g. in this case we want the `FooDefinition` to appear in the `foo` property of our entity. Following are `foo_id`, which is the name of the column in the database, `id` as the ID column in the referenced database (`foo` in this case) and the referenced definition. The last parameter defines, if you want to automatically load this association every time you load a `bar` entity. We've set this to `false`.

::: warning
Setting autoload to \`true\` on the \`EntityExtension\` and \`EntityDefinition\` will lead to a recursion / out of memory error. If you want to get the association on every load, set autoload to \`true\` only in the \`EntityExtension\`. See also [Add complex data to existing entities](../data-handling/add-complex-data-to-existing-entities#adding-a-field-with-database).
:::

For the sake of completion, here is the respective `defineFields` method of the `FooDefinition`:

```php
// <plugin root>/src/Core/Content/Foo/FooDefinition.php
protected function defineFields(): FieldCollection
{
    return new FieldCollection([
        (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
        (new StringField('name', 'name'))->addFlags(new Required()),

        (new OneToOneAssociationField('bar', 'id', 'foo_id', BarDefinition::class, false))
    ]);
}
```

Note, that in here there is no `FkField` necessary.

### One to Many / Many to One

In "One To Many" / "Many To One" associations, you need to define a foreign key column for the "Many to One" side. E.g. your `bar` entity comes with multiple `foo`'s. Therefore, you have to add a `bar_id` column in your `foo` table. In this example it will be `bar_id` in the `FooDefinition`.

Let's have a look at the `defineFields` methods of both entity definitions:

```php
// <plugin root>/src/Core/Content/Bar/BarDefinition.php
protected function defineFields(): FieldCollection
{
    return new FieldCollection([
        (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),

        new OneToManyAssociationField('foos', FooDefinition::class, 'bar_id')
    ]);
}
```

Next to the `IdField`, you only have to define the `OneToManyAssociationField` in your `BarDefinition`. Its parameters are `foos`, which is the property that will contain all `FooEntity`'s, the class name of `FooDefinition` and the name of the column in the referenced table, which points to the definition itself.

Let's have a look at the `FooDefinition` now:

```php
// <plugin root>/src/Core/Content/Foo/FooDefinition.php
protected function defineFields(): FieldCollection
{
    return new FieldCollection([
        (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
        (new FkField('bar_id', 'barId', BarDefinition::class))->addFlags(new Required()),

        new ManyToOneAssociationField('bar', 'bar_id', BarDefinition::class, 'id'),
    ]);
}
```

Next to the `IdField`, you can see a new `FkField`, which is the field for the new `bar_id` column. Its parameters are the name of the column in your database (snake\_case), the property name in your definition (lowerCamelCase) and the respective definition class.

Instead of adding a `OneToManyAssociationField` here now, we have to use the reverse side, which is `ManyToOneAssociationField`. Here you have to apply the name of the property, which will contain the single `BarDefinition` instance, the name of the column, which references to the inverse side entity (`bar_id`), the class of the referenced definition and the name of the ID column in the definition's database table itself. You could add another boolean parameter here, which would define whether or not you want this association to always automatically be added and be loaded. This defaults to `false`, since enabling this could come with performance issues.

### Many to Many associations

`ManyToMany` associations require another, third entity to be available. It will be called `FooBarMappingDefinition` and is responsible for connecting both definitions. It also needs an own database table.

#### Mapping definition

Let's create this one first:

```php
// <plugin root>/src/Core/Content/FooBarMappingDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content;

use Shopware\Core\Framework\DataAbstractionLayer\Field\CreatedAtField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\FkField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\PrimaryKey;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
use Shopware\Core\Framework\DataAbstractionLayer\Field\ManyToOneAssociationField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;
use Shopware\Core\Framework\DataAbstractionLayer\MappingEntityDefinition;
use Swag\BasicExample\Core\Content\Bar\BarDefinition;
use Swag\BasicExample\Core\Content\Foo\FooDefinition;

class FooBarMappingDefinition extends MappingEntityDefinition
{
    public const ENTITY_NAME = 'foo_bar';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new FkField('bar_id', 'barId', BarDefinition::class))->addFlags(new PrimaryKey(), new Required()),
            (new FkField('foo_id', 'fooId', FooDefinition::class))->addFlags(new PrimaryKey(), new Required()),
            new ManyToOneAssociationField('bar', 'bar_id', BarDefinition::class, 'id'),
            new ManyToOneAssociationField('foo', 'foo_id', FooDefinition::class, 'id')
        ]);
    }
}
```

The mapping definition has to extend from the `MappingEntityDefinition`, instead of the `EntityDefinition` like in other entity definitions. The rest is quite the same: Your entity definitions needs an entity name, saved in `ENTITY_NAME`, as well as the method `defineFields`, which has to return a `FieldCollection`.

First of all there are two `FkField`'s. Its parameters are the name of the column in your database(snake\_case), the property name in your definition (lowerCamelCase) and the respective definition class.

Additional to that, you need the `ManyToOneAssociationField`'s. Here you have to supply the name of the property in your entity, which should contain the entries, again the name of the column in the database and the definition again. The last parameter is most likely `id`, which is the column name of the connected table. You could add another boolean parameter here, which would define whether or not you want this association to always automatically be added and be loaded. This defaults to `false`, since enabling this could come with performance issues.

Of course, you have to add both mentioned fields for each definition you want to connect, so two times that is.

#### Adjusting the main definitions

The last thing to do, is to add a `ManyToManyAssociationField` to each of your definitions themselves, like in the following example:

```php
// <plugin root>/src/Core/Content/Bar/BarDefinition.php
protected function defineFields(): FieldCollection
{
    return new FieldCollection([
        (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),

        new ManyToManyAssociationField(
            'foos',
            FooDefinition::class,
            FooBarMappingDefinition::class,
            'bar_id',
            'foo_id'
        ),
    ]);
}
```

Its parameters are the following:

* `propertyName`: The name of the property in your entity, that will contain the associated entities.
* `referenceDefinition`: The class of the associated definition.
* `mappingDefinition`: The class of the mapping definition.
* `mappingLocalColumn`: The name of the id column for the current entity, `bar_id` if you're in the `BarDefinition`.
* `mappingReferenceColumn`: The name of the id column for the referenced entity.

For the sake of completion, here is the respective `FooDefinition`:

```php
// <plugin root>/src/Core/Content/Foo/FooDefinition.php
protected function defineFields(): FieldCollection
{
    return new FieldCollection([
        (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),

        new ManyToManyAssociationField(
            'bars',
            BarDefinition::class,
            FooBarMappingDefinition::class,
            'foo_id',
            'bar_id'
        ),
    ]);
}
```

And that's it, your `ManyToMany` association is now set up properly.

## Next steps

One type of association you'll often stumble upon are translations. If you wonder how to add translations to your entity, [this is the place](add-data-translations) to go.

Otherwise you may want to update some data, for this you can look at our [Writing data](writing-data) and [Replacing data](reading-data) guide. If you plan to remove associated data from entities, you can head over to our [Remove associated data](deleting-associated-data) guide.

---

---
url: >-
  /docs/v6.5/guides/plugins/plugins/framework/data-handling/add-data-associations.md
---

# Adding Data Associations

## Overview

In this guide you will learn how to add associations to your entities. Every possible kind of association will be covered here, so "One to One", "Many to One" or "One to Many" respectively, and "Many to many" associations.

In every example we'll be working with two example entities, that we want to connect with an association: `FooEntity` and `BarEntity`.

They are **not** created in this guide though!

## Prerequisites

This guide is built upon the [Plugin Base Guide](../../plugin-base-guide), but any plugin will work here. Just note that all examples are using the plugin mentioned above.

In order to add data associations you need an existing entity, as this guide is based on the [Adding custom complex data](add-custom-complex-data) guide, you should have a look at it first.

## Associations

In the following paragraphs, there will be examples for each kind of association. Those are simplified, which means that this guide will not cover how to create entities in the first place. Head over to our guide regarding [Adding custom complex data](add-custom-complex-data).

## Example entity definitions

As already mentioned, this guide will always use the same two example entities for each type of association. They both contain only an ID field, nothing else. For the sake of clarity, here are those example entity definitions:

```php
// <plugin root>/src/Core/Content/Bar/BarDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Bar;

use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\PrimaryKey;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
use Shopware\Core\Framework\DataAbstractionLayer\Field\IdField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;

class BarDefinition extends EntityDefinition
{
    public const ENTITY_NAME = 'bar';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
            // Other fields here
        ]);
    }
}
```

```php
// <plugin root>/src/Core/Content/Foo/FooDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Foo;

use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\PrimaryKey;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
use Shopware\Core\Framework\DataAbstractionLayer\Field\IdField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;

class FooDefinition extends EntityDefinition
{
    public const ENTITY_NAME = 'foo';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
            // Other fields here
        ]);
    }
}
```

### One to One associations

One to One associations require you to define a foreign key for one of the two connected associations. E.g. the `bar` table has to contain a `foo_id` column, or the other way around: A `bar_id` column in the `foo` table. In this example it will be `foo_id` in the `BarDefinition`.

Let's have a look at the `defineFields` methods of both entity definitions:

```php
// <plugin root>/src/Core/Content/Bar/BarDefinition.php
protected function defineFields(): FieldCollection
{
    return new FieldCollection([
        (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
        (new FkField('foo_id', 'fooId', FooDefinition::class))->addFlags(new Required()),
        (new StringField('name', 'name'))->addFlags(new Required()),

        new OneToOneAssociationField('foo', 'foo_id', 'id', FooDefinition::class, false)
    ]);
}
```

Note the new `FkField`, which basically is the mentioned `foo_id` column. Its parameters are the name of the column in your database(snake\_case), the property name in your definition (lowerCamelCase) and the respective definition class.

Additional to that, we've got the `OneToOneAssociationField`. Here you supply the name of the property, which should contain the associated entity, in your respective definition, e.g. in this case we want the `FooDefinition` to appear in the `foo` property of our entity. Following are `foo_id`, which is the name of the column in the database, `id` as the ID column in the referenced database (`foo` in this case) and the referenced definition. The last parameter defines, if you want to automatically load this association every time you load a `bar` entity. We've set this to `false`.

::: warning
Setting autoload to \`true\` on the \`EntityExtension\` and \`EntityDefinition\` will lead to a recursion / out of memory error. If you want to get the association on every load, set autoload to \`true\` only in the \`EntityExtension\`. See also [Add complex data to existing entities](../data-handling/add-complex-data-to-existing-entities#adding-a-field-with-database).
:::

For the sake of completion, here is the respective `defineFields` method of the `FooDefinition`:

```php
// <plugin root>/src/Core/Content/Foo/FooDefinition.php
protected function defineFields(): FieldCollection
{
    return new FieldCollection([
        (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
        (new StringField('name', 'name'))->addFlags(new Required()),

        (new OneToOneAssociationField('bar', 'id', 'foo_id', BarDefinition::class, false))
    ]);
}
```

Note, that in here there is no `FkField` necessary.

### One to Many / Many to One

In "One To Many" / "Many To One" associations, you need to define a foreign key column for the "Many to One" side. E.g. your `bar` entity comes with multiple `foo`'s. Therefore, you have to add a `bar_id` column in your `foo` table. In this example it will be `bar_id` in the `FooDefinition`.

Let's have a look at the `defineFields` methods of both entity definitions:

```php
// <plugin root>/src/Core/Content/Bar/BarDefinition.php
protected function defineFields(): FieldCollection
{
    return new FieldCollection([
        (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),

        new OneToManyAssociationField('foos', FooDefinition::class, 'bar_id')
    ]);
}
```

Next to the `IdField`, you only have to define the `OneToManyAssociationField` in your `BarDefinition`. Its parameters are `foos`, which is the property that will contain all `FooEntity`'s, the class name of `FooDefinition` and the name of the column in the referenced table, which points to the definition itself.

Let's have a look at the `FooDefinition` now:

```php
// <plugin root>/src/Core/Content/Foo/FooDefinition.php
protected function defineFields(): FieldCollection
{
    return new FieldCollection([
        (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
        (new FkField('bar_id', 'barId', BarDefinition::class))->addFlags(new Required()),

        new ManyToOneAssociationField('bar', 'bar_id', BarDefinition::class, 'id'),
    ]);
}
```

Next to the `IdField`, you can see a new `FkField`, which is the field for the new `bar_id` column. Its parameters are the name of the column in your database (snake\_case), the property name in your definition (lowerCamelCase) and the respective definition class.

Instead of adding a `OneToManyAssociationField` here now, we have to use the reverse side, which is `ManyToOneAssociationField`. Here you have to apply the name of the property, which will contain the single `BarDefinition` instance, the name of the column, which references to the inverse side entity (`bar_id`), the class of the referenced definition and the name of the ID column in the definition's database table itself. You could add another boolean parameter here, which would define whether or not you want this association to always automatically be added and be loaded. This defaults to `false`, since enabling this could come with performance issues.

### Many to Many associations

`ManyToMany` associations require another, third entity to be available. It will be called `FooBarMappingDefinition` and is responsible for connecting both definitions. It also needs an own database table.

#### Mapping definition

Let's create this one first:

```php
// <plugin root>/src/Core/Content/FooBarMappingDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content;

use Shopware\Core\Framework\DataAbstractionLayer\Field\CreatedAtField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\FkField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\PrimaryKey;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
use Shopware\Core\Framework\DataAbstractionLayer\Field\ManyToOneAssociationField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;
use Shopware\Core\Framework\DataAbstractionLayer\MappingEntityDefinition;
use Swag\BasicExample\Core\Content\Bar\BarDefinition;
use Swag\BasicExample\Core\Content\Foo\FooDefinition;

class FooBarMappingDefinition extends MappingEntityDefinition
{
    public const ENTITY_NAME = 'foo_bar';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new FkField('bar_id', 'barId', BarDefinition::class))->addFlags(new PrimaryKey(), new Required()),
            (new FkField('foo_id', 'fooId', FooDefinition::class))->addFlags(new PrimaryKey(), new Required()),
            new ManyToOneAssociationField('bar', 'bar_id', BarDefinition::class, 'id'),
            new ManyToOneAssociationField('foo', 'foo_id', FooDefinition::class, 'id')
        ]);
    }
}
```

The mapping definition has to extend from the `MappingEntityDefinition`, instead of the `EntityDefinition` like in other entity definitions. The rest is quite the same: Your entity definitions needs an entity name, saved in `ENTITY_NAME`, as well as the method `defineFields`, which has to return a `FieldCollection`.

First of all there are two `FkField`'s. Its parameters are the name of the column in your database(snake\_case), the property name in your definition (lowerCamelCase) and the respective definition class.

Additional to that, you need the `ManyToOneAssociationField`'s. Here you have to supply the name of the property in your entity, which should contain the entries, again the name of the column in the database and the definition again. The last parameter is most likely `id`, which is the column name of the connected table. You could add another boolean parameter here, which would define whether or not you want this association to always automatically be added and be loaded. This defaults to `false`, since enabling this could come with performance issues.

Of course, you have to add both mentioned fields for each definition you want to connect, so two times that is.

#### Adjusting the main definitions

The last thing to do, is to add a `ManyToManyAssociationField` to each of your definitions themselves, like in the following example:

```php
// <plugin root>/src/Core/Content/Bar/BarDefinition.php
protected function defineFields(): FieldCollection
{
    return new FieldCollection([
        (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),

        new ManyToManyAssociationField(
            'foos',
            FooDefinition::class,
            FooBarMappingDefinition::class,
            'bar_id',
            'foo_id'
        ),
    ]);
}
```

Its parameters are the following:

* `propertyName`: The name of the property in your entity, that will contain the associated entities.
* `referenceDefinition`: The class of the associated definition.
* `mappingDefinition`: The class of the mapping definition.
* `mappingLocalColumn`: The name of the id column for the current entity, `bar_id` if you're in the `BarDefinition`.
* `mappingReferenceColumn`: The name of the id column for the referenced entity.

For the sake of completion, here is the respective `FooDefinition`:

```php
// <plugin root>/src/Core/Content/Foo/FooDefinition.php
protected function defineFields(): FieldCollection
{
    return new FieldCollection([
        (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),

        new ManyToManyAssociationField(
            'bars',
            BarDefinition::class,
            FooBarMappingDefinition::class,
            'foo_id',
            'bar_id'
        ),
    ]);
}
```

And that's it, your `ManyToMany` association is now set up properly.

## Next steps

One type of association you'll often stumble upon are translations. If you wonder how to add translations to your entity, [this is the place](add-data-translations) to go.

Otherwise you may want to update some data, for this you can look at our [Writing data](writing-data) and [Replacing data](reading-data) guide. If you plan to remove associated data from entities, you can head over to our [Remove associated data](deleting-associated-data) guide.

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/framework/data-handling/add-data-associations.md
---

# Adding Data Associations

## Overview

In this guide you will learn how to add associations to your entities. Every possible kind of association will be covered here, so "One to One", "Many to One" or "One to Many" respectively, and "Many to many" associations.

In every example we'll be working with two example entities, that we want to connect with an association: `FooEntity` and `BarEntity`.

They are **not** created in this guide though!

## Prerequisites

This guide is built upon the [Plugin Base Guide](../../plugin-base-guide), but any plugin will work here. Just note that all examples are using the plugin mentioned above.

In order to add data associations you need an existing entity, as this guide is based on the [Adding custom complex data](add-custom-complex-data) guide, you should have a look at it first.

## Associations

In the following paragraphs, there will be examples for each kind of association. Those are simplified, which means that this guide will not cover how to create entities in the first place. Head over to our guide regarding [Adding custom complex data](add-custom-complex-data).

## Example entity definitions

As already mentioned, this guide will always use the same two example entities for each type of association. They both contain only an ID field, nothing else. For the sake of clarity, here are those example entity definitions:

```php
// <plugin root>/src/Core/Content/Bar/BarDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Bar;

use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\PrimaryKey;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
use Shopware\Core\Framework\DataAbstractionLayer\Field\IdField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;

class BarDefinition extends EntityDefinition
{
    public const ENTITY_NAME = 'bar';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
            // Other fields here
        ]);
    }
}
```

```php
// <plugin root>/src/Core/Content/Foo/FooDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Foo;

use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\PrimaryKey;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
use Shopware\Core\Framework\DataAbstractionLayer\Field\IdField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;

class FooDefinition extends EntityDefinition
{
    public const ENTITY_NAME = 'foo';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
            // Other fields here
        ]);
    }
}
```

### One to One associations

One to One associations require you to define a foreign key for one of the two connected associations. E.g. the `bar` table has to contain a `foo_id` column, or the other way around: A `bar_id` column in the `foo` table. In this example it will be `foo_id` in the `BarDefinition`.

Let's have a look at the `defineFields` methods of both entity definitions:

```php
// <plugin root>/src/Core/Content/Bar/BarDefinition.php
protected function defineFields(): FieldCollection
{
    return new FieldCollection([
        (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
        (new FkField('foo_id', 'fooId', FooDefinition::class))->addFlags(new Required()),
        (new StringField('name', 'name'))->addFlags(new Required()),

        new OneToOneAssociationField('foo', 'foo_id', 'id', FooDefinition::class, false)
    ]);
}
```

Note the new `FkField`, which basically is the mentioned `foo_id` column. Its parameters are the name of the column in your database(snake\_case), the property name in your definition (lowerCamelCase) and the respective definition class.

Additional to that, we've got the `OneToOneAssociationField`. Here you supply the name of the property, which should contain the associated entity, in your respective definition, e.g. in this case we want the `FooDefinition` to appear in the `foo` property of our entity. Following are `foo_id`, which is the name of the column in the database, `id` as the ID column in the referenced database (`foo` in this case) and the referenced definition. The last parameter defines, if you want to automatically load this association every time you load a `bar` entity. We've set this to `false`.

::: warning
Setting autoload to \`true\` on the \`EntityExtension\` and \`EntityDefinition\` will lead to a recursion / out of memory error. If you want to get the association on every load, set autoload to \`true\` only in the \`EntityExtension\`. See also [Add complex data to existing entities](../data-handling/add-complex-data-to-existing-entities#adding-a-field-with-database).
:::

For the sake of completion, here is the respective `defineFields` method of the `FooDefinition`:

```php
// <plugin root>/src/Core/Content/Foo/FooDefinition.php
protected function defineFields(): FieldCollection
{
    return new FieldCollection([
        (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
        (new StringField('name', 'name'))->addFlags(new Required()),

        (new OneToOneAssociationField('bar', 'id', 'foo_id', BarDefinition::class, false))
    ]);
}
```

Note, that in here there is no `FkField` necessary.

### One to Many / Many to One

In "One To Many" / "Many To One" associations, you need to define a foreign key column for the "Many to One" side. E.g. your `bar` entity comes with multiple `foo`'s. Therefore, you have to add a `bar_id` column in your `foo` table. In this example it will be `bar_id` in the `FooDefinition`.

Let's have a look at the `defineFields` methods of both entity definitions:

```php
// <plugin root>/src/Core/Content/Bar/BarDefinition.php
protected function defineFields(): FieldCollection
{
    return new FieldCollection([
        (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),

        new OneToManyAssociationField('foos', FooDefinition::class, 'bar_id')
    ]);
}
```

Next to the `IdField`, you only have to define the `OneToManyAssociationField` in your `BarDefinition`. Its parameters are `foos`, which is the property that will contain all `FooEntity`'s, the class name of `FooDefinition` and the name of the column in the referenced table, which points to the definition itself.

Let's have a look at the `FooDefinition` now:

```php
// <plugin root>/src/Core/Content/Foo/FooDefinition.php
protected function defineFields(): FieldCollection
{
    return new FieldCollection([
        (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),
        (new FkField('bar_id', 'barId', BarDefinition::class))->addFlags(new Required()),

        new ManyToOneAssociationField('bar', 'bar_id', BarDefinition::class, 'id'),
    ]);
}
```

Next to the `IdField`, you can see a new `FkField`, which is the field for the new `bar_id` column. Its parameters are the name of the column in your database (snake\_case), the property name in your definition (lowerCamelCase) and the respective definition class.

Instead of adding a `OneToManyAssociationField` here now, we have to use the reverse side, which is `ManyToOneAssociationField`. Here you have to apply the name of the property, which will contain the single `BarDefinition` instance, the name of the column, which references to the inverse side entity (`bar_id`), the class of the referenced definition and the name of the ID column in the definition's database table itself. You could add another boolean parameter here, which would define whether or not you want this association to always automatically be added and be loaded. This defaults to `false`, since enabling this could come with performance issues.

### Many to Many associations

`ManyToMany` associations require another, third entity to be available. It will be called `FooBarMappingDefinition` and is responsible for connecting both definitions. It also needs an own database table.

#### Mapping definition

Let's create this one first:

```php
// <plugin root>/src/Core/Content/FooBarMappingDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content;

use Shopware\Core\Framework\DataAbstractionLayer\Field\CreatedAtField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\FkField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\PrimaryKey;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
use Shopware\Core\Framework\DataAbstractionLayer\Field\ManyToOneAssociationField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;
use Shopware\Core\Framework\DataAbstractionLayer\MappingEntityDefinition;
use Swag\BasicExample\Core\Content\Bar\BarDefinition;
use Swag\BasicExample\Core\Content\Foo\FooDefinition;

class FooBarMappingDefinition extends MappingEntityDefinition
{
    public const ENTITY_NAME = 'foo_bar';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new FkField('bar_id', 'barId', BarDefinition::class))->addFlags(new PrimaryKey(), new Required()),
            (new FkField('foo_id', 'fooId', FooDefinition::class))->addFlags(new PrimaryKey(), new Required()),
            new ManyToOneAssociationField('bar', 'bar_id', BarDefinition::class, 'id'),
            new ManyToOneAssociationField('foo', 'foo_id', FooDefinition::class, 'id')
        ]);
    }
}
```

The mapping definition has to extend from the `MappingEntityDefinition`, instead of the `EntityDefinition` like in other entity definitions. The rest is quite the same: Your entity definitions needs an entity name, saved in `ENTITY_NAME`, as well as the method `defineFields`, which has to return a `FieldCollection`.

First of all there are two `FkField`'s. Its parameters are the name of the column in your database(snake\_case), the property name in your definition (lowerCamelCase) and the respective definition class.

Additional to that, you need the `ManyToOneAssociationField`'s. Here you have to supply the name of the property in your entity, which should contain the entries, again the name of the column in the database and the definition again. The last parameter is most likely `id`, which is the column name of the connected table. You could add another boolean parameter here, which would define whether or not you want this association to always automatically be added and be loaded. This defaults to `false`, since enabling this could come with performance issues.

Of course, you have to add both mentioned fields for each definition you want to connect, so two times that is.

#### Adjusting the main definitions

The last thing to do, is to add a `ManyToManyAssociationField` to each of your definitions themselves, like in the following example:

```php
// <plugin root>/src/Core/Content/Bar/BarDefinition.php
protected function defineFields(): FieldCollection
{
    return new FieldCollection([
        (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),

        new ManyToManyAssociationField(
            'foos',
            FooDefinition::class,
            FooBarMappingDefinition::class,
            'bar_id',
            'foo_id'
        ),
    ]);
}
```

Its parameters are the following:

* `propertyName`: The name of the property in your entity, that will contain the associated entities.
* `referenceDefinition`: The class of the associated definition.
* `mappingDefinition`: The class of the mapping definition.
* `mappingLocalColumn`: The name of the id column for the current entity, `bar_id` if you're in the `BarDefinition`.
* `mappingReferenceColumn`: The name of the id column for the referenced entity.

For the sake of completion, here is the respective `FooDefinition`:

```php
// <plugin root>/src/Core/Content/Foo/FooDefinition.php
protected function defineFields(): FieldCollection
{
    return new FieldCollection([
        (new IdField('id', 'id'))->addFlags(new Required(), new PrimaryKey()),

        new ManyToManyAssociationField(
            'bars',
            BarDefinition::class,
            FooBarMappingDefinition::class,
            'foo_id',
            'bar_id'
        ),
    ]);
}
```

And that's it, your `ManyToMany` association is now set up properly.

## Next steps

One type of association you'll often stumble upon are translations. If you wonder how to add translations to your entity, [this is the place](add-data-translations) to go.

Otherwise you may want to update some data, for this you can look at our [Writing data](writing-data) and [Replacing data](reading-data) guide. If you plan to remove associated data from entities, you can head over to our [Remove associated data](deleting-associated-data) guide.

---

---
url: /docs/guides/plugins/plugins/framework/data-handling/add-data-indexer.md
---

# Adding Data Indexer

## Overview

Data indexer are used to optimize the performance of recurring complex tasks.

One good example to understand the benefit of data indexer would be the cheapest price calculation within Shopware. Every product has a `cheapest_price` column in the database which should contain the cheapest price a product has. The calculation of this column can be complex, because a product can have several variants with advanced pricing rules and so on. This makes the calculation more difficult and would take too much time when reading 25 products for a listing.

To optimize the performance there is a data indexer that calculates the cheapest price of a product every time the product is updated by the DAL. This means that no new calculation has to be performed when a product is read, and performance during reading is significantly increased. Furthermore data indexer can make use of the [Message queue](../../../../hosting/infrastructure/message-queue.md) to handle the calculations asynchronously.

## Prerequisites

This guide is built upon the [Plugin base guide](../../plugin-base-guide.md), but any plugin will work here. Just note that all examples are using the plugin mentioned above. In order to create data indexer you should have read the [Adding custom complex data guide](./add-custom-complex-data.md).

## Adding an own data indexer

It is possible to add data indexer for your own entities, like the one created in the [Adding custom complex data](./add-custom-complex-data) guide or for existing entities. However, if you want to react on changes of existing entities the preferred way should be subscribing to the events if available. See the [Index data using existing events](./add-data-indexer.md#index-data-using-existing-events) section below. To create a new indexer, just create a new class in your plugin:

```php
// <plugin root>/src/Core/Framework/DataAbstractionLayer/Indexing/ExampleIndexer.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Framework\DataAbstractionLayer\Indexing;

use Doctrine\DBAL\Connection;
use Shopware\Core\Checkout\Customer\CustomerDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Dbal\Common\IteratorFactory;
use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\DataAbstractionLayer\Event\EntityWrittenContainerEvent;
use Shopware\Core\Framework\DataAbstractionLayer\Indexing\EntityIndexer;
use Shopware\Core\Framework\DataAbstractionLayer\Indexing\EntityIndexingMessage;
use Shopware\Core\Framework\Uuid\Uuid;

class ExampleIndexer extends EntityIndexer
{
    private IteratorFactory $iteratorFactory;

    private EntityRepository $repository;

    private Connection $connection;

    public function __construct(
        IteratorFactory $iteratorFactory,
        EntityRepository $repository,
        Connection $connection
    ) {
        $this->iteratorFactory = $iteratorFactory;
        $this->repository = $repository;
        $this->connection = $connection;
    }

    /**
     * Returns a unique name for this indexer.
     */
    public function getName(): string
    {
        return 'swag.basic.example.indexer';
    }

    /**
     * Called when a full entity index is required. This function should generate a list of message for all records which
     * are indexed by this indexer.
     */

    public function iterate($offset): ?EntityIndexingMessage
    {
        $iterator = $this->iteratorFactory->createIterator($this->repository->getDefinition(), $offset);

        $ids = $iterator->fetch();

        if (empty($ids)) {
            return null;
        }

        return new EntityIndexingMessage(array_values($ids), $iterator->getOffset());
    }

    /**
     * Called when entities are updated over the DAL. This function should react to the provided entity written events
     * and generate a list of messages which has to be processed by the `handle` function over the message queue workers.
     */
    public function update(EntityWrittenContainerEvent $event): ?EntityIndexingMessage
    {
        $updates = $event->getPrimaryKeys(CustomerDefinition::ENTITY_NAME);

        if (empty($updates)) {
            return null;
        }

        return new EntityIndexingMessage(array_values($updates), null, $event->getContext());
    }

    /**
     * Called over the message queue workers. The messages are the generated messages
     * of the `self::iterate` or `self::update` functions.
     */
    public function handle(EntityIndexingMessage $message): void
    {
        $ids = $message->getData();

        if (!$ids) {
            return;
        }

        foreach ($ids as $id) {
            $this->writeLog($id);
        }
    }

    private function writeLog($customerId)
    {
        $this->connection->executeStatement('INSERT INTO `log_entry` (`id`, `message`, `level`, `channel`, `created_at`) VALUES (:id, :message, :level, :channel, now())', [
            'id' => Uuid::randomBytes(),
            'message' => 'Indexed customer with id: ' . $customerId,
            'level' => 1,
            'channel' => 'debug'
        ]);
    }
}
```

With the corresponding service registration:

```php
<?php declare(strict_types=1);

use Doctrine\DBAL\Connection;
use Shopware\Core\Framework\DataAbstractionLayer\Dbal\Common\IteratorFactory;
use Swag\BasicExample\Core\Framework\DataAbstractionLayer\Indexing\ExampleIndexer;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(ExampleIndexer::class)
        ->args([
            service(IteratorFactory::class),
            service('customer.repository'),
            service(Connection::class),
        ])
        ->tag('shopware.entity_indexer');
};
```

The indexer service has to be tagged as `shopware.entity_indexer` in order to work.

Let's take a closer look at the functions of the entity indexer class.

* `public function getName(): string`:
  * This function returns the name of the indexer and should be unique. It is used in the `EntityIndexerRegistry` to identify which messages should be handled by which indexer.
* `public function iterate($offset): ?EntityIndexingMessage`:
  * This function is called when a full entity indexing was requested. This is for example the case if the console command `bin/console dal:refresh:index` is used or if a user of the Administration requested an update of all indexes in the settings.
    It should generate a list of messages for all records which are indexed by this indexer. In the example documentation above, the customer entity should be indexed. Therefore, the `Shopware\Core\Framework\DataAbstractionLayer\Dbal\Common\IteratorFactory` is used to fetch customer ids. The offset is used to reduce the amount of data which is processed at once.
* `public function update(EntityWrittenContainerEvent $event): ?EntityIndexingMessage`:
  * This function is called when entities are updated over the DAL. This function should react to the provided entity written events and generate a list of messages which has to be processed by the `handle` function. In the example implementation above, we get all customer identifiers that have been updated by `$updates = $event->getPrimaryKeys(CustomerDefinition::ENTITY_NAME);`. A closer look at the `EntityWrittenContainerEvent` class is also good idea. It is for example possible to filter the updated customer by the updated column. For example if you only need to index customers with a changed firstname. It is always a good idea to filter the entities as much as possible to save performance.
  * The `update()` can also be used to update data that has always to be changed synchronously.
* `public function handle(EntityIndexingMessage $message): void`
  * The `handle()` method handles the messages which were generated in the `self::iterate` or `self::update` function. In the example above a small log entry is written to the database indicating that a customer was indexed. The preferred way to manipulate data here is using the `connection` directly and not to use the DAL. See the [Use DAL functionalities in the indexer](#use-dal-functionalities-in-the-indexer) section for more information.

### Handle messages asynchronously or synchronously

By default, all messages which are returned by the `public function update()` function in the indexer are handled synchronously. That means the `handle()` function is called directly after the `update()` function. To handle the messages asynchronously over the [Message queue](../../../../hosting/infrastructure/message-queue.md) the `EntityIndexingMessage` can be used with different constructor parameters. A closer look at the `EntityIndexingMessage` class shows that it has a fourth parameter named `$forceQueue` which is `false` by default. This parameter can be set to `true` and then the message will be handled asynchronously by the message queue.

### Use DAL functionalities in the indexer

By default, indexing is also active while working with an indexer, which means, that entities that are written over the DAL also trigger `EntityWrittenContainerEvent` events. So the indexers are triggered again. This can lead to an infinite loop. Therefore, the connection should be used directly to alter data in the database. You can find more information about this in the corresponding ADR [when to use plain SQL or the DAL](../../../../../resources/references/adr/2021-05-14-when-to-use-plain-sql-or-dal.md). However, if you want to use the DAL for manipulation data in a data indexer, indexing can be disabled. This can be done by passing adding a flag to the context, as shown in the example below:

```php
public function update(EntityWrittenContainerEvent $event): ?EntityIndexingMessage
{
    $updates = $event->getPrimaryKeys(CustomerDefinition::ENTITY_NAME);

    if (empty($updates)) {
        return null;
    }

    $context = $event->getContext();
    $context->addState(EntityIndexerRegistry::DISABLE_INDEXING);

    return new EntityIndexingMessage(array_values($updates), null, $context);
}
```

## Index data using existing events

There are already a bunch of indexers in shopware that you can use. If you take a look at the `CustomerIndexer` or `CategoryIndexer` classes for example, you will see that they dispatch an event in the `handle` method. This should be used for indexing data of the main entities. Among others, the following indexers already exist and dispatch events that can be used for indexing data:

* `CustomerIndexer`
* `CategoryIndexer`
* `LandingPageIndexer`
* `ProductIndexer`
* `ProductStreamIndexer`
* `PromotionIndexer`
* `RuleIndexer`
* `MediaIndexer`
* `MediaFolderIndexer`
* `MediaFolderConfigurationIndexer`
* `SalesChannelIndexer`
* `BreadcrumpIndexer`

### Subscribe to an indexer event

A new subscriber is necessary. Refer to the [Listening to Events](../event/listening-to-events.md) guide for more details about subscribers.

In this example a new entry is written to the `log_entry` database table indicating that a customer was updated:

```php
// <plugin root>/src/Service/Subscriber.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Doctrine\DBAL\Connection;
use Shopware\Core\Checkout\Customer\Event\CustomerIndexerEvent;
use Shopware\Core\Framework\DataAbstractionLayer\Doctrine\MultiInsertQueryQueue;
use Shopware\Core\Framework\Uuid\Uuid;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class Subscriber implements EventSubscriberInterface
{
    /**
     * @var Connection
     */
    private Connection $connection;

    public function __construct(Connection $connection)
    {
        $this->connection = $connection;
    }

    public static function getSubscribedEvents(): array
    {
        return [
//            CustomerIndexerEvent::class => 'onCustomerIndexerHandle'
        ];
    }

    public function onCustomerIndexerHandle(CustomerIndexerEvent $customerIndexerEvent)
    {
        $queue = new MultiInsertQueryQueue($this->connection);
        foreach ($customerIndexerEvent->getIds() as $id) {
            $this->addLog($id, $queue);
        }
        $queue->execute();
    }

    private function addLog($customerId, MultiInsertQueryQueue $queue)
    {
        $queue->addInsert('log_entry', [
            'id' => Uuid::randomBytes(),
            'message' => 'Updated customer with id: ' . $customerId,
            'level' => 1,
            'channel' => 'debug'
        ]);
    }
}
```

The service definition for the subscriber would look like this.

```php
<?php declare(strict_types=1);

use Doctrine\DBAL\Connection;
use Swag\BasicExample\Service\Subscriber;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(Subscriber::class)
        ->args([service(Connection::class)])
        ->tag('kernel.event_subscriber');
};
```

It is recommended to work directly with the `Connection` since the event is dispatched in the context of an indexer. If we would use the Data Abstraction Layer (DAL) for writing changes to the database, the indexer would be triggered again, because it listens for `EntityWrittenContainerEvent` events. This would lead to an infinite loop. Using the `Connection` directly prevents the DAL from dispatching entity written events. Also the performance of plain sql is much higher, which is very important for indexers in general.

---

---
url: /docs/v6.5/guides/plugins/plugins/framework/data-handling/add-data-indexer.md
---
# Adding Data Indexer

## Overview

Data indexer are used to optimize the performance of recurring complex tasks. One good example to understand the benefit of data indexer would be the cheapest price calculation within Shopware. Every product has a `cheapest_price` column in the database which should contain the cheapest price a product has. The calculation of this column can be complex, because a product can have several variants with advanced pricing rules and so on. This makes the calculation more difficult and would take too much time when reading 25 products for a listing. To optimize the performance there is a data indexer that calculates the cheapest price of a product every time the product is updated by the DAL. This means that no new calculation has to be performed when a product is read, and performance during reading is significantly increased. Furthermore data indexer can make use of the [Message queue](../../../../hosting/infrastructure/message-queue) to handle the calculations asynchronously.

## Prerequisites

This guide is built upon the [Plugin base guide](../../plugin-base-guide), but any plugin will work here. Just note that all examples are using the plugin mentioned above. In order to create data indexer you should have read the [Adding custom complex data guide](./add-custom-complex-data).

## Adding an own data indexer

It is possible to add data indexer for your own entities, like the one created in the [Adding custom complex data](./add-custom-complex-data) guide or for existing entities. However, if you want to react on changes of existing entities the preferred way should be subscribing to the events if available. See the [Index data using existing events](#index-data-using-existing-events) section below. To create a new indexer, just create a new class in your plugin:

```php
// <plugin root>/src/Core/Framework/DataAbstractionLayer/Indexing/ExampleIndexer.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Framework\DataAbstractionLayer\Indexing;

use Doctrine\DBAL\Connection;
use Shopware\Core\Checkout\Customer\CustomerDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Dbal\Common\IteratorFactory;
use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\DataAbstractionLayer\Event\EntityWrittenContainerEvent;
use Shopware\Core\Framework\DataAbstractionLayer\Indexing\EntityIndexer;
use Shopware\Core\Framework\DataAbstractionLayer\Indexing\EntityIndexingMessage;
use Shopware\Core\Framework\Uuid\Uuid;

class ExampleIndexer extends EntityIndexer
{
    private IteratorFactory $iteratorFactory;

    private EntityRepository $repository;

    private Connection $connection;

    public function __construct(
        IteratorFactory $iteratorFactory,
        EntityRepository $repository,
        Connection $connection
    ) {
        $this->iteratorFactory = $iteratorFactory;
        $this->repository = $repository;
        $this->connection = $connection;
    }

    /**
     * Returns a unique name for this indexer.
     */
    public function getName(): string
    {
        return 'swag.basic.example.indexer';
    }

    /**
     * Called when a full entity index is required. This function should generate a list of message for all records which
     * are indexed by this indexer.
     */

    public function iterate($offset): ?EntityIndexingMessage
    {
        $iterator = $this->iteratorFactory->createIterator($this->repository->getDefinition(), $offset);

        $ids = $iterator->fetch();

        if (empty($ids)) {
            return null;
        }

        return new EntityIndexingMessage(array_values($ids), $iterator->getOffset());
    }

    /**
     * Called when entities are updated over the DAL. This function should react to the provided entity written events
     * and generate a list of messages which has to be processed by the `handle` function over the message queue workers.
     */
    public function update(EntityWrittenContainerEvent $event): ?EntityIndexingMessage
    {
        $updates = $event->getPrimaryKeys(CustomerDefinition::ENTITY_NAME);

        if (empty($updates)) {
            return null;
        }

        return new EntityIndexingMessage(array_values($updates), null, $event->getContext());
    }

    /**
     * Called over the message queue workers. The messages are the generated messages
     * of the `self::iterate` or `self::update` functions.
     */
    public function handle(EntityIndexingMessage $message): void
    {
        $ids = $message->getData();

        if (!$ids) {
            return;
        }

        foreach ($ids as $id) {
            $this->writeLog($id);
        }
    }

    private function writeLog($customerId)
    {
        $this->connection->executeStatement('INSERT INTO `log_entry` (`id`, `message`, `level`, `channel`, `created_at`) VALUES (:id, :message, :level, :channel, now())', [
            'id' => Uuid::randomBytes(),
            'message' => 'Indexed customer with id: ' . $customerId,
            'level' => 1,
            'channel' => 'debug'
        ]);
    }
}
```

With the corresponding service registration:

```xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
                <service id="Swag\BasicExample\Core\Framework\DataAbstractionLayer\Indexing\ExampleIndexer">
                    <argument type="service" id="Shopware\Core\Framework\DataAbstractionLayer\Dbal\Common\IteratorFactory"/>
                    <argument type="service" id="customer.repository"/>
                    <argument type="service" id="Doctrine\DBAL\Connection" />
                    <tag name="shopware.entity_indexer"/>
                </service>
    </services>
</container>
```

The indexer service has to be tagged as `shopware.entity_indexer` in order to work.

Let's take a closer look at the functions of the entity indexer class.

* `public function getName(): string`:
  * This function returns the name of the indexer and should be unique. It is used in the `EntityIndexerRegistry` to identify which messages should be handled by which indexer.
* `public function iterate($offset): ?EntityIndexingMessage`:
  * This function is called when a full entity indexing was requested. This is for example the case if the console command `bin/console dal:refresh:index` is used or if a user of the Administration requested an update of all indexes in the settings.
    It should generate a list of messages for all records which are indexed by this indexer. In the example documentation above, the customer entity should be indexed. Therefore, the `Shopware\Core\Framework\DataAbstractionLayer\Dbal\Common\IteratorFactory` is used to fetch customer ids. The offset is used to reduce the amount of data which is processed at once.
* `public function update(EntityWrittenContainerEvent $event): ?EntityIndexingMessage`:
  * This function is called when entities are updated over the DAL. This function should react to the provided entity written events and generate a list of messages which has to be processed by the `handle` function. In the example implementation above, we get all customer identifiers that have been updated by `$updates = $event->getPrimaryKeys(CustomerDefinition::ENTITY_NAME);`. A closer look at the `EntityWrittenContainerEvent` class is also good idea. It is for example possible to filter the updated customer by the updated column. For example if you only need to index customers with a changed firstname. It is always a good idea to filter the entities as much as possible to save performance.
  * The `update()` can also be used to update data that has always to be changed synchronously.
* `public function handle(EntityIndexingMessage $message): void`
  * The `handle()` method handles the messages which were generated in the `self::iterate` or `self::update` function. In the example above a small log entry is written to the database indicating that a customer was indexed. The preferred way to manipulate data here is using the `connection` directly and not to use the DAL. See the section \[Use DAL functionalities in the indexer]\(Use DAL functionalities in the indexer) for more information.

### Handle messages asynchronously or synchronously

By default, all messages which are returned by the `public function update()` function in the indexer are handled synchronously. That means the `handle()` function is called directly after the `update()` function. To handle the messages asynchronously over the [Message queue](../../../../hosting/infrastructure/message-queue) the `EntityIndexingMessage` can be used with different constructor parameters. A closer look at the `EntityIndexingMessage` class shows that it has a fourth parameter named `$forceQueue` which is `false` by default. This parameter can be set to `true` and then the message will be handled asynchronously by the message queue.

### Use DAL functionalities in the indexer

By default, indexing is also active while working with an indexer, which means, that entities that are written over the DAL also trigger `EntityWrittenContainerEvent` events. So the indexers are triggered again. This can lead to an infinite loop. Therefore, the connection should be used directly to alter data in the database. You can find more information about this in the corresponding ADR [when to use plain SQL or the DAL](../../../../../resources/references/adr/2021-05-14-when-to-use-plain-sql-or-dal.md). However, if you want to use the DAL for manipulation data in a data indexer, indexing can be disabled. This can be done by passing adding a flag to the context, as shown in the example below:

```php
public function update(EntityWrittenContainerEvent $event): ?EntityIndexingMessage
{
    $updates = $event->getPrimaryKeys(CustomerDefinition::ENTITY_NAME);

    if (empty($updates)) {
        return null;
    }

    $context = $event->getContext();
    $context->addState(EntityIndexerRegistry::DISABLE_INDEXING);

    return new EntityIndexingMessage(array_values($updates), null, $context);
}
```

## Index data using existing events

There are already a bunch of indexers in shopware that you can use. If you take a look at the `CustomerIndexer` or `CategoryIndexer` classes for example, you will see that they dispatch an event in the `handle` method. This should be used for indexing data of the main entities. Among others, the following indexers already exist and dispatch events that can be used for indexing data:

* `CustomerIndexer`
* `CategoryIndexer`
* `LandingPageIndexer`
* `ProductIndexer`
* `ProductStreamIndexer`
* `PromotionIndexer`
* `RuleIndexer`
* `MediaIndexer`
* `MediaFolderIndexer`
* `MediaFolderConfigurationIndexer`
* `SalesChannelIndexer`
* `BreadcrumpIndexer`

### Subscribe to an indexer event

For this we need a new subscriber. If you are not familiar with a subscriber, have a look at our [Listening to events](../../plugin-fundamentals/listening-to-events) guide. For this example, we just write a new entry to the `log_entry` database table, indicating that a customer was updated.

```php
// <plugin root>/src/Service/Subscriber.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Doctrine\DBAL\Connection;
use Shopware\Core\Checkout\Customer\Event\CustomerIndexerEvent;
use Shopware\Core\Framework\DataAbstractionLayer\Doctrine\MultiInsertQueryQueue;
use Shopware\Core\Framework\Uuid\Uuid;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class Subscriber implements EventSubscriberInterface
{
    /**
     * @var Connection
     */
    private Connection $connection;

    public function __construct(Connection $connection)
    {
        $this->connection = $connection;
    }

    public static function getSubscribedEvents(): array
    {
        return [
//            CustomerIndexerEvent::class => 'onCustomerIndexerHandle'
        ];
    }

    public function onCustomerIndexerHandle(CustomerIndexerEvent $customerIndexerEvent)
    {
        $queue = new MultiInsertQueryQueue($this->connection);
        foreach ($customerIndexerEvent->getIds() as $id) {
            $this->addLog($id, $queue);
        }
        $queue->execute();
    }

    private function addLog($customerId, MultiInsertQueryQueue $queue)
    {
        $queue->addInsert('log_entry', [
            'id' => Uuid::randomBytes(),
            'message' => 'Updated customer with id: ' . $customerId,
            'level' => 1,
            'channel' => 'debug'
        ]);
    }
}
```

The service definition for the subscriber would look like this.

```xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Service\Subscriber" >
            <argument type="service" id="Doctrine\DBAL\Connection" />
            <tag name="kernel.event_subscriber" />
        </service>
    </services>
</container>
```

It is recommended to work directly with the `Connection` since the event is dispatched in the context of an indexer. If we would use the Data Abstraction Layer (DAL) for writing changes to the database, the indexer  would be triggered again, because it listens for `EntityWrittenContainerEvent` events. This would lead to an infinite loop. Using the `Connection` directly prevents the DAL from dispatching entity written events. Also the performance of plain sql is much higher, which is very important for indexers in general.

---

---
url: /docs/v6.6/guides/plugins/plugins/framework/data-handling/add-data-indexer.md
---
# Adding Data Indexer

## Overview

Data indexer are used to optimize the performance of recurring complex tasks. One good example to understand the benefit of data indexer would be the cheapest price calculation within Shopware. Every product has a `cheapest_price` column in the database which should contain the cheapest price a product has. The calculation of this column can be complex, because a product can have several variants with advanced pricing rules and so on. This makes the calculation more difficult and would take too much time when reading 25 products for a listing. To optimize the performance there is a data indexer that calculates the cheapest price of a product every time the product is updated by the DAL. This means that no new calculation has to be performed when a product is read, and performance during reading is significantly increased. Furthermore data indexer can make use of the [Message queue](../../../../hosting/infrastructure/message-queue) to handle the calculations asynchronously.

## Prerequisites

This guide is built upon the [Plugin base guide](../../plugin-base-guide), but any plugin will work here. Just note that all examples are using the plugin mentioned above. In order to create data indexer you should have read the [Adding custom complex data guide](./add-custom-complex-data).

## Adding an own data indexer

It is possible to add data indexer for your own entities, like the one created in the [Adding custom complex data](./add-custom-complex-data) guide or for existing entities. However, if you want to react on changes of existing entities the preferred way should be subscribing to the events if available. See the [Index data using existing events](#index-data-using-existing-events) section below. To create a new indexer, just create a new class in your plugin:

```php
// <plugin root>/src/Core/Framework/DataAbstractionLayer/Indexing/ExampleIndexer.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Framework\DataAbstractionLayer\Indexing;

use Doctrine\DBAL\Connection;
use Shopware\Core\Checkout\Customer\CustomerDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Dbal\Common\IteratorFactory;
use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\DataAbstractionLayer\Event\EntityWrittenContainerEvent;
use Shopware\Core\Framework\DataAbstractionLayer\Indexing\EntityIndexer;
use Shopware\Core\Framework\DataAbstractionLayer\Indexing\EntityIndexingMessage;
use Shopware\Core\Framework\Uuid\Uuid;

class ExampleIndexer extends EntityIndexer
{
    private IteratorFactory $iteratorFactory;

    private EntityRepository $repository;

    private Connection $connection;

    public function __construct(
        IteratorFactory $iteratorFactory,
        EntityRepository $repository,
        Connection $connection
    ) {
        $this->iteratorFactory = $iteratorFactory;
        $this->repository = $repository;
        $this->connection = $connection;
    }

    /**
     * Returns a unique name for this indexer.
     */
    public function getName(): string
    {
        return 'swag.basic.example.indexer';
    }

    /**
     * Called when a full entity index is required. This function should generate a list of message for all records which
     * are indexed by this indexer.
     */

    public function iterate($offset): ?EntityIndexingMessage
    {
        $iterator = $this->iteratorFactory->createIterator($this->repository->getDefinition(), $offset);

        $ids = $iterator->fetch();

        if (empty($ids)) {
            return null;
        }

        return new EntityIndexingMessage(array_values($ids), $iterator->getOffset());
    }

    /**
     * Called when entities are updated over the DAL. This function should react to the provided entity written events
     * and generate a list of messages which has to be processed by the `handle` function over the message queue workers.
     */
    public function update(EntityWrittenContainerEvent $event): ?EntityIndexingMessage
    {
        $updates = $event->getPrimaryKeys(CustomerDefinition::ENTITY_NAME);

        if (empty($updates)) {
            return null;
        }

        return new EntityIndexingMessage(array_values($updates), null, $event->getContext());
    }

    /**
     * Called over the message queue workers. The messages are the generated messages
     * of the `self::iterate` or `self::update` functions.
     */
    public function handle(EntityIndexingMessage $message): void
    {
        $ids = $message->getData();

        if (!$ids) {
            return;
        }

        foreach ($ids as $id) {
            $this->writeLog($id);
        }
    }

    private function writeLog($customerId)
    {
        $this->connection->executeStatement('INSERT INTO `log_entry` (`id`, `message`, `level`, `channel`, `created_at`) VALUES (:id, :message, :level, :channel, now())', [
            'id' => Uuid::randomBytes(),
            'message' => 'Indexed customer with id: ' . $customerId,
            'level' => 1,
            'channel' => 'debug'
        ]);
    }
}
```

With the corresponding service registration:

```xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
                <service id="Swag\BasicExample\Core\Framework\DataAbstractionLayer\Indexing\ExampleIndexer">
                    <argument type="service" id="Shopware\Core\Framework\DataAbstractionLayer\Dbal\Common\IteratorFactory"/>
                    <argument type="service" id="customer.repository"/>
                    <argument type="service" id="Doctrine\DBAL\Connection" />
                    <tag name="shopware.entity_indexer"/>
                </service>
    </services>
</container>
```

The indexer service has to be tagged as `shopware.entity_indexer` in order to work.

Let's take a closer look at the functions of the entity indexer class.

* `public function getName(): string`:
  * This function returns the name of the indexer and should be unique. It is used in the `EntityIndexerRegistry` to identify which messages should be handled by which indexer.
* `public function iterate($offset): ?EntityIndexingMessage`:
  * This function is called when a full entity indexing was requested. This is for example the case if the console command `bin/console dal:refresh:index` is used or if a user of the Administration requested an update of all indexes in the settings.
    It should generate a list of messages for all records which are indexed by this indexer. In the example documentation above, the customer entity should be indexed. Therefore, the `Shopware\Core\Framework\DataAbstractionLayer\Dbal\Common\IteratorFactory` is used to fetch customer ids. The offset is used to reduce the amount of data which is processed at once.
* `public function update(EntityWrittenContainerEvent $event): ?EntityIndexingMessage`:
  * This function is called when entities are updated over the DAL. This function should react to the provided entity written events and generate a list of messages which has to be processed by the `handle` function. In the example implementation above, we get all customer identifiers that have been updated by `$updates = $event->getPrimaryKeys(CustomerDefinition::ENTITY_NAME);`. A closer look at the `EntityWrittenContainerEvent` class is also good idea. It is for example possible to filter the updated customer by the updated column. For example if you only need to index customers with a changed firstname. It is always a good idea to filter the entities as much as possible to save performance.
  * The `update()` can also be used to update data that has always to be changed synchronously.
* `public function handle(EntityIndexingMessage $message): void`
  * The `handle()` method handles the messages which were generated in the `self::iterate` or `self::update` function. In the example above a small log entry is written to the database indicating that a customer was indexed. The preferred way to manipulate data here is using the `connection` directly and not to use the DAL. See the section \[Use DAL functionalities in the indexer]\(Use DAL functionalities in the indexer) for more information.

### Handle messages asynchronously or synchronously

By default, all messages which are returned by the `public function update()` function in the indexer are handled synchronously. That means the `handle()` function is called directly after the `update()` function. To handle the messages asynchronously over the [Message queue](../../../../hosting/infrastructure/message-queue) the `EntityIndexingMessage` can be used with different constructor parameters. A closer look at the `EntityIndexingMessage` class shows that it has a fourth parameter named `$forceQueue` which is `false` by default. This parameter can be set to `true` and then the message will be handled asynchronously by the message queue.

### Use DAL functionalities in the indexer

By default, indexing is also active while working with an indexer, which means, that entities that are written over the DAL also trigger `EntityWrittenContainerEvent` events. So the indexers are triggered again. This can lead to an infinite loop. Therefore, the connection should be used directly to alter data in the database. You can find more information about this in the corresponding ADR [when to use plain SQL or the DAL](../../../../../resources/references/adr/2021-05-14-when-to-use-plain-sql-or-dal.md). However, if you want to use the DAL for manipulation data in a data indexer, indexing can be disabled. This can be done by passing adding a flag to the context, as shown in the example below:

```php
public function update(EntityWrittenContainerEvent $event): ?EntityIndexingMessage
{
    $updates = $event->getPrimaryKeys(CustomerDefinition::ENTITY_NAME);

    if (empty($updates)) {
        return null;
    }

    $context = $event->getContext();
    $context->addState(EntityIndexerRegistry::DISABLE_INDEXING);

    return new EntityIndexingMessage(array_values($updates), null, $context);
}
```

## Index data using existing events

There are already a bunch of indexers in shopware that you can use. If you take a look at the `CustomerIndexer` or `CategoryIndexer` classes for example, you will see that they dispatch an event in the `handle` method. This should be used for indexing data of the main entities. Among others, the following indexers already exist and dispatch events that can be used for indexing data:

* `CustomerIndexer`
* `CategoryIndexer`
* `LandingPageIndexer`
* `ProductIndexer`
* `ProductStreamIndexer`
* `PromotionIndexer`
* `RuleIndexer`
* `MediaIndexer`
* `MediaFolderIndexer`
* `MediaFolderConfigurationIndexer`
* `SalesChannelIndexer`
* `BreadcrumpIndexer`

### Subscribe to an indexer event

For this we need a new subscriber. If you are not familiar with a subscriber, have a look at our [Listening to events](../../plugin-fundamentals/listening-to-events) guide. For this example, we just write a new entry to the `log_entry` database table, indicating that a customer was updated.

```php
// <plugin root>/src/Service/Subscriber.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Doctrine\DBAL\Connection;
use Shopware\Core\Checkout\Customer\Event\CustomerIndexerEvent;
use Shopware\Core\Framework\DataAbstractionLayer\Doctrine\MultiInsertQueryQueue;
use Shopware\Core\Framework\Uuid\Uuid;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class Subscriber implements EventSubscriberInterface
{
    /**
     * @var Connection
     */
    private Connection $connection;

    public function __construct(Connection $connection)
    {
        $this->connection = $connection;
    }

    public static function getSubscribedEvents(): array
    {
        return [
//            CustomerIndexerEvent::class => 'onCustomerIndexerHandle'
        ];
    }

    public function onCustomerIndexerHandle(CustomerIndexerEvent $customerIndexerEvent)
    {
        $queue = new MultiInsertQueryQueue($this->connection);
        foreach ($customerIndexerEvent->getIds() as $id) {
            $this->addLog($id, $queue);
        }
        $queue->execute();
    }

    private function addLog($customerId, MultiInsertQueryQueue $queue)
    {
        $queue->addInsert('log_entry', [
            'id' => Uuid::randomBytes(),
            'message' => 'Updated customer with id: ' . $customerId,
            'level' => 1,
            'channel' => 'debug'
        ]);
    }
}
```

The service definition for the subscriber would look like this.

```xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Service\Subscriber" >
            <argument type="service" id="Doctrine\DBAL\Connection" />
            <tag name="kernel.event_subscriber" />
        </service>
    </services>
</container>
```

It is recommended to work directly with the `Connection` since the event is dispatched in the context of an indexer. If we would use the Data Abstraction Layer (DAL) for writing changes to the database, the indexer  would be triggered again, because it listens for `EntityWrittenContainerEvent` events. This would lead to an infinite loop. Using the `Connection` directly prevents the DAL from dispatching entity written events. Also the performance of plain sql is much higher, which is very important for indexers in general.

---

---
url: /docs/guides/plugins/plugins/framework/data-handling/add-data-translations.md
---

# Adding Data Translations

## Overview

In this guide you'll learn how to add translations to entities.

When reading translated data later, prefer `entity.translated.field` in storefront and sales-channel contexts, and use the plain `entity.field` in Admin/CRUD flows where you need the value stored for the current language. See [Plain vs translated entity fields](../../../../../concepts/framework/translations/plain-vs-translated-fields.md).

## Prerequisites

This guide is built upon the [Plugin base guide](../../plugin-base-guide), but any plugin will work here. Just note that all examples are using the plugin mentioned above.

In order to create data translations you need an existing entity, as this guide is based on the [Adding custom complex data](add-custom-complex-data) guide, you should have a look at it first.

::: info
Refer to this video on **[Translating your entity](https://www.youtube.com/watch?v=FfqxfQl3I4w)** that deals with data translations. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

## Creating the migration

We'll start with creating a new database table. Make sure to use the name of your entity appending `_translation`.

In this guide we'll name our table `swag_example_translation` since our entity is named `swag_example`.

The translation table's columns should be the following:

This is how your migration could look like:

```php
// <plugin root>/src/Migration/Migration1612863838ExampleTranslation.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Framework\Migration\MigrationStep;

class Migration1612863838ExampleTranslation extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1612863838;
    }

    public function update(Connection $connection): void
    {
        $query = <<<SQL
CREATE TABLE IF NOT EXISTS `swag_example_translation` (
    `swag_example_id` BINARY(16) NOT NULL,
    `language_id` BINARY(16) NOT NULL,
    `name` VARCHAR(255),
    `created_at` DATETIME(3) NOT NULL,
    `updated_at` DATETIME(3) NULL,
    PRIMARY KEY (`swag_example_id`, `language_id`),
    CONSTRAINT `fk.swag_example_translation.swag_example_id` FOREIGN KEY (`swag_example_id`)
        REFERENCES `swag_example` (`id`) ON DELETE CASCADE ON UPDATE CASCADE,
    CONSTRAINT `fk.swag_example_translation.language_id` FOREIGN KEY (`language_id`)
        REFERENCES `language` (`id`) ON DELETE CASCADE ON UPDATE CASCADE
)
    ENGINE = InnoDB
    DEFAULT CHARSET = utf8mb4
    COLLATE = utf8mb4_unicode_ci;
SQL;
        $connection->executeStatement($query);
    }
}
```

## Creating the translation entity

The translation is an aggregation to the `ExampleEntity`. Therefore, you should place it into the `<plugin root>/src/Core/Content/Example/Aggregate` directory. In this directory we create a subdirectory called `ExampleTranslation` where we create a new definition for our translation which is called `ExampleTranslation`.

### EntityDefinition class

Now we can start creating our `ExampleTranslationDefinition` which extends from `Shopware\Core\Framework\DataAbstractionLayer\EntityTranslationDefinition`. Special for entity translation is, that we have to override a method called `getParentDefinitionClass` which returns the definition class of our entity we want to translate. In this case it's `ExampleDefinition`.

```php
// <plugin root>/src/Core/Content/Example/Aggregate/ExampleTranslation/ExampleTranslationDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\Aggregate\ExampleTranslation;

use Shopware\Core\Framework\DataAbstractionLayer\EntityTranslationDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
use Shopware\Core\Framework\DataAbstractionLayer\Field\StringField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;
use Swag\BasicExample\Core\Content\Example\ExampleDefinition;

class ExampleTranslationDefinition extends EntityTranslationDefinition
{
    public const ENTITY_NAME = 'swag_example_translation';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    public function getParentDefinitionClass(): string
    {
        return ExampleDefinition::class;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new StringField('name', 'name'))->addFlags(new Required()),
        ]);
    }
}
```

As you can see, we've implemented a `StringField` for the `name` column, the other fields like the `language_id` will be automatically added by the `EntityTranslationDefinition` since they are base fields of it.

All that's left to do now, is to introduce your `ExampleTranslationDefinition` to Shopware by registering your class in your `services.php` file and by using the `shopware.entity.definition` tag, because Shopware 6 is looking for definitions this way. Note, that we have to register the translation after the entity we want to translate.

Here's the `services.php` as it should look like:

```php
// <plugin root>/src/Resources/config/services.php
<?php declare(strict_types=1);

use Swag\BasicExample\Core\Content\Example\ExampleDefinition;
use Swag\BasicExample\Core\Content\Example\Aggregate\ExampleTranslation\ExampleTranslationDefinition;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(ExampleDefinition::class)
        ->tag('shopware.entity.definition', ['entity' => 'swag_example']);

    $services->set(ExampleTranslationDefinition::class)
        ->tag('shopware.entity.definition', ['entity' => 'swag_example_translation']);
};
```

### Entity class

So far we introduced our definition, we can create our `ExampleTranslationEntity`. Our entity has to extend from the `Shopware\Core\Framework\DataAbstractionLayer\TranslationEntity` which comes with some getters and setters for the the `language_id`. We only have to add three properties here, one for the `example_id`, one for the actual name and one for the association to the `ExampleEntity`. All of those properties need a getter and a setter again, so add those too.

Here's our `ExampleTranslationEntity`:

```php
// <plugin root>/src/Core/Content/Example/Aggregate/ExampleTranslation/ExampleTranslationEntity.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\Aggregate\ExampleTranslation;

use Shopware\Core\Framework\DataAbstractionLayer\TranslationEntity;
use Swag\BasicExample\Core\Content\Example\ExampleEntity;

class ExampleTranslationEntity extends TranslationEntity
{
    protected string $exampleId;

    protected ?string $name;

    protected ExampleEntity $example;

    public function getExampleId(): string
    {
        return $this->exampleId;
    }

    public function setExampleId(string $exampleId): void
    {
        $this->exampleId = $exampleId;
    }

    public function getName(): ?string
    {
        return $this->name;
    }

    public function setName(string $name): void
    {
        $this->name = $name;
    }

    public function getExample(): ExampleEntity
    {
        return $this->example;
    }

    public function setExample(ExampleEntity $example): void
    {
        $this->example = $example;
    }
}
```

Now we need our translation definition to know its custom entity class. This is done by overriding the method `getEntityClass` in our `ExampleTranslationDefinition`.

```php
// <plugin root>/src/Core/Content/Example/Aggregate/ExampleTranslation/ExampleTranslationDefinition.php
class ExampleTranslationDefinition extends EntityTranslationDefinition
{
    [...]

    public function getEntityClass(): string
    {
        return ExampleTranslationEntity::class;
    }
}
```

### EntityCollection

As we already know, we should create an `EntityCollection` for our `Entity` too. For entity translations it is the same way as for normal entities.

Our collection class could then look like this:

```php
// <plugin root>/src/Core/Content/Example/Aggregate/ExampleTranslation/ExampleTranslationCollection.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\Aggregate\ExampleTranslation;

use Shopware\Core\Framework\DataAbstractionLayer\EntityCollection;

/**
 * @method void                          add(ExampleTranslationEntity $entity)
 * @method void                          set(string $key, ExampleTranslationEntity $entity)
 * @method ExampleTranslationEntity[]    getIterator()
 * @method ExampleTranslationEntity[]    getElements()
 * @method ExampleTranslationEntity|null get(string $key)
 * @method ExampleTranslationEntity|null first()
 * @method ExampleTranslationEntity|null last()
 */
class ExampleTranslationCollection extends EntityCollection
{
    protected function getExpectedClass(): string
    {
        return ExampleTranslationEntity::class;
    }
}
```

### Main Entity Class

The main entity class, that is the class with the field(s) we are going to translate, must define:

* a `TranslatedField` for the “name” field
* a `TranslationsAssociationField`, with a reference to the ExampleTranslationDefinition

```php
// <plugin root>/src/Core/Content/Example/ExampleDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example;

use ...

class ExampleDefinition extends EntityDefinition
{
    public const ENTITY_NAME = 'example';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    [...]

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new PrimaryKey(), new ApiAware(), new Required()),
            (new StringField('not_translated_field', 'notTranslatedField'))->addFlags(new ApiAware()),
            (new TranslatedField('name'))->addFlags(new ApiAware(), new Required()),
            (new TranslationsAssociationField(
                ExampleTranslationDefinition::class,
                'swag_example_id'
            ))->addFlags(new ApiAware(), new Required())
        ]);
    }
}
```

---

---
url: >-
  /docs/v6.5/guides/plugins/plugins/framework/data-handling/add-data-translations.md
---

# Adding Data Translations

## Overview

In this guide you'll learn how to add translations to entities.

## Prerequisites

This guide is built upon the [Plugin base guide](../../plugin-base-guide), but any plugin will work here. Just note that all examples are using the plugin mentioned above.

In order to create data translations you need an existing entity, as this guide is based on the [Adding custom complex data](add-custom-complex-data) guide, you should have a look at it first.

::: info
Refer to this video on **[Translating your entity](https://www.youtube.com/watch?v=FfqxfQl3I4w)** that deals with data translations. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

## Creating the migration

We'll start with creating a new database table. Make sure to use the name of your entity appending `_translation`.

In this guide we'll name our table `swag_example_translation` since our entity is named `swag_example`.

The translation table's columns should be the following:

This is how your migration could look like:

```php
// <plugin root>/src/Migration/Migration1612863838ExampleTranslation.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Framework\Migration\MigrationStep;

class Migration1612863838ExampleTranslation extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1612863838;
    }

    public function update(Connection $connection): void
    {
        $query = <<<SQL
CREATE TABLE IF NOT EXISTS `swag_example_translation` (
    `swag_example_id` BINARY(16) NOT NULL,
    `language_id` BINARY(16) NOT NULL,
    `name` VARCHAR(255),
    `created_at` DATETIME(3) NOT NULL,
    `updated_at` DATETIME(3) NULL,
    PRIMARY KEY (`swag_example_id`, `language_id`),
    CONSTRAINT `fk.swag_example_translation.swag_example_id` FOREIGN KEY (`swag_example_id`)
        REFERENCES `swag_example` (`id`) ON DELETE CASCADE ON UPDATE CASCADE,
    CONSTRAINT `fk.swag_example_translation.language_id` FOREIGN KEY (`language_id`)
        REFERENCES `language` (`id`) ON DELETE CASCADE ON UPDATE CASCADE
)
    ENGINE = InnoDB
    DEFAULT CHARSET = utf8mb4
    COLLATE = utf8mb4_unicode_ci;
SQL;
        $connection->executeStatement($query);
    }

    public function updateDestructive(Connection $connection): void
    {
    }
}
```

## Creating the translation entity

The translation is an aggregation to the `ExampleEntity`. Therefore, you should place it into the `<plugin root>/src/Core/Content/Example/Aggregate` directory. In this directory we create a subdirectory called `ExampleTranslation` where we create a new definition for our translation which is called `ExampleTranslation`.

### EntityDefinition class

Now we can start creating our `ExampleTranslationDefinition` which extends from `Shopware\Core\Framework\DataAbstractionLayer\EntityTranslationDefinition`. Special for entity translation is, that we have to override a method called `getParentDefinitionClass` which returns the definition class of our entity we want to translate. In this case it's `ExampleDefinition`.

```php
// <plugin root>/src/Core/Content/Example/Aggregate/ExampleTranslation/ExampleTranslationDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\Aggregate\ExampleTranslation;

use Shopware\Core\Framework\DataAbstractionLayer\EntityTranslationDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
use Shopware\Core\Framework\DataAbstractionLayer\Field\StringField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;
use Swag\BasicExample\Core\Content\Example\ExampleDefinition;

class ExampleTranslationDefinition extends EntityTranslationDefinition
{
    public const ENTITY_NAME = 'swag_example_translation';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    public function getParentDefinitionClass(): string
    {
        return ExampleDefinition::class;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new StringField('name', 'name'))->addFlags(new Required()),
        ]);
    }
}
```

As you can see, we've implemented a `StringField` for the `name` column, the other fields like the `language_id` will be automatically added by the `EntityTranslationDefinition` since they are base fields of it.

All that's left to do now, is to introduce your `ExampleTranslationDefinition` to Shopware by registering your class in your `services.xml` file and by using the `shopware.entity.definition` tag, because Shopware 6 is looking for definitions this way. Note, that we have to register the translation after the entity we want to translate.

Here's the `services.xml` as it should look like:

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Core\Content\Example\ExampleDefinition">
            <tag name="shopware.entity.definition" entity="swag_example" />
        </service>

        <service id="Swag\BasicExample\Core\Content\Example\Aggregate\ExampleTranslation\ExampleTranslationDefinition">
            <tag name="shopware.entity.definition" entity="swag_example_translation" />
        </service>
    </services>
</container>
```

### Entity class

So far we introduced our definition, we can create our `ExampleTranslationEntity`. Our entity has to extend from the `Shopware\Core\Framework\DataAbstractionLayer\TranslationEntity` which comes with some getters and setters for the the `language_id`. We only have to add three properties here, one for the `example_id`, one for the actual name and one for the association to the `ExampleEntity`. All of those properties need a getter and a setter again, so add those too.

Here's our `ExampleTranslationEntity`:

```php
// <plugin root>/src/Core/Content/Example/Aggregate/ExampleTranslation/ExampleTranslationEntity.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\Aggregate\ExampleTranslation;

use Shopware\Core\Framework\DataAbstractionLayer\TranslationEntity;
use Swag\BasicExample\Core\Content\Example\ExampleEntity;

class ExampleTranslationEntity extends TranslationEntity
{
    protected string $exampleId;

    protected ?string $name;

    protected ExampleEntity $example;

    public function getExampleId(): string
    {
        return $this->exampleId;
    }

    public function setExampleId(string $exampleId): void
    {
        $this->exampleId = $exampleId;
    }

    public function getName(): ?string
    {
        return $this->name;
    }

    public function setName(string $name): void
    {
        $this->name = $name;
    }

    public function getExample(): ExampleEntity
    {
        return $this->example;
    }

    public function setExample(ExampleEntity $example): void
    {
        $this->example = $example;
    }
}
```

Now we need our translation definition to know its custom entity class. This is done by overriding the method `getEntityClass` in our `ExampleTranslationDefinition`.

```php
// <plugin root>/src/Core/Content/Example/Aggregate/ExampleTranslation/ExampleTranslationDefinition.php
class ExampleTranslationDefinition extends EntityTranslationDefinition
{
    [...]

    public function getEntityClass(): string
    {
        return ExampleTranslationEntity::class;
    }
}
```

### EntityCollection

As we already know, we should create an `EntityCollection` for our `Entity` too. For entity translations it is the same way as for normal entities.

Our collection class could then look like this:

```php
// <plugin root>/src/Core/Content/Example/Aggregate/ExampleTranslation/ExampleTranslationCollection.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\Aggregate\ExampleTranslation;

use Shopware\Core\Framework\DataAbstractionLayer\EntityCollection;

/**
 * @method void                          add(ExampleTranslationEntity $entity)
 * @method void                          set(string $key, ExampleTranslationEntity $entity)
 * @method ExampleTranslationEntity[]    getIterator()
 * @method ExampleTranslationEntity[]    getElements()
 * @method ExampleTranslationEntity|null get(string $key)
 * @method ExampleTranslationEntity|null first()
 * @method ExampleTranslationEntity|null last()
 */
class ExampleTranslationCollection extends EntityCollection
{
    protected function getExpectedClass(): string
    {
        return ExampleTranslationEntity::class;
    }
}
```

### Main Entity Class

The main entity class, that is the class with the field(s) we are going to translate, must define:

* a `TranslatedField` for the “name” field
* a `TranslationsAssociationField`, with a reference to the ExampleTranslationDefinition

```php
// <plugin root>/src/Core/Content/Example/ExampleDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example;

use ...

class ExampleDefinition extends EntityDefinition
{
    public const ENTITY_NAME = 'example';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    [...]

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new PrimaryKey(), new ApiAware(), new Required()),
            (new StringField('not_translated_field', 'notTranslatedField'))->addFlags(new ApiAware()),
            (new TranslatedField('name'))->addFlags(new ApiAware(), new Required()),
            (new TranslationsAssociationField(
                ExampleTranslationDefinition::class,
                'swag_example_id'
            ))->addFlags(new ApiAware(), new Required())
        ]);
    }
}
```

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/framework/data-handling/add-data-translations.md
---

# Adding Data Translations

## Overview

In this guide you'll learn how to add translations to entities.

## Prerequisites

This guide is built upon the [Plugin base guide](../../plugin-base-guide), but any plugin will work here. Just note that all examples are using the plugin mentioned above.

In order to create data translations you need an existing entity, as this guide is based on the [Adding custom complex data](add-custom-complex-data) guide, you should have a look at it first.

::: info
Refer to this video on **[Translating your entity](https://www.youtube.com/watch?v=FfqxfQl3I4w)** that deals with data translations. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

## Creating the migration

We'll start with creating a new database table. Make sure to use the name of your entity appending `_translation`.

In this guide we'll name our table `swag_example_translation` since our entity is named `swag_example`.

The translation table's columns should be the following:

This is how your migration could look like:

```php
// <plugin root>/src/Migration/Migration1612863838ExampleTranslation.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Framework\Migration\MigrationStep;

class Migration1612863838ExampleTranslation extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1612863838;
    }

    public function update(Connection $connection): void
    {
        $query = <<<SQL
CREATE TABLE IF NOT EXISTS `swag_example_translation` (
    `swag_example_id` BINARY(16) NOT NULL,
    `language_id` BINARY(16) NOT NULL,
    `name` VARCHAR(255),
    `created_at` DATETIME(3) NOT NULL,
    `updated_at` DATETIME(3) NULL,
    PRIMARY KEY (`swag_example_id`, `language_id`),
    CONSTRAINT `fk.swag_example_translation.swag_example_id` FOREIGN KEY (`swag_example_id`)
        REFERENCES `swag_example` (`id`) ON DELETE CASCADE ON UPDATE CASCADE,
    CONSTRAINT `fk.swag_example_translation.language_id` FOREIGN KEY (`language_id`)
        REFERENCES `language` (`id`) ON DELETE CASCADE ON UPDATE CASCADE
)
    ENGINE = InnoDB
    DEFAULT CHARSET = utf8mb4
    COLLATE = utf8mb4_unicode_ci;
SQL;
        $connection->executeStatement($query);
    }

    public function updateDestructive(Connection $connection): void
    {
    }
}
```

## Creating the translation entity

The translation is an aggregation to the `ExampleEntity`. Therefore, you should place it into the `<plugin root>/src/Core/Content/Example/Aggregate` directory. In this directory we create a subdirectory called `ExampleTranslation` where we create a new definition for our translation which is called `ExampleTranslation`.

### EntityDefinition class

Now we can start creating our `ExampleTranslationDefinition` which extends from `Shopware\Core\Framework\DataAbstractionLayer\EntityTranslationDefinition`. Special for entity translation is, that we have to override a method called `getParentDefinitionClass` which returns the definition class of our entity we want to translate. In this case it's `ExampleDefinition`.

```php
// <plugin root>/src/Core/Content/Example/Aggregate/ExampleTranslation/ExampleTranslationDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\Aggregate\ExampleTranslation;

use Shopware\Core\Framework\DataAbstractionLayer\EntityTranslationDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
use Shopware\Core\Framework\DataAbstractionLayer\Field\StringField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;
use Swag\BasicExample\Core\Content\Example\ExampleDefinition;

class ExampleTranslationDefinition extends EntityTranslationDefinition
{
    public const ENTITY_NAME = 'swag_example_translation';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    public function getParentDefinitionClass(): string
    {
        return ExampleDefinition::class;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new StringField('name', 'name'))->addFlags(new Required()),
        ]);
    }
}
```

As you can see, we've implemented a `StringField` for the `name` column, the other fields like the `language_id` will be automatically added by the `EntityTranslationDefinition` since they are base fields of it.

All that's left to do now, is to introduce your `ExampleTranslationDefinition` to Shopware by registering your class in your `services.xml` file and by using the `shopware.entity.definition` tag, because Shopware 6 is looking for definitions this way. Note, that we have to register the translation after the entity we want to translate.

Here's the `services.xml` as it should look like:

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Core\Content\Example\ExampleDefinition">
            <tag name="shopware.entity.definition" entity="swag_example" />
        </service>

        <service id="Swag\BasicExample\Core\Content\Example\Aggregate\ExampleTranslation\ExampleTranslationDefinition">
            <tag name="shopware.entity.definition" entity="swag_example_translation" />
        </service>
    </services>
</container>
```

### Entity class

So far we introduced our definition, we can create our `ExampleTranslationEntity`. Our entity has to extend from the `Shopware\Core\Framework\DataAbstractionLayer\TranslationEntity` which comes with some getters and setters for the the `language_id`. We only have to add three properties here, one for the `example_id`, one for the actual name and one for the association to the `ExampleEntity`. All of those properties need a getter and a setter again, so add those too.

Here's our `ExampleTranslationEntity`:

```php
// <plugin root>/src/Core/Content/Example/Aggregate/ExampleTranslation/ExampleTranslationEntity.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\Aggregate\ExampleTranslation;

use Shopware\Core\Framework\DataAbstractionLayer\TranslationEntity;
use Swag\BasicExample\Core\Content\Example\ExampleEntity;

class ExampleTranslationEntity extends TranslationEntity
{
    protected string $exampleId;

    protected ?string $name;

    protected ExampleEntity $example;

    public function getExampleId(): string
    {
        return $this->exampleId;
    }

    public function setExampleId(string $exampleId): void
    {
        $this->exampleId = $exampleId;
    }

    public function getName(): ?string
    {
        return $this->name;
    }

    public function setName(string $name): void
    {
        $this->name = $name;
    }

    public function getExample(): ExampleEntity
    {
        return $this->example;
    }

    public function setExample(ExampleEntity $example): void
    {
        $this->example = $example;
    }
}
```

Now we need our translation definition to know its custom entity class. This is done by overriding the method `getEntityClass` in our `ExampleTranslationDefinition`.

```php
// <plugin root>/src/Core/Content/Example/Aggregate/ExampleTranslation/ExampleTranslationDefinition.php
class ExampleTranslationDefinition extends EntityTranslationDefinition
{
    [...]

    public function getEntityClass(): string
    {
        return ExampleTranslationEntity::class;
    }
}
```

### EntityCollection

As we already know, we should create an `EntityCollection` for our `Entity` too. For entity translations it is the same way as for normal entities.

Our collection class could then look like this:

```php
// <plugin root>/src/Core/Content/Example/Aggregate/ExampleTranslation/ExampleTranslationCollection.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example\Aggregate\ExampleTranslation;

use Shopware\Core\Framework\DataAbstractionLayer\EntityCollection;

/**
 * @method void                          add(ExampleTranslationEntity $entity)
 * @method void                          set(string $key, ExampleTranslationEntity $entity)
 * @method ExampleTranslationEntity[]    getIterator()
 * @method ExampleTranslationEntity[]    getElements()
 * @method ExampleTranslationEntity|null get(string $key)
 * @method ExampleTranslationEntity|null first()
 * @method ExampleTranslationEntity|null last()
 */
class ExampleTranslationCollection extends EntityCollection
{
    protected function getExpectedClass(): string
    {
        return ExampleTranslationEntity::class;
    }
}
```

### Main Entity Class

The main entity class, that is the class with the field(s) we are going to translate, must define:

* a `TranslatedField` for the “name” field
* a `TranslationsAssociationField`, with a reference to the ExampleTranslationDefinition

```php
// <plugin root>/src/Core/Content/Example/ExampleDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Content\Example;

use ...

class ExampleDefinition extends EntityDefinition
{
    public const ENTITY_NAME = 'example';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    [...]

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new PrimaryKey(), new ApiAware(), new Required()),
            (new StringField('not_translated_field', 'notTranslatedField'))->addFlags(new ApiAware()),
            (new TranslatedField('name'))->addFlags(new ApiAware(), new Required()),
            (new TranslationsAssociationField(
                ExampleTranslationDefinition::class,
                'swag_example_id'
            ))->addFlags(new ApiAware(), new Required())
        ]);
    }
}
```

---

---
url: /resources/admin-extension-sdk/develop/entity-types.md
---

# Adding Entity Types (TypeScript)

The Meteor Admin SDK supports TypeScript typings for Shopware entities. Adding entity types enables type-safe access, editing, and saving of entities when working with repositories.

To enable typings, create a global declaration file such as `global.d.ts` and extend the `EntitySchema` namespace.

## Option 1: Use Shopware’s generated entity types (recommended)

Shopware provides generated TypeScript definitions for all core entities.

Install the package that matches your Shopware version:

```bash
npm install @shopware-ag/entity-schema-types@5.0.0
```

The package version corresponds to the Shopware version without the leading `6.`. Examples:

`Shopware 6.5.0.0` → `@shopware-ag/entity-schema-types@5.0.0`
`Shopware 6.5.1.2` → `@shopware-ag/entity-schema-types@5.1.2`
`Shopware 6.6.3.1` → `@shopware-ag/entity-schema-types@6.3.1`

Then import the types in your global declaration file:

```ts
// global.d.ts
import '@shopware-ag/entity-schema-types';
```

## Option 2: Use a fallback `any` type

This is the simplest solution, but it removes type safety. If strict typing isn't required, it's possible to define a fallback type for all entities by setting the type to `any`:

```ts
// global.d.ts
declare namespace EntitySchema {
    interface Entities {
        [entityName: string]: any;
    }
}
```

This avoids type errors but disables type safety.

## Option 3: Define custom entity types

This option provides full control by defining entity types manually for each property and association. The drawback is the additional effort required to maintain the definitions.

```ts
// global.d.ts
declare namespace EntitySchema {
    interface Entities {
        // using product_manufacturer as an example
        product_manufacturer: product_manufacturer;
        // in this case 'media', 'product' and 'product_manufacturer_translation' is also needed
        ...
    }

    interface product_manufacturer {
        id: string;
        versionId: string;
        mediaId?: string;
        link?: string;
        name: string;
        description?: string;
        customFields?: unknown;
        /* 
        * Entity and EntityCollection is defined in the namespace and can directly be used.
        * The value in the generic (here 'media', 'product' and 'product_manufacturer_translation') must
        * also be defined in this file.
        */ 
        media?: Entity<'media'>;
        products?: EntityCollection<'product'>;
        translations: EntityCollection<'product_manufacturer_translation'>;
        createdAt: string;
        updatedAt?: string;
        translated?: {name?: string, description?: string, customFields?: unknown};
    }

    ...
}
```

It is necessary to define types for any referenced entities, such as:

* `media`
* `product`
* `product_manufacturer_translation`

---

---
url: /docs/v6.5/guides/plugins/plugins/administration/add-error-handling.md
---

# Adding error handling

​

## Overview

The Shopware 6 Administration stores API errors in the [Vuex store](https://vuex.vuejs.org/). There they are centrally accessible to your components, with a flat data structure looking like this:

```text
(state)
 |- entityNameA
    |- id1
        |- property1
        |- property2
        ...
    |- id2
        |- property1
        |- property2
        ...
 |- entityNameB
   ...
```

In this guide you will learn how to access this error store directly or via one of the provided helper functions. ​

## Read errors from the store

​ Errors can be read from the store by calling the getter method `getApiErrorFromPath`. ​

```javascript
function getApiErrorFromPath (state) => (entityName, id, path)
```

​ In there, the parameter `path` is an `array` representing the nested property names of your entity.

Also we provide a wrapper which can also handle nested fields in object notation, being much easier to use for scalar fields: ​

```javascript
function getApiError(state) => (entity, field)
```

​ For example, an empty product name would result in an error with the path `product.name`, instead of having the array `['product', 'name']` present.

In your Vue component, use computed properties to avoid flooding your templates with store calls. ​

```javascript
computed: {
    propertyError() {
        return this.$store.getters.getApiError(myEntity, 'myFieldName');
    },
    nestedpropertyError() {
        return this.$store.getters.getApiError(myEntity, 'myFieldName.nested');
    }
}
```

Those computed properties can then be used in your templates the familiar way:

```html
<div>
    <sw-field ... :error="propertyError"></sw-field>
</div>
```

​

### The mapErrors Service

​ Like every Vuex mapping, fetching the errors from the store may be very repetitive and error-prone. Because of this we provide you an Vuex like mapper function: ​

```javascript
mapPropertyErrors(subject, properties)
```

​ Here, the `subject` parameter is the entity name (not the entity itself) and `properties` is an array of the properties you want to map. You can spread its result to create computed properties in your component. The functions returned by the mapper are named like a camelCase representation of your input, suffixed with `Error`.

This is an example from the `sw-product-basic-form` component: ​

```javascript
const { mapPropertyErrors } = Shopware.Component.getComponentHelper();

Component.register('sw-product-basic-form', {
    computed: {
        ...mapPropertyErrors('product', [
            'name',
            'description',
            'productNumber',
            'manufacturerId',
            'active',
            'markAsTopseller'
        ])
    }
})
```

Which then are bound to the inputs like this:

```html
<sw-field type="text" v-model="product.name" :error="productNameError">
```

​

### Error configuration for pages

​ When working with nested views, you need a way to tell the user that an error occurred on another view, e.g in another `tab`. For this you can write a config for your `sw-page` component which looks like seen below: ​

```json
{
  "sw.product.detail.base": {
    "product": [
      "taxId",
      "price",
      "stock",
      "manufacturerId",
      "name"
    ]
  },
  "sw.product.detail.cross.selling": {
    "product_cross_selling": [
      "name",
      "type",
      "position"
    ]
  }
}
```

​ This can then directly imported and used in the `mapPageError` computed property:

```javascript
import errorConfiguration from './error.cfg.json';

const { mapPageErrors } = Shopware.Component.getComponentHelper();

Shopware.Component.register('sw-product-detail', {
    computed: {
        ...mapPageErrors(errorConfiguration),
    }
}
```

This makes it possible to indicate if one or more errors exists, in another view or a tab:

```html
<sw-tabs
    :hasError="swProductDetailBaseError">
</sw-tabs>
```

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/administration/permissions-error-handling/add-error-handling.md
---

# Adding error handling

​

## Overview

The Shopware 6 Administration stores API errors in the [Vuex store](https://vuex.vuejs.org/). There they are centrally accessible to your components, with a flat data structure looking like this:

```text
(state)
 |- entityNameA
    |- id1
        |- property1
        |- property2
        ...
    |- id2
        |- property1
        |- property2
        ...
 |- entityNameB
   ...
```

In this guide you will learn how to access this error store directly or via one of the provided helper functions. ​

## Read errors from the store

​ Errors can be read from the store by calling the getter method `getApiErrorFromPath`. ​

```javascript
function getApiErrorFromPath (state) => (entityName, id, path)
```

​ In there, the parameter `path` is an `array` representing the nested property names of your entity.

Also we provide a wrapper which can also handle nested fields in object notation, being much easier to use for scalar fields: ​

```javascript
function getApiError(state) => (entity, field)
```

​ For example, an empty product name would result in an error with the path `product.name`, instead of having the array `['product', 'name']` present.

In your Vue component, use computed properties to avoid flooding your templates with store calls. ​

```javascript
computed: {
    propertyError() {
        return this.$store.getters.getApiError(myEntity, 'myFieldName');
    },
    nestedpropertyError() {
        return this.$store.getters.getApiError(myEntity, 'myFieldName.nested');
    }
}
```

Those computed properties can then be used in your templates the familiar way:

```html
<div>
    <sw-field ... :error="propertyError"></sw-field>
</div>
```

​

### The mapErrors Service

​ Like every Vuex mapping, fetching the errors from the store may be very repetitive and error-prone. Because of this we provide you an Vuex like mapper function: ​

```javascript
mapPropertyErrors(subject, properties)
```

​ Here, the `subject` parameter is the entity name (not the entity itself) and `properties` is an array of the properties you want to map. You can spread its result to create computed properties in your component. The functions returned by the mapper are named like a camelCase representation of your input, suffixed with `Error`.

This is an example from the `sw-product-basic-form` component: ​

```javascript
const { mapPropertyErrors } = Shopware.Component.getComponentHelper();

Component.register('sw-product-basic-form', {
    computed: {
        ...mapPropertyErrors('product', [
            'name',
            'description',
            'productNumber',
            'manufacturerId',
            'active',
            'markAsTopseller'
        ])
    }
})
```

Which then are bound to the inputs like this:

```html
<sw-field type="text" v-model="product.name" :error="productNameError">
```

​

### Error configuration for pages

​ When working with nested views, you need a way to tell the user that an error occurred on another view, e.g in another `tab`. For this you can write a config for your `sw-page` component which looks like seen below: ​

```json
{
  "sw.product.detail.base": {
    "product": [
      "taxId",
      "price",
      "stock",
      "manufacturerId",
      "name"
    ]
  },
  "sw.product.detail.cross.selling": {
    "product_cross_selling": [
      "name",
      "type",
      "position"
    ]
  }
}
```

​ This can then directly imported and used in the `mapPageError` computed property:

```javascript
import errorConfiguration from './error.cfg.json';

const { mapPageErrors } = Shopware.Component.getComponentHelper();

Shopware.Component.register('sw-product-detail', {
    computed: {
        ...mapPageErrors(errorConfiguration),
    }
}
```

This makes it possible to indicate if one or more errors exists, in another view or a tab:

```html
<sw-tabs
    :hasError="swProductDetailBaseError">
</sw-tabs>
```

---

---
url: >-
  /docs/guides/plugins/plugins/administration/permissions-error-handling/add-error-handling.md
---

# Adding Error Handling

## Overview

The Shopware 6 Administration stores API errors in the [Vuex store](https://vuex.vuejs.org/). There they are centrally accessible to your components, with a flat data structure looking like this:

```text
(state)
 |- entityNameA
    |- id1
        |- property1
        |- property2
        ...
    |- id2
        |- property1
        |- property2
        ...
 |- entityNameB
   ...
```

In this guide you will learn how to access this error store directly or via one of the provided helper functions. ​

## Read errors from the store

​ Errors can be read from the store by calling the getter method `getApiErrorFromPath`. ​

```javascript
function getApiErrorFromPath (state) => (entityName, id, path)
```

​ In there, the parameter `path` is an `array` representing the nested property names of your entity.

Also we provide a wrapper which can also handle nested fields in object notation, being much easier to use for scalar fields: ​

```javascript
function getApiError(state) => (entity, field)
```

​ For example, an empty product name would result in an error with the path `product.name`, instead of having the array `['product', 'name']` present.

In your Vue component, use computed properties to avoid flooding your templates with store calls. ​

```javascript
computed: {
    propertyError() {
        return this.$store.getters.getApiError(myEntity, 'myFieldName');
    },
    nestedpropertyError() {
        return this.$store.getters.getApiError(myEntity, 'myFieldName.nested');
    }
}
```

Those computed properties can then be used in your templates the familiar way:

```html
<div>
    <sw-field ... :error="propertyError"></sw-field>
</div>
```

​

### The mapErrors Service

​ Like every Vuex mapping, fetching the errors from the store may be very repetitive and error-prone. Because of this we provide you an Vuex like mapper function: ​

```javascript
mapPropertyErrors(subject, properties)
```

​ Here, the `subject` parameter is the entity name (not the entity itself) and `properties` is an array of the properties you want to map. You can spread its result to create computed properties in your component. The functions returned by the mapper are named like a camelCase representation of your input, suffixed with `Error`.

This is an example from the `sw-product-basic-form` component: ​

```javascript
const { mapPropertyErrors } = Shopware.Component.getComponentHelper();

Component.register('sw-product-basic-form', {
    computed: {
        ...mapPropertyErrors('product', [
            'name',
            'description',
            'productNumber',
            'manufacturerId',
            'active',
            'markAsTopseller'
        ])
    }
})
```

Which then are bound to the inputs like this:

```html
<sw-field type="text" v-model="product.name" :error="productNameError">
```

​

### Error configuration for pages

​ When working with nested views, you need a way to tell the user that an error occurred on another view, e.g in another `tab`. For this you can write a config for your `sw-page` component which looks like seen below: ​

```json
{
  "sw.product.detail.base": {
    "product": [
      "taxId",
      "price",
      "stock",
      "manufacturerId",
      "name"
    ]
  },
  "sw.product.detail.cross.selling": {
    "product_cross_selling": [
      "name",
      "type",
      "position"
    ]
  }
}
```

​ This can then directly imported and used in the `mapPageError` computed property:

```javascript
import errorConfiguration from './error.cfg.json';

const { mapPageErrors } = Shopware.Component.getComponentHelper();

Shopware.Component.register('sw-product-detail', {
    computed: {
        ...mapPageErrors(errorConfiguration),
    }
}
```

This makes it possible to indicate if one or more errors exists, in another view or a tab:

```html
<sw-tabs
    :hasError="swProductDetailBaseError">
</sw-tabs>
```

---

---
url: /docs/guides/plugins/plugins/administration/mixins-directives/add-mixins.md
---

# Adding Mixins

## Overview

This documentation chapter will cover how to add a new Administration mixin for your plugin. In general, mixins behave the same as they do in Vue normally, differing only in the registration and the way mixins are included in a component. If you want an overview over the shopware provided mixins look at them here: [Using Mixins](using-mixins.md).

## Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files and a running plugin. Of course you'll have to understand JavaScript, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation. As stated before mixins in Shopware are basically the same as in Vue, so you should have read their [documentation](https://v2.vuejs.org/v2/guide/mixins.html?redirect=true) on them first.

## Register a new Mixin

For this example, we'll just use the example mixin from the [VueJS documentation](https://v2.vuejs.org/v2/guide/mixins.html?redirect=true) and adjust it to be used in Shopware.

Mixins in Shopware have to be registered in the mixin registry via the `Mixin.register` function to be available everywhere in the Administration.

Converting the Vue mixin to be used in Shopware looks like the example seen below:

```javascript
// <administration root>/mixins/swag-basic-example.js
// get the Mixin property of the shopware object
const { Mixin } = Shopware;

// give the mixin a name and feed it into the register function as the second argument
Mixin.register('swag-basic-mixin', {
    created: function () {
        this.hello()
    },
    methods: {
        hello: function () {
            console.log('hello from mixin!')
        }
    }
});
```

## Importing the Mixin in the Plugin

Now that we have registered the mixin, we need to import it *before importing our components* in the `main.js` file.

```javascript
// <administration root>/src/main.js
import '<administration root>/mixins/swag-basic-example.js'
    
// importing components...
```

## Using the Mixin

After registering our mixin under a name, we can get it from the registry with the `Mixin.getByName` function and inject it into our component as seen below.

```javascript
// <administration root>/components/swag-basic-example/index.js
const { Component, Mixin } = Shopware;

Component.register('swag-basic-example', {

    mixins: [
        Mixin.getByName('swag-basic-mixin')
    ],
});
```

This can also be done with Shopware provided mixins, learn more about them here: [Using Mixins](using-mixins.md)

## More interesting topics

* [Adding filters](../services-utilities/add-filter.md)
* [Using utility functions](../services-utilities/using-utils.md)

---

---
url: /docs/v6.5/guides/plugins/plugins/administration/add-mixins.md
---

# Adding Mixins

## Overview

This documentation chapter will cover how to add a new Administration mixin for your plugin. In general, mixins behave the same as they do in Vue normally, differing only in the registration and the way mixins are included in a component. If you want an overview over the shopware provided mixins look at them here: [Using Mixins](using-mixins).

## Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files and a running plugin. Of course you'll have to understand JavaScript, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation. As stated before mixins in Shopware are basically the same as in Vue, so you should have read their [documentation](https://vuejs.org/v2/guide/mixins.html) on them first.

## Register a new Mixin

For this example, we'll just use the example mixin from the [VueJS documentation](https://vuejs.org/v2/guide/mixins.html) and adjust it to be used in Shopware.

Mixins in Shopware have to be registered in the mixin registry via the `Mixin.register` function to be available everywhere in the Administration.

Converting the Vue mixin to be used in Shopware looks like the example seen below:

```javascript
// <administration root>/mixins/swag-basic-example.js
// get the Mixin property of the shopware object
const { Mixin } = Shopware;

// give the mixin a name and feed it into the register function as the second argument
Mixin.register('swag-basic-mixin', {
    created: function () {
        this.hello()
    },
    methods: {
        hello: function () {
            console.log('hello from mixin!')
        }
    }
});
```

## Importing the Mixin in the Plugin

Now that we have registered the mixin, we need to import it *before importing our components* in the `main.js` file.

```javascript
// <administration root>/src/main.js
import '<administration root>/mixins/swag-basic-example.js'
    
// importing components...
```

## Using the Mixin

After registering our mixin under a name, we can get it from the registry with the `Mixin.getByName` function and inject it into our component as seen below.

```javascript
// <administration root>/components/swag-basic-example/index.js
const { Component, Mixin } = Shopware;

Component.register('swag-basic-example', {

    mixins: [
        Mixin.getByName('swag-basic-mixin')
    ],
});
```

This can also be done with Shopware provided mixins, learn more about them here: [Using Mixins](using-mixins)

## More interesting topics

* [Adding filters](add-filter)
* [Using utils](using-utils)

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/administration/mixins-directives/add-mixins.md
---

# Adding Mixins

## Overview

This documentation chapter will cover how to add a new Administration mixin for your plugin. In general, mixins behave the same as they do in Vue normally, differing only in the registration and the way mixins are included in a component. If you want an overview over the shopware provided mixins look at them here: [Using Mixins](using-mixins.md).

## Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files and a running plugin. Of course you'll have to understand JavaScript, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation. As stated before mixins in Shopware are basically the same as in Vue, so you should have read their [documentation](https://vuejs.org/v2/guide/mixins.html) on them first.

## Register a new Mixin

For this example, we'll just use the example mixin from the [VueJS documentation](https://vuejs.org/v2/guide/mixins.html) and adjust it to be used in Shopware.

Mixins in Shopware have to be registered in the mixin registry via the `Mixin.register` function to be available everywhere in the Administration.

Converting the Vue mixin to be used in Shopware looks like the example seen below:

```javascript
// <administration root>/mixins/swag-basic-example.js
// get the Mixin property of the shopware object
const { Mixin } = Shopware;

// give the mixin a name and feed it into the register function as the second argument
Mixin.register('swag-basic-mixin', {
    created: function () {
        this.hello()
    },
    methods: {
        hello: function () {
            console.log('hello from mixin!')
        }
    }
});
```

## Importing the Mixin in the Plugin

Now that we have registered the mixin, we need to import it *before importing our components* in the `main.js` file.

```javascript
// <administration root>/src/main.js
import '<administration root>/mixins/swag-basic-example.js'
    
// importing components...
```

## Using the Mixin

After registering our mixin under a name, we can get it from the registry with the `Mixin.getByName` function and inject it into our component as seen below.

```javascript
// <administration root>/components/swag-basic-example/index.js
const { Component, Mixin } = Shopware;

Component.register('swag-basic-example', {

    mixins: [
        Mixin.getByName('swag-basic-mixin')
    ],
});
```

This can also be done with Shopware provided mixins, learn more about them here: [Using Mixins](using-mixins.md)

## More interesting topics

* [Adding filters](../services-utilities/add-filter.md)
* [Using utility functions](../services-utilities/using-utils.md)

---

---
url: /docs/guides/plugins/plugins/dependencies/using-npm-dependencies.md
---

# Adding NPM Dependencies

In this guide, you'll learn how to add NPM dependencies to your plugin.

## Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files and a running plugin. Of course, you'll have to understand JavaScript, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation. Further, a basic understanding of Node and NPM is required.

## Installing an npm package

Presuming you have `npm` installed, run `npm init -y` in the `<plugin root>/src/Resources/app/administration/` folder or the `<plugin root>/src/Resources/app/storefront/` folder. This command creates a `package.json` file in the respective folder, depending on the environment you're working in.

To add a package to the `package.json` file, run the `npm install` command. In this example we will be installing [`missionlog`](https://www.npmjs.com/package/missionlog):

```bash
npm install missionlog
```

## Administration (Shopware 6.7+ with Vite)

Since Shopware 6.7, the Administration build system has been migrated from Webpack to [Vite](https://vite.dev/). With Vite, you no longer need a custom `webpack.config.js` file to use npm packages. Vite resolves npm packages from your plugin's `node_modules` directory automatically using standard Node.js module resolution.

You can import npm packages directly in your code without any additional build configuration:

```javascript
// <plugin root>/src/Resources/app/administration/src/example-component.js
import { log } from 'missionlog';

// Initializing the logger
log.init({ initializer: 'INFO' }, (level, tag, msg, params) => {
    console.log(`${level}: [${tag}] `, msg, ...params);
});
```

If you need custom Vite configuration (for example, path aliases), create a `vite.config.mts` file in the `<plugin root>/src/Resources/app/administration/src/` directory (alongside your entry file, e.g., `main.js`). Note that `package.json` stays in `<plugin root>/src/Resources/app/administration/`:

```typescript
// <plugin root>/src/Resources/app/administration/src/vite.config.mts
import { defineConfig } from 'vite';

export default defineConfig({
    resolve: {
        alias: {
            '@my-module': 'src/my-module',
        },
    },
});
```

Build the Administration using:

```bash
composer build:js:admin
```

For more information on migrating from Webpack to Vite, see the [Webpack to Vite migration guide](../../../upgrades-migrations/administration/vite.md).

## Storefront (Webpack)

The Storefront build system continues to use [Webpack](https://webpack.js.org/). To make Webpack aware of the npm packages installed in your plugin, create a `webpack.config.js` file in the `<plugin root>/src/Resources/app/storefront/build/` directory:

```javascript
// <plugin root>/src/Resources/app/storefront/build/webpack.config.js
module.exports = (params) => {
    return {
        resolve: {
            modules: [
                `${params.basePath}/Resources/app/storefront/node_modules`,
            ],
        }
    };
}
```

This tells Webpack to also search for modules in your plugin's `node_modules` folder, in addition to Shopware's own `node_modules`.

### Using the dependency in the Storefront

Once you have installed all the dependencies and registered the plugin's `node_modules` path in the build system, you can import and use the package in your code:

```javascript
// <plugin root>/src/Resources/app/storefront/src/example.plugin.js
const { PluginBaseClass } = window;

// Import logger
import { log } from 'missionlog';

// Initializing the logger
log.init({ initializer: 'INFO' }, (level, tag, msg, params) => {
    console.log(`${level}: [${tag}] `, msg, ...params);
});

// The plugin skeleton
export default class ExamplePlugin extends PluginBaseClass {
    init() {
        console.log('init');

        // Use logger
        log.info('initializer', 'example plugin got started', this);
    }
}
```

Register the plugin in your `main.js` file so it can be loaded by the plugin system:

```javascript
// <plugin root>/src/Resources/app/storefront/src/main.js
import ExamplePlugin from './example.plugin';

PluginManager.register(
    'ExamplePlugin',
    ExamplePlugin
);
```

Build the Storefront using:

```bash
shopware-cli project storefront-build
```

## Next steps

Now that you know how to include new `npm` dependencies you might want to create a service with them. Learn how to do that in this guide: [How to add a custom-service](../administration/services-utilities/add-custom-service.md)

If you want to add [Composer dependencies](using-composer-dependencies.md), or even other [plugin dependencies](add-plugin-dependencies.md), we've got you covered as well.

---

---
url: >-
  /docs/v6.5/guides/plugins/plugins/plugin-fundamentals/using-npm-dependencies.md
---

# Adding NPM Dependencies

In this guide you'll learn how add NPM dependencies to your project.

## Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files and a running plugin. Of course you'll have to understand JavaScript, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation. Further a basic understanding of Node and NPM is required.

## Video

This guide is also available as a video:

## Adding a npm package to the Administration or the Storefront

Presuming you have `npm` installed, run `npm init -y` in the `<plugin root>src/Resources/app/administration/` folder or the `<plugin root>src/Resources/app/storefront/` folder. This command creates a `package.json` file in the respective folder, depending on the environment you're working in. To add a package to the `package.json` file simply run the `npm install` command. In this example we will be installing [`missionlog`](https://www.npmjs.com/package/missionlog).

So in order to install `missionlog`, run `npm install missionlog` in the folder you have created your `package.json` file in.

## Registering a package in the build system

Shopware's storefront as well as administration is based on the build system [Webpack](https://webpack.js.org/). Webpack is a source file bundler: In essence it bundles all the source files into a single `bundle.js` to be shipped to a browser. So in order to make Webpack aware of the new dependency, we have to register it and give it an alias/pseudonym so that the package can be bundled correctly.

To do this we create a new folder called "build" under either `Resources/app/storefront` or `Resources/app/administration`. In this build folder we create a new file with the name `webpack.config.js`. We thereby make it possible to extend the Webpack configuration of Shopware.

```javascript
// <plugin root>/src/Resources/app/storefront/build/webpack.config.js
const { join, resolve } = require('path'); 
module.exports = () => { 
    return { 
        resolve: { 
           alias: { 
               '@missionlog': resolve( 
                    join(__dirname, '..', 'node_modules', 'missionlog') 
               ) 
           } 
       } 
   }; 
}
```

Let us take a closer look at the code. In the first line, we import the two functions `join` and `resolve` for the path module of Node.js. In the second line, we export a so-called arrow function. The build system from Shopware calls this function when either the Administration or Storefront is being built.

After that, there comes the exciting part for us: registering the alias. The alias for `missionlog` is given the prefix `@`, so it is possible to recognize later on in the source files. We will use the result of the two functions of the path module previously imported as a value.

We proceed from the inside to the outside. We use [`join`](https://nodejs.org/api/path.html#path_path_join_paths) to reflect the path to the package inside the `node_modules` folder. The `node_modules` folder contains all the packages that we have installed via `npm install`. After we identified the relevant path to the package, we use the [`resolve`](https://nodejs.org/api/path.html#path_path_resolve_paths) function to transform this path into an absolute path.

## Using the dependency

Once we have installed all the dependencies and registered the package in the build system with an alias, we can use the package in our own code.

```javascript
// <plugin root>/src/Resources/app/storefront/src/main.js
import Plugin from 'src/plugin-system/plugin.class';

// Import logger
import { log } from '@missionlog';

// Initializing the logger
log.init({ initializer: 'INFO' }, (level, tag, msg, params) => {
    console.log(`${level}: [${tag}] `, msg, ...params);
});

// The plugin skeleton
export default class ExamplePlugin extends Plugin {
    init() {
        console.log('init');

        // Use logger
        log.info('initializer', 'example plugin got started', this);
    }
}
```

We import the function log as well as the constants tag via `destructuring` in the specified code. Through the use of the alias, we keep the paths short and recognize that this is an alias at first glance via the prefix.

The final step in this process is to build your Storefront or Administration so that your changes are processed by Webpack.

## Next steps

Now that you know how to include new `npm` dependencies you might want to create a service with them. Learn how to do that in this guide: [How to add a custom-service](../administration/add-custom-service)

If you want to add [Composer dependencies](using-composer-dependencies), or even other [plugin dependencies](add-plugin-dependencies), we've got you covered as well.

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/plugin-fundamentals/using-npm-dependencies.md
---

# Adding NPM Dependencies

In this guide, you'll learn how to add NPM dependencies to your project.

## Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files and a running plugin. Of course, you'll have to understand JavaScript, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation. Further, a basic understanding of Node and NPM is required.

## Video

This guide is also available as a video:

::: warning
This video shows how to resolve the NPM package name as an alias. We recommend resolving all node\_modules instead like shown in the code example below.
:::

## Adding a npm package to the Administration or the Storefront

Presuming you have `npm` installed, run `npm init -y` in the `<plugin root>src/Resources/app/administration/` folder or the `<plugin root>src/Resources/app/storefront/` folder. This command creates a `package.json` file in the respective folder, depending on the environment you're working in. To add a package to the `package.json` file simply run the `npm install` command. In this example we will be installing [`missionlog`](https://www.npmjs.com/package/missionlog).

So in order to install `missionlog`, run `npm install missionlog` in the folder you have created your `package.json` file in.

## Registering a package in the build system

Shopware's storefront as well as administration is based on the build system [Webpack](https://webpack.js.org/). Webpack is a source file bundler: In essence it bundles all the source files into a single `bundle.js` to be shipped to a browser. So in order to make Webpack aware of the new dependency, we have to register it and give it an alias/pseudonym so that the package can be bundled correctly.

To do this, we create a new folder called "build" under either `Resources/app/storefront` or `Resources/app/administration`. In this build folder we create a new file with the name `webpack.config.js`. We thereby make it possible to extend the Webpack configuration of Shopware.

```javascript
module.exports = (params) => {
    return { 
        resolve: { 
            modules: [
                `${params.basePath}/Resources/app/storefront/node_modules`,
            ],
       } 
   }; 
}
```

Let us take a closer look at the code. In the first line, we export a so-called arrow function. The build system from Shopware calls this function when either the Administration or Storefront is being built.

Now we add the `node_modules` folder from our extension. `resolve.modules` tells webpack what directories should be searched when resolving modules. By default, the shopware webpack config only considers the `node_modules` folder of the platform. By accessing `params.basePath` we get the absolute path to our extension. We then add the rest of the path to our extensions `node_modules`. Now webpack will also search for modules in our `node_modules` folder.

## Using the dependency

Once we have installed all the dependencies and registered the package in the build system, we can use the package in our own code.

```javascript
// <plugin root>/src/Resources/app/storefront/src/example.plugin.js
const { PluginBaseClass } = window;

// Import logger
import { log } from 'missionlog';

// Initializing the logger
log.init({ initializer: 'INFO' }, (level, tag, msg, params) => {
    console.log(`${level}: [${tag}] `, msg, ...params);
});

// The plugin skeleton
export default class ExamplePlugin extends PluginBaseClass {
    init() {
        console.log('init');

        // Use logger
        log.info('initializer', 'example plugin got started', this);
    }
}
```

We import the function log as well as the constants tag via `destructuring` in the specified code and register our above plugin in our main.js file, so it can be loaded by the plugin system.

```javascript
// <plugin root>/src/Resources/app/storefront/src/main.js
import ExamplePlugin from './example.plugin';

PluginManager.register(
    'ExamplePlugin',
    ExamplePlugin
);
```

The final step in this process is to build your Storefront or Administration so that your changes are processed by Webpack.

```bash
# Build the Storefront
./bin/build-storefront.sh

# Build the Administration
./bin/build-administration.sh
```

## Next steps

Now that you know how to include new `npm` dependencies you might want to create a service with them. Learn how to do that in this guide: [How to add a custom-service](../administration/add-custom-service)

If you want to add [Composer dependencies](using-composer-dependencies), or even other [plugin dependencies](add-plugin-dependencies), we've got you covered as well.

---

---
url: /docs/v6.5/guides/plugins/plugins/administration/add-acl-rules.md
---

# Adding permissions

## Overview

This guide will teach you how to add Access Control Lists to the Shopware 6 Administration. Access Control Lists or ACL in Shopware ensure that you can create individual roles. These roles have finely granular rights, which every shop operator can set up for themselves. They can be assigned to users.

As an example, let's take a look at a role called 'Editor'. We would assign this role rights to edit products, categories and manufacturers. Now, every user who is a 'Editor' would be able to see and edit the specific areas which are defined in the role.

This documentation chapter will cover the following topics:

* What is an admin privilege
* How to register new admin privileges for your plugin
* How to protect your plugin routes
* How to protect your menu entries
* How to add admin snippets for your privileges
* How you can check in your module at any place if the user has the required rights

Note: ACL Rules in the Administration can be circumnavigated by making direct API calls to your backend.

## Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files and a running plugin. A basic understanding of the [vue router](https://router.vuejs.org/) is also required. Of course you'll have to understand JavaScript, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation.

## Admin privileges

Admin privileges are higher-level permissions that are always determined by an explicit identifier. This is made up of a 'key' and the 'role', connected by a dot: `.`.

A distinction is made here between normal `permissions` and `additional_permissions`. Let's start with the normal permissions.

### Normal permissions

![Permissions GUI](../../../../assets/permissions-gui.png)

`permissions`:

* Key: `product`
* Role: `viewer`
* Identifier (Key + Role): `product.viewer`

The key describes the higher-level admin privilege. For normal `permissions` this is usually the module name, `product` in this case. Other keys could be for example `manufacturer`, `shopping_experiences` or `customers`. The key is used to group the admin privileges, as seen in the picture above.

The role indicates which authorization is given for the key. So four predefined roles are available for the normal `permissions`:

* `viewer`: The viewer is allowed to view entities
* `editor`: The editor is allowed to edit entities
* `creator`: The Creator is allowed to create new entities
* `deleter`: The Deleter is allowed to delete entities

It is important to note that these combinations are not API permissions. They are only intended to enable, disable, deactivate or hide certain elements in the Administration.

For each admin privilege, the needed entity privileges need to be assigned. Depending on the admin privileges, these can be much more complex. This means that for example if a user should be allowed to view reviews, then they also have to be allowed to view customers, products and sales channels.

### Additional permissions

In addition to the normal `permissions`, which represent CRUD functionality, there are also `additional_permissions`. These are intended for all functions that cannot be represented by CRUD.

![Additional permissions GUI](../../../../assets/additionalPermissions-gui.png)

The `additional_permissions` have their own card below the normal permissions grid. An example for `additional_permissions` would be: "clearing the cache". This is an individual action without CRUD functionalities. The key is still used for grouping. Therefore the role can be individual and does not have to follow the scheme.

`additional_permissions`:

* Key: `system`
* Role: `clear_cache`
* Identifier (Key + Role): `system.clear_cache`

## Register admin privilege

The privilege service is used to handle privileges in the Administration. Those privileges will then be displayed in the Users & Permissions module under the roles.

Privileges can be added or extended with the Method `addPrivilegeMappingEntry` of the privilege service:

| Property | Description |
| :--- | :--- |
| category | Where the privilege should be visible in the `permissions` grid or in the `additional_permissions` |
| parent | For nesting and gaining a better overview, you can add a parent key. If the privilege does not have a parent then use `null`. |
| key | All privileges with the same key will be grouped together. For normal `permissions` each role will be in the same row. |
| roles | When category is `permissions`: Use `viewer`, `editor`, `creator` and `deleter`. |
|  | When category is `additional_permissions`: Use a custom key because the additional permissions don´t enforce a structure. |

Each role in roles:

| Property | Description |
| :--- | :--- |
| privileges | You need to add all API permissions here which are required for an working admin privilege. The structure is `entity_name:operation`, e.g. 'product:read'. |
| dependencies | In some cases it is necessary to automatically check another role. To do this, you need to add the identifier, e.g. `product.viewer`. |

Here's an example how this can look like for the review functionality in the Administration:

```javascript
Shopware.Service('privileges')
    .addPrivilegeMappingEntry({
        category: 'permissions',
        parent: 'catalogues',
        key: 'review',
        roles: {
            viewer: {
                privileges: [
                    'product_review:read',
                    'customer:read',
                    'product:read',
                    'sales_channel:read'
                ],
                dependencies: []
            },
            editor: {
                privileges: [
                    'product_review:update'
                ],
                dependencies: [
                    'review.viewer'
                ]
            },
            creator: {
                privileges: [
                    'product_review:create'
                ],
                dependencies: [
                    'review.viewer',
                    'review.editor'
                ]
            },
            deleter: {
                privileges: [
                    'product_review:delete'
                ],
                dependencies: [
                    'review.viewer'
                ]
            }
        }
    });
```

### Adding new, normal permissions

You could use the service at any point in your code. However, it's important that it will be called before the user goes to the roles detail page. For convenience, we recommend this pattern:

```text
- <plugin root>/src/Resources/app/administration/src/<your-component>/
    - acl
        - index.js -> contains permission
    - ...
    - index.js -> import './acl'
```

Now you can use the method `addPrivilegeMappingEntry` to add a new entry:

To add a new mapping for your custom key use the following approach:

```javascript
// <plugin root>/src/Resources/app/administration/src/<your-component>/acl/index.js

Shopware.Service('privileges').addPrivilegeMappingEntry({
    category: 'permissions',
    parent: null,
    key: 'your_key',
    roles: {
        viewer: {
            privileges: [],
            dependencies: []
        },
        editor: {
            privileges: [],
            dependencies: []
        },
        creator: {
            privileges: [],
            dependencies: []
        },
        deleter: {
            privileges: [],
            dependencies: []
        }
    }
});
```

### Extending existing normal permissions

Adding privileges to an existing key can be done like this:

```javascript
// <plugin root>/src/Resources/app/administration/src/acl-override/index.js

Shopware.Service('privileges').addPrivilegeMappingEntry({
    category: 'permissions',
    parent: null,
    key: 'product',
    roles: {
        viewer: {
            privileges: ['plugin:read']
        },
        editor: {
            privileges: ['plugin:update']
        },
        newrole: {
            privileges: ['plugin:write']
        }
    }
});
```

Note: This file has to be imported in the `main.js` file which has to be placed in the `<plugin root>/src/Resources/app/administration/src` directory in order to be automatically found by Shopware 6.

### Register additional permissions

To add privileges to the card `additional_permissions` you need to set `additional_permissions` in the property category. The main difference to normal permissions is that you can choose every role key you want.

Here's an example for `additional_permissions`:

```javascript
Shopware.Service('privileges').addPrivilegeMappingEntry({
    category: 'additional_permissions',
    parent: null,
    key: 'system',
    roles: {
        clear_cache: {
            privileges: ['system:clear:cache'],
            dependencies: []
        }
    }
});
```

Here, the key is `system` to group the permission together with other system specific permissions. However, you can feel free to add your own names here.

## Get permissions from other privilege mappings

In case you have many dependencies which are the same as in other modules, you can import them here. This can be useful if you have components in your module which have complex privileges. Some examples can be found in the rule builder or the media module. You can get these privileges with the method `getPrivileges` of the service.

See this example here:

```javascript
Shopware.Service('privileges').addPrivilegeMappingEntry({
    category: 'permissions',
    parent: null,
    key: 'product',
    roles: {
        viewer: {
            privileges: [
                'product.read',
                Shopware.Service('privileges').getPrivileges('rule.viewer')
            ],
            dependencies: []
        }
    }
})
```

Now all users with the privilege `product.viewer` automatically have access to all privileges from the `rule.viewer`.

Important: The user still has no access to the module itself in the Administration. This means that the example above doesn't give a user access to the `rule` module.

## Protect your plugin routes

It's easy to protect your routes for users without the appropriate privileges. Just add `privilege` to the `meta` property in your route:

```javascript
Module.register('your-plugin-module', {
    routes: {
        detail: {
            component: 'your-plugin-detail',
            path: 'your-plugin',
            meta: {
                privilege: 'your_key.your_role' // e.g. 'product.viewer'
            }
        }    
    }
});
```

## Protect your plugin menu entries

Similar to the routes, you can to add the property `privilege` to your navigation settings to hide it:

```javascript
Module.register('your-plugin-module', {
    navigation: [{
        id: 'your-plugin',
        ...,
        privilege: 'your_key.your_role' // e.g. product.viewer
    }]
});
```

or in the settings item:

```javascript
Module.register('your-plugin-module', {
    settingsItem: [{
        group: 'system',
        to: 'sw.your.plugin.detail',
        privilege: 'your_key.your_role' // e.g. product.viewer
    }]
});
```

## Add snippets for your privileges

To create translations for the labels of the permissions you need to add snippet translations. The path is created automatically for you:

For group titles:

```text
sw.privileges.${category}.${key}.label
// e.g. sw.privileges.permissions.product.label
// e.g. sw.privileges.additional_permissions.system.label
```

For specific roles (only needed in `additional_permissions`):

```text
sw.privileges.${category}.${key}.${role_key} 
// e.g. sw.privileges.additional_permissions.system.clear_cache
```

Just add the snippets to your snippets file:

```json
{
  "sw-privileges": {
    "permissions": {
      "review": {
        "label": "Reviews"
      }
    },
    "additional_permissions": {
      "system": {
        "label": "System",
        "clear_cache": "Clear cache"
      }
    }
  }
}
```

## Use the privileges in any place in your plugin

You can use the `acl` service to check if the user has the correct privileges to view or edit things, regardless of location in your app. The method you need is `acl.can(identifier)`: It checks automatically if the user has admin rights or the privilege for the identifier.

You can use the global Shopware object (`Shopware.Service('acl')`) or inject the service in your component:

```javascript
Shopware.Component.register('your-plugin-component', {
    template,

    inject: ['acl'],

    ...
});
```

With the injection, you can use the service functionality everywhere in your component.

Example in a method:

```javascript
Shopware.Component.register('your-plugin-component', {
    template,

    inject: ['acl'],

    methods: {
        allowSaving() {
            return this.acl.can('sales_channel.creator');
        }    
    }
});
```

Below is an example to hide the element if the user has not the right privilege:

```html
<button v-if="acl.can('review.editor')">
</button>
```

For example you could disable elements if the user has not the right privilege to use them and inform the user with a tooltip that a privilege is missing. To achieve this, you can use the global snippet path:

```html
<button @click="saveProduct"
        :disabled="!acl.can('review.editor')"
        v-tooltip="{
            message: $tc('sw-privileges.tooltip.warning'),
            disabled: acl.can('review.editor'),
            showOnDisabledElements: true
        }"
></button>
```

## Protect your shortcuts

You can replace the String value with an object which contains the method with the name `active` which then returns a boolean or just the property `active`as boolean. In our case we need a function to check if the user has the privilege required to use the shortcut.

```javascript
Module.register('your-plugin-module', {
    shortcuts: {
        'SYSTEMKEY+S': {
            active() {
                return this.acl.can('product.editor');
            },
            method: 'onSave'
        },
        ESCAPE: 'onCancel'
    },
});
```

## Add your custom privileges

To make sure your custom privileges are additionally added to existing roles, override the `enrichPrivileges` method and return a list of your custom privileges.
This method should return an array with the technical role name as key, while the privileges should be the array value.
An event subscriber will add the plugins custom privileges at runtime.

```php
<?php declare(strict_types=1);

namespace SwagTestPluginAcl;

use Shopware\Core\Framework\Plugin;

class SwagTestPluginAcl extends Plugin
{
    public function enrichPrivileges(): array
    {
        return [
            'product.viewer' => [
                'my_custom_privilege:read',
                'my_custom_privilege:write',
                'my_other_custom_privilege:read',
                // ...
            ],
            'product.editor' => [
                // ...
            ],
        ];
    }
}
```

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/administration/permissions-error-handling/add-acl-rules.md
---

# Adding permissions

## Overview

This guide will teach you how to add Access Control Lists to the Shopware 6 Administration. Access Control Lists or ACL in Shopware ensure that you can create individual roles. These roles have finely granular rights, which every shop operator can set up for themselves. They can be assigned to users.

As an example, let's take a look at a role called 'Editor'. We would assign this role rights to edit products, categories and manufacturers. Now, every user who is a 'Editor' would be able to see and edit the specific areas which are defined in the role.

This documentation chapter will cover the following topics:

* What is an admin privilege
* How to register new admin privileges for your plugin
* How to protect your plugin routes
* How to protect your menu entries
* How to add admin snippets for your privileges
* How you can check in your module at any place if the user has the required rights

Note: ACL Rules in the Administration can be circumnavigated by making direct API calls to your backend.

## Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files and a running plugin. A basic understanding of the [vue router](https://router.vuejs.org/) is also required. Of course you'll have to understand JavaScript, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation.

## Admin privileges

Admin privileges are higher-level permissions that are always determined by an explicit identifier. This is made up of a 'key' and the 'role', connected by a dot: `.`.

A distinction is made here between normal `permissions` and `additional_permissions`. Let's start with the normal permissions.

### Normal permissions

![Permissions GUI](../../../../../assets/permissions-gui.png)

`permissions`:

* Key: `product`
* Role: `viewer`
* Identifier (Key + Role): `product.viewer`

The key describes the higher-level admin privilege. For normal `permissions` this is usually the module name, `product` in this case. Other keys could be for example `manufacturer`, `shopping_experiences` or `customers`. The key is used to group the admin privileges, as seen in the picture above.

The role indicates which authorization is given for the key. So four predefined roles are available for the normal `permissions`:

* `viewer`: The viewer is allowed to view entities
* `editor`: The editor is allowed to edit entities
* `creator`: The Creator is allowed to create new entities
* `deleter`: The Deleter is allowed to delete entities

It is important to note that these combinations are not API permissions. They are only intended to enable, disable, deactivate or hide certain elements in the Administration.

For each admin privilege, the needed entity privileges need to be assigned. Depending on the admin privileges, these can be much more complex. This means that for example if a user should be allowed to view reviews, then they also have to be allowed to view customers, products and sales channels.

### Additional permissions

In addition to the normal `permissions`, which represent CRUD functionality, there are also `additional_permissions`. These are intended for all functions that cannot be represented by CRUD.

![Additional permissions GUI](../../../../../assets/additionalPermissions-gui.png)

The `additional_permissions` have their own card below the normal permissions grid. An example for `additional_permissions` would be: "clearing the cache". This is an individual action without CRUD functionalities. The key is still used for grouping. Therefore the role can be individual and does not have to follow the scheme.

`additional_permissions`:

* Key: `system`
* Role: `clear_cache`
* Identifier (Key + Role): `system.clear_cache`

## Register admin privilege

The privilege service is used to handle privileges in the Administration. Those privileges will then be displayed in the Users & Permissions module under the roles.

Privileges can be added or extended with the Method `addPrivilegeMappingEntry` of the privilege service:

| Property | Description |
| :--- | :--- |
| category | Where the privilege should be visible in the `permissions` grid or in the `additional_permissions` |
| parent | For nesting and gaining a better overview, you can add a parent key. If the privilege does not have a parent then use `null`. |
| key | All privileges with the same key will be grouped together. For normal `permissions` each role will be in the same row. |
| roles | When category is `permissions`: Use `viewer`, `editor`, `creator` and `deleter`. |
|  | When category is `additional_permissions`: Use a custom key because the additional permissions don´t enforce a structure. |

Each role in roles:

| Property | Description |
| :--- | :--- |
| privileges | You need to add all API permissions here which are required for an working admin privilege. The structure is `entity_name:operation`, e.g. 'product:read'. |
| dependencies | In some cases it is necessary to automatically check another role. To do this, you need to add the identifier, e.g. `product.viewer`. |

Here's an example how this can look like for the review functionality in the Administration:

```javascript
Shopware.Service('privileges')
    .addPrivilegeMappingEntry({
        category: 'permissions',
        parent: 'catalogues',
        key: 'review',
        roles: {
            viewer: {
                privileges: [
                    'product_review:read',
                    'customer:read',
                    'product:read',
                    'sales_channel:read'
                ],
                dependencies: []
            },
            editor: {
                privileges: [
                    'product_review:update'
                ],
                dependencies: [
                    'review.viewer'
                ]
            },
            creator: {
                privileges: [
                    'product_review:create'
                ],
                dependencies: [
                    'review.viewer',
                    'review.editor'
                ]
            },
            deleter: {
                privileges: [
                    'product_review:delete'
                ],
                dependencies: [
                    'review.viewer'
                ]
            }
        }
    });
```

### Adding new, normal permissions

You could use the service at any point in your code. However, it's important that it will be called before the user goes to the roles detail page. For convenience, we recommend this pattern:

```text
- <plugin root>/src/Resources/app/administration/src/<your-component>/
    - acl
        - index.js -> contains permission
    - ...
    - index.js -> import './acl'
```

Now you can use the method `addPrivilegeMappingEntry` to add a new entry:

To add a new mapping for your custom key use the following approach:

```javascript
// <plugin root>/src/Resources/app/administration/src/<your-component>/acl/index.js

Shopware.Service('privileges').addPrivilegeMappingEntry({
    category: 'permissions',
    parent: null,
    key: 'your_key',
    roles: {
        viewer: {
            privileges: [],
            dependencies: []
        },
        editor: {
            privileges: [],
            dependencies: []
        },
        creator: {
            privileges: [],
            dependencies: []
        },
        deleter: {
            privileges: [],
            dependencies: []
        }
    }
});
```

### Extending existing normal permissions

Adding privileges to an existing key can be done like this:

```javascript
// <plugin root>/src/Resources/app/administration/src/acl-override/index.js

Shopware.Service('privileges').addPrivilegeMappingEntry({
    category: 'permissions',
    parent: null,
    key: 'product',
    roles: {
        viewer: {
            privileges: ['plugin:read']
        },
        editor: {
            privileges: ['plugin:update']
        },
        newrole: {
            privileges: ['plugin:write']
        }
    }
});
```

Note: This file has to be imported in the `main.js` file which has to be placed in the `<plugin root>/src/Resources/app/administration/src` directory in order to be automatically found by Shopware 6.

### Register additional permissions

To add privileges to the card `additional_permissions` you need to set `additional_permissions` in the property category. The main difference to normal permissions is that you can choose every role key you want.

Here's an example for `additional_permissions`:

```javascript
Shopware.Service('privileges').addPrivilegeMappingEntry({
    category: 'additional_permissions',
    parent: null,
    key: 'system',
    roles: {
        clear_cache: {
            privileges: ['system:clear:cache'],
            dependencies: []
        }
    }
});
```

Here, the key is `system` to group the permission together with other system specific permissions. However, you can feel free to add your own names here.

## Get permissions from other privilege mappings

In case you have many dependencies which are the same as in other modules, you can import them here. This can be useful if you have components in your module which have complex privileges. Some examples can be found in the rule builder or the media module. You can get these privileges with the method `getPrivileges` of the service.

See this example here:

```javascript
Shopware.Service('privileges').addPrivilegeMappingEntry({
    category: 'permissions',
    parent: null,
    key: 'product',
    roles: {
        viewer: {
            privileges: [
                'product.read',
                Shopware.Service('privileges').getPrivileges('rule.viewer')
            ],
            dependencies: []
        }
    }
})
```

Now all users with the privilege `product.viewer` automatically have access to all privileges from the `rule.viewer`.

Important: The user still has no access to the module itself in the Administration. This means that the example above doesn't give a user access to the `rule` module.

## Protect your plugin routes

It's easy to protect your routes for users without the appropriate privileges. Just add `privilege` to the `meta` property in your route:

```javascript
Module.register('your-plugin-module', {
    routes: {
        detail: {
            component: 'your-plugin-detail',
            path: 'your-plugin',
            meta: {
                privilege: 'your_key.your_role' // e.g. 'product.viewer'
            }
        }    
    }
});
```

## Protect your plugin menu entries

Similar to the routes, you can to add the property `privilege` to your navigation settings to hide it:

```javascript
Module.register('your-plugin-module', {
    navigation: [{
        id: 'your-plugin',
        ...,
        privilege: 'your_key.your_role' // e.g. product.viewer
    }]
});
```

or in the settings item:

```javascript
Module.register('your-plugin-module', {
    settingsItem: [{
        group: 'system',
        to: 'sw.your.plugin.detail',
        privilege: 'your_key.your_role' // e.g. product.viewer
    }]
});
```

## Add snippets for your privileges

To create translations for the labels of the permissions you need to add snippet translations. The path is created automatically for you:

For group titles:

```text
sw.privileges.${category}.${key}.label
// e.g. sw.privileges.permissions.product.label
// e.g. sw.privileges.additional_permissions.system.label
```

For specific roles (only needed in `additional_permissions`):

```text
sw.privileges.${category}.${key}.${role_key} 
// e.g. sw.privileges.additional_permissions.system.clear_cache
```

Just add the snippets to your snippets file:

```json
{
  "sw-privileges": {
    "permissions": {
      "review": {
        "label": "Reviews"
      }
    },
    "additional_permissions": {
      "system": {
        "label": "System",
        "clear_cache": "Clear cache"
      }
    }
  }
}
```

## Use the privileges in any place in your plugin

You can use the `acl` service to check if the user has the correct privileges to view or edit things, regardless of location in your app. The method you need is `acl.can(identifier)`: It checks automatically if the user has admin rights or the privilege for the identifier.

You can use the global Shopware object (`Shopware.Service('acl')`) or inject the service in your component:

```javascript
Shopware.Component.register('your-plugin-component', {
    template,

    inject: ['acl'],

    ...
});
```

With the injection, you can use the service functionality everywhere in your component.

Example in a method:

```javascript
Shopware.Component.register('your-plugin-component', {
    template,

    inject: ['acl'],

    methods: {
        allowSaving() {
            return this.acl.can('sales_channel.creator');
        }    
    }
});
```

Below is an example to hide the element if the user has not the right privilege:

```html
<button v-if="acl.can('review.editor')">
</button>
```

For example you could disable elements if the user has not the right privilege to use them and inform the user with a tooltip that a privilege is missing. To achieve this, you can use the global snippet path:

```html
<button @click="saveProduct"
        :disabled="!acl.can('review.editor')"
        v-tooltip="{
            message: $tc('sw-privileges.tooltip.warning'),
            disabled: acl.can('review.editor'),
            showOnDisabledElements: true
        }"
></button>
```

## Protect your shortcuts

You can replace the String value with an object which contains the method with the name `active` which then returns a boolean or just the property `active`as boolean. In our case we need a function to check if the user has the privilege required to use the shortcut.

```javascript
Module.register('your-plugin-module', {
    shortcuts: {
        'SYSTEMKEY+S': {
            active() {
                return this.acl.can('product.editor');
            },
            method: 'onSave'
        },
        ESCAPE: 'onCancel'
    },
});
```

## Add your custom privileges

To make sure your custom privileges are additionally added to existing roles, override the `enrichPrivileges` method and return a list of your custom privileges.
This method should return an array with the technical role name as key, while the privileges should be the array value.
An event subscriber will add the plugins custom privileges at runtime.

```php
<?php declare(strict_types=1);

namespace SwagTestPluginAcl;

use Shopware\Core\Framework\Plugin;

class SwagTestPluginAcl extends Plugin
{
    public function enrichPrivileges(): array
    {
        return [
            'product.viewer' => [
                'my_custom_privilege:read',
                'my_custom_privilege:write',
                'my_other_custom_privilege:read',
                // ...
            ],
            'product.editor' => [
                // ...
            ],
        ];
    }
}
```

---

---
url: >-
  /docs/guides/plugins/plugins/administration/permissions-error-handling/add-acl-rules.md
---

# Adding Permissions

## Overview

This guide will teach you how to add Access Control Lists to the Shopware 6 Administration. Access Control Lists or ACL in Shopware ensure that you can create individual roles. These roles have finely granular rights, which every shop operator can set up for themselves. They can be assigned to users.

As an example, let's take a look at a role called 'Editor'. We would assign this role rights to edit products, categories and manufacturers. Now, every user who is a 'Editor' would be able to see and edit the specific areas which are defined in the role.

This documentation chapter will cover the following topics:

* What is an admin privilege
* How to register new admin privileges for your plugin
* How to protect your plugin routes
* How to protect your menu entries
* How to add admin snippets for your privileges
* How you can check in your module at any place if the user has the required rights

Note: ACL Rules in the Administration can be circumnavigated by making direct API calls to your backend.

## Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files and a running plugin. A basic understanding of the [Vue router](https://router.vuejs.org/) is also required. Of course you'll have to understand JavaScript, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation.

## Admin privileges

Admin privileges are higher-level permissions that are always determined by an explicit identifier. This is made up of a 'key' and the 'role', connected by a dot: `.`.

A distinction is made here between normal `permissions` and `additional_permissions`. Let's start with the normal permissions.

### Normal permissions

![Permissions GUI](../../../../../assets/permissions-gui.png)

`permissions`:

* Key: `product`
* Role: `viewer`
* Identifier (Key + Role): `product.viewer`

The key describes the higher-level admin privilege. For normal `permissions` this is usually the module name, `product` in this case. Other keys could be for example `manufacturer`, `shopping_experiences` or `customers`. The key is used to group the admin privileges, as seen in the picture above.

The role indicates which authorization is given for the key. So four predefined roles are available for the normal `permissions`:

* `viewer`: The viewer is allowed to view entities
* `editor`: The editor is allowed to edit entities
* `creator`: The Creator is allowed to create new entities
* `deleter`: The Deleter is allowed to delete entities

It is important to note that these combinations are not API permissions. They are only intended to enable, disable, deactivate or hide certain elements in the Administration.

For each admin privilege, the needed entity privileges need to be assigned. Depending on the admin privileges, these can be much more complex. This means that for example if a user should be allowed to view reviews, then they also have to be allowed to view customers, products and sales channels.

### Additional permissions

In addition to the normal `permissions`, which represent CRUD functionality, there are also `additional_permissions`. These are intended for all functions that cannot be represented by CRUD.

![Additional permissions GUI](../../../../../assets/additionalPermissions-gui.png)

The `additional_permissions` have their own card below the normal permissions grid. An example for `additional_permissions` would be: "clearing the cache". This is an individual action without CRUD functionalities. The key is still used for grouping. Therefore the role can be individual and does not have to follow the scheme.

`additional_permissions`:

* Key: `system`
* Role: `clear_cache`
* Identifier (Key + Role): `system.clear_cache`

## Register admin privilege

The privilege service is used to handle privileges in the Administration. Those privileges will then be displayed in the Users & Permissions module under the roles.

Privileges can be added or extended with the Method `addPrivilegeMappingEntry` of the privilege service:

| Property | Description |
| :--- | :--- |
| category | Where the privilege should be visible in the `permissions` grid or in the `additional_permissions` |
| parent | For nesting and gaining a better overview, you can add a parent key. If the privilege does not have a parent then use `null`. |
| key | All privileges with the same key will be grouped together. For normal `permissions` each role will be in the same row. |
| roles | When category is `permissions`: Use `viewer`, `editor`, `creator` and `deleter`. |
|  | When category is `additional_permissions`: Use a custom key because the additional permissions don´t enforce a structure. |

Each role in roles:

| Property | Description |
| :--- | :--- |
| privileges | You need to add all API permissions here which are required for an working admin privilege. The structure is `entity_name:operation`, e.g. 'product:read'. |
| dependencies | In some cases it is necessary to automatically check another role. To do this, you need to add the identifier, e.g. `product.viewer`. |

Here's an example how this can look like for the review functionality in the Administration:

```javascript
Shopware.Service('privileges')
    .addPrivilegeMappingEntry({
        category: 'permissions',
        parent: 'catalogues',
        key: 'review',
        roles: {
            viewer: {
                privileges: [
                    'product_review:read',
                    'customer:read',
                    'product:read',
                    'sales_channel:read'
                ],
                dependencies: []
            },
            editor: {
                privileges: [
                    'product_review:update'
                ],
                dependencies: [
                    'review.viewer'
                ]
            },
            creator: {
                privileges: [
                    'product_review:create'
                ],
                dependencies: [
                    'review.viewer',
                    'review.editor'
                ]
            },
            deleter: {
                privileges: [
                    'product_review:delete'
                ],
                dependencies: [
                    'review.viewer'
                ]
            }
        }
    });
```

### Adding new, normal permissions

You could use the service at any point in your code. However, it's important that it will be called before the user goes to the roles detail page. For convenience, we recommend this pattern:

```text
- <plugin root>/src/Resources/app/administration/src/<your-component>/
    - acl
        - index.js -> contains permission
    - ...
    - index.js -> import './acl'
```

Now you can use the method `addPrivilegeMappingEntry` to add a new entry:

To add a new mapping for your custom key use the following approach:

```javascript
// <plugin root>/src/Resources/app/administration/src/<your-component>/acl/index.js

Shopware.Service('privileges').addPrivilegeMappingEntry({
    category: 'permissions',
    parent: null,
    key: 'your_key',
    roles: {
        viewer: {
            privileges: [],
            dependencies: []
        },
        editor: {
            privileges: [],
            dependencies: []
        },
        creator: {
            privileges: [],
            dependencies: []
        },
        deleter: {
            privileges: [],
            dependencies: []
        }
    }
});
```

### Extending existing normal permissions

Adding privileges to an existing key can be done like this:

```javascript
// <plugin root>/src/Resources/app/administration/src/acl-override/index.js

Shopware.Service('privileges').addPrivilegeMappingEntry({
    category: 'permissions',
    parent: null,
    key: 'product',
    roles: {
        viewer: {
            privileges: ['plugin:read']
        },
        editor: {
            privileges: ['plugin:update']
        },
        newrole: {
            privileges: ['plugin:write']
        }
    }
});
```

Note: This file has to be imported in the `main.js` file which has to be placed in the `<plugin root>/src/Resources/app/administration/src` directory in order to be automatically found by Shopware 6.

### Register additional permissions

To add privileges to the card `additional_permissions` you need to set `additional_permissions` in the property category. The main difference to normal permissions is that you can choose every role key you want.

Here's an example for `additional_permissions`:

```javascript
Shopware.Service('privileges').addPrivilegeMappingEntry({
    category: 'additional_permissions',
    parent: null,
    key: 'system',
    roles: {
        clear_cache: {
            privileges: ['system:clear:cache'],
            dependencies: []
        }
    }
});
```

Here, the key is `system` to group the permission together with other system specific permissions. However, you can feel free to add your own names here.

## Get permissions from other privilege mappings

In case you have many dependencies which are the same as in other modules, you can import them here. This can be useful if you have components in your module which have complex privileges. Some examples can be found in the rule builder or the media module. You can get these privileges with the method `getPrivileges` of the service.

See this example here:

```javascript
Shopware.Service('privileges').addPrivilegeMappingEntry({
    category: 'permissions',
    parent: null,
    key: 'product',
    roles: {
        viewer: {
            privileges: [
                'product.read',
                Shopware.Service('privileges').getPrivileges('rule.viewer')
            ],
            dependencies: []
        }
    }
})
```

Now all users with the privilege `product.viewer` automatically have access to all privileges from the `rule.viewer`.

Important: The user still has no access to the module itself in the Administration. This means that the example above doesn't give a user access to the `rule` module.

## Protect your plugin routes

It's easy to protect your routes for users without the appropriate privileges. Just add `privilege` to the `meta` property in your route:

```javascript
Module.register('your-plugin-module', {
    routes: {
        detail: {
            component: 'your-plugin-detail',
            path: 'your-plugin',
            meta: {
                privilege: 'your_key.your_role' // e.g. 'product.viewer'
            }
        }    
    }
});
```

## Protect your plugin menu entries

Similar to the routes, you can to add the property `privilege` to your navigation settings to hide it:

```javascript
Module.register('your-plugin-module', {
    navigation: [{
        id: 'your-plugin',
        ...,
        privilege: 'your_key.your_role' // e.g. product.viewer
    }]
});
```

or in the settings item:

```javascript
Module.register('your-plugin-module', {
    settingsItem: [{
        group: 'system',
        to: 'sw.your.plugin.detail',
        privilege: 'your_key.your_role' // e.g. product.viewer
    }]
});
```

## Add snippets for your privileges

To create translations for the labels of the permissions you need to add snippet translations. The path is created automatically for you:

For group titles:

```text
sw.privileges.${category}.${key}.label
// e.g. sw.privileges.permissions.product.label
// e.g. sw.privileges.additional_permissions.system.label
```

For specific roles (only needed in `additional_permissions`):

```text
sw.privileges.${category}.${key}.${role_key} 
// e.g. sw.privileges.additional_permissions.system.clear_cache
```

Just add the snippets to your snippets file:

```json
{
  "sw-privileges": {
    "permissions": {
      "review": {
        "label": "Reviews"
      }
    },
    "additional_permissions": {
      "system": {
        "label": "System",
        "clear_cache": "Clear cache"
      }
    }
  }
}
```

## Use the privileges in any place in your plugin

You can use the `acl` service to check if the user has the correct privileges to view or edit things, regardless of location in your app. The method you need is `acl.can(identifier)`: It checks automatically if the user has admin rights or the privilege for the identifier.

You can use the global Shopware object (`Shopware.Service('acl')`) or inject the service in your component:

```javascript
Shopware.Component.register('your-plugin-component', {
    template,

    inject: ['acl'],

    ...
});
```

With the injection, you can use the service functionality everywhere in your component.

Example in a method:

```javascript
Shopware.Component.register('your-plugin-component', {
    template,

    inject: ['acl'],

    methods: {
        allowSaving() {
            return this.acl.can('sales_channel.creator');
        }    
    }
});
```

Below is an example to hide the element if the user has not the right privilege:

```html
<button v-if="acl.can('review.editor')">
</button>
```

For example you could disable elements if the user has not the right privilege to use them and inform the user with a tooltip that a privilege is missing. To achieve this, you can use the global snippet path:

```html
<button @click="saveProduct"
        :disabled="!acl.can('review.editor')"
        v-tooltip="{
            message: $tc('sw-privileges.tooltip.warning'),
            disabled: acl.can('review.editor'),
            showOnDisabledElements: true
        }"
></button>
```

## Protect your shortcuts

You can replace the String value with an object which contains the method with the name `active` which then returns a boolean or just the property `active`as boolean. In our case we need a function to check if the user has the privilege required to use the shortcut.

```javascript
Module.register('your-plugin-module', {
    shortcuts: {
        'SYSTEMKEY+S': {
            active() {
                return this.acl.can('product.editor');
            },
            method: 'onSave'
        },
        ESCAPE: 'onCancel'
    },
});
```

## Add your custom privileges

To make sure your custom privileges are additionally added to existing roles, override the `enrichPrivileges` method and return a list of your custom privileges.
This method should return an array with the technical role name as key, while the privileges should be the array value.
An event subscriber will add the plugins custom privileges at runtime.

```php
<?php declare(strict_types=1);

namespace SwagTestPluginAcl;

use Shopware\Core\Framework\Plugin;

class SwagTestPluginAcl extends Plugin
{
    public function enrichPrivileges(): array
    {
        return [
            'product.viewer' => [
                'my_custom_privilege:read',
                'my_custom_privilege:write',
                'my_other_custom_privilege:read',
                // ...
            ],
            'product.editor' => [
                // ...
            ],
        ];
    }
}
```

---

---
url: >-
  /docs/guides/plugins/plugins/integrations/elasticsearch/add-product-entity-extension-to-elasticsearch.md
---

# Adding Product Entity Extension to Elasticsearch

In this guide you'll learn how to add extended fields of the product entity to the elasticsearch engine to make it searchable.

In this example we'll assume an extension of the `ProductDefinition` with a string field `customString` like described in [Adding complex data to existing entities](../../framework/data-handling/add-complex-data-to-existing-entities.md#adding-a-field-without-database).

## Prerequisites

This guide is built upon the [Plugin Base Guide](../../plugin-base-guide.md), and the entity extension described in [Adding complex data to existing entities](../../framework/data-handling/add-complex-data-to-existing-entities.md#adding-a-field-without-database).
We will extend the product extension with an `OneToOneAssociationField` and `OneToManyAssociationField`.

## Decorate the ElasticsearchProductDefinition

To extend the elasticsearch definition we need to extend the product definition first and add the subscriber. This is described in the above mentioned articles.
Here we show you how this could look like in the end.

The services.php with all needed definitions.

```php
// <plugin root>/src/Core/Content/DependencyInjection/product.php
<?php declare(strict_types=1);

use Doctrine\DBAL\Connection;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;
use Swag\BasicExample\Extension\Content\Product\CustomExtension;
use Swag\BasicExample\Extension\Content\Product\OneToOneExampleExtensionDefinition;
use Swag\BasicExample\Extension\Content\Product\OneToManyExampleExtensionDefinition;
use Swag\BasicExample\Subscriber\ProductSubscriber;
use Swag\BasicExample\Elasticsearch\Product\MyProductEsDecorator;
use Shopware\Elasticsearch\Product\ElasticsearchProductDefinition;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(CustomExtension::class)
        ->tag('shopware.entity.extension');

    $services->set(OneToOneExampleExtensionDefinition::class)
        ->tag('shopware.entity.definition', ['entity' => 'one_to_one_swag_example_extension']);

    $services->set(OneToManyExampleExtensionDefinition::class)
        ->tag('shopware.entity.definition', ['entity' => 'one_to_many_swag_example_extension']);

    $services->set(ProductSubscriber::class)
        ->tag('kernel.event_subscriber');

    $services->set(MyProductEsDecorator::class)
        ->decorate(ElasticsearchProductDefinition::class)
        ->args([
            service(MyProductEsDecorator::class . '.inner'),
            service(Connection::class),
        ]);
};
```

The product extension `CustomExtension.php` provides the extensions to the product entity.

```php
// <plugin root>/src/Extension/Content/Product/CustomExtension.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Extension\Content\Product;

use Shopware\Core\Content\Product\ProductDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\EntityExtension;
use Shopware\Core\Framework\DataAbstractionLayer\Field\ObjectField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\OneToManyAssociationField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\OneToOneAssociationField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Runtime;

class CustomExtension extends EntityExtension
{
    public function extendFields(FieldCollection $collection): void
    {
        //Add ApiAware flag to make this field searchable
        $collection->add(
            (new OneToOneAssociationField('oneToOneExampleExtension', 'id', 'product_id', OneToOneExampleExtensionDefinition::class, true))->addFlags(new ApiAware())
        );
        //Add ApiAware flag to make this field searchable
        $collection->add(
            (new OneToManyAssociationField('oneToManyExampleExtension', OneToManyExampleExtensionDefinition::class, 'product_id'))->addFlags(new ApiAware())
        );
        //Runtime fields are not searchable
        $collection->add(
            (new ObjectField('custom_string', 'customString'))->addFlags(new Runtime())
        );
    }

    public function getDefinitionClass(): string
    {
        return ProductDefinition::class;
    }
}
```

The entity definition `OneToManyExampleExtensionDefinition.php`.

```php
// <plugin root>/src/Extension/Content/Product/OneToManyExampleExtensionDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Extension\Content\Product;

use Shopware\Core\Content\Product\ProductDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Field\FkField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\ApiAware;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\PrimaryKey;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
use Shopware\Core\Framework\DataAbstractionLayer\Field\IdField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\ManyToOneAssociationField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\ReferenceVersionField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\StringField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;
use Shopware\Core\Framework\DataAbstractionLayer\Entity;

class OneToManyExampleExtensionDefinition extends EntityDefinition
{
    public const ENTITY_NAME = 'one_to_many_swag_example_extension';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    public function getEntityClass(): string
    {
        return Entity::class;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new ApiAware(), new Required(), new PrimaryKey()),
            new FkField('product_id', 'productId', ProductDefinition::class),
            (new ReferenceVersionField(ProductDefinition::class))->addFlags(new Required()),
            (new StringField('custom_string', 'customString'))->addFlags(new ApiAware()),

            new ManyToOneAssociationField('product', 'product_id', ProductDefinition::class),
        ]);
    }
}
```

The entity definition `OneToOneExampleExtensionDefinition.php`.

```php
// <plugin root>/src/Extension/Content/Product/OneToOneExampleExtensionDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Extension\Content\Product;

use Shopware\Core\Content\Product\ProductDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Field\FkField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\ApiAware;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\PrimaryKey;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
use Shopware\Core\Framework\DataAbstractionLayer\Field\IdField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\OneToOneAssociationField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\ReferenceVersionField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\StringField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;
use Shopware\Core\Framework\DataAbstractionLayer\Entity;

class OneToOneExampleExtensionDefinition extends EntityDefinition
{
    public const ENTITY_NAME = 'one_to_one_swag_example_extension';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    public function getEntityClass(): string
    {
        return Entity::class;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new ApiAware(), new Required(), new PrimaryKey()),
            new FkField('product_id', 'productId', ProductDefinition::class),
            (new ReferenceVersionField(ProductDefinition::class))->addFlags(new Required()),
            (new StringField('custom_string', 'customString'))->addFlags(new ApiAware()),

            new OneToOneAssociationField('product', 'product_id', 'id', ProductDefinition::class, false)
        ]);
    }
}
```

Here is a decoration to add a new field named `customString`, an `oneToOneAssociationField` named `oneToOneExampleExtension` and an `oneToManyAssociationField` named `oneToManyExampleExtension` to the index.
For adding more information from the database you should execute a single query with all document ids `(array_column($documents, 'id'))` and map the values.

```php
// <plugin root>/src/Elasticsearch/Product/MyProductEsDecorator.php
<?php

namespace Swag\BasicExample\Elasticsearch\Product;

use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Elasticsearch\Framework\AbstractElasticsearchDefinition;
use Doctrine\DBAL\Connection;
use Swag\BasicExample\Subscriber\ProductSubscriber;

class MyProductEsDecorator extends AbstractElasticsearchDefinition
{
    private AbstractElasticsearchDefinition $productDefinition;
    private Connection $connection;

    public function __construct(AbstractElasticsearchDefinition $productDefinition, Connection $connection)
    {
        $this->productDefinition = $productDefinition;
        $this->connection = $connection;
    }

    public function getEntityDefinition(): EntityDefinition
    {
        return $this->productDefinition->getEntityDefinition();
    }

    public function buildTermQuery(Context $context, Criteria $criteria): BoolQuery
    {
        return $this->productDefinition->buildTermQuery($context, $criteria);
    }

    /**
     * Extend the mapping with your own changes
     * Take care to get the default mapping first by `$this->productDefinition->getMapping($context);`
     */
    public function getMapping(Context $context): array
    {
        $mapping = $this->productDefinition->getMapping($context);

        //The mapping for a simple keyword field
        $mapping['properties']['customString'] = AbstractElasticsearchDefinition::KEYWORD_FIELD;

        // Adding an association as keyword
        $mapping['properties']['oneToOneExampleExtension'] = [
                'type' => 'nested',
                'properties' => [
                    'customString' => AbstractElasticsearchDefinition::KEYWORD_FIELD,
            ],
        ];

        // Adding a nested field with id
        $mapping['properties']['oneToManyExampleExtension'] = [
            'type' => 'nested',
            'properties' => [
                'id' => AbstractElasticsearchDefinition::KEYWORD_FIELD,
            ],
        ];

        return $mapping;
    }

    public function fetch(array $ids, Context $context): array
    {
        $documents = $this->productDefinition->fetch($ids, $context);

        $associationOneToOne = $this->fetchOneToOneExample($ids);
        $associationOneToMany = $this->fetchOneToManyExample($ids);

        foreach ($documents as &$document) {
            /**
             * A field directly on the product.
             * The value should be filled with the same Runtime value which will be set by the ProductSubscriber
             */
            $document['customString'] = ProductSubscriber::getRuntimeValue($document['id'])->getValue();

            /**
             * Field with value from associated entity
             */
            if (isset($associationOneToOne[$document['id']])) {
                $document['oneToOneExampleExtension']['customString'] = $associationOneToOne[$document['id']];
            }

            /**
             * Field with multiple id entries from associated entity
             */
            if (isset($associationOneToMany[$document['id']])) {
                $document['oneToManyExampleExtension'] = array_map(function (string $id) {
                    return ['id' => $id];
                }, array_filter(explode('|', $associationOneToMany[$document['id']] ?? '')));
            }
        }

        return $documents;
    }

    /**
     * Read the associated entries directly from the database
     */
    private function fetchOneToOneExample(array $ids): array
    {
        $query = <<<SQL
            SELECT LOWER(HEX(product_id)) as id, custom_string
            FROM one_to_one_swag_example_extension
            WHERE
                product_id IN(:ids)
        SQL;

        return $this->connection->fetchAllKeyValue(
            $query,
            [
                'ids' => $ids,
            ],
            [
                'ids' => Connection::PARAM_STR_ARRAY
            ]
        );
    }

    /**
     * Read the associated entries directly from the database
     */
    private function fetchOneToManyExample(array $ids): array
    {
        $query = <<<SQL
            SELECT LOWER(HEX(product_id)) as id, GROUP_CONCAT(id SEPARATOR "|")
            FROM one_to_many_swag_example_extension
            WHERE
                product_id IN(:ids)
        SQL;

        return $this->connection->fetchAllKeyValue(
            $query,
            [
                'ids' => $ids,
            ],
            [
                'ids' => Connection::PARAM_STR_ARRAY
            ]
        );
    }
}
```

---

---
url: >-
  /docs/v6.5/guides/plugins/plugins/elasticsearch/add-product-entity-extension-to-elasticsearch.md
---

# Adding Product Entity Extension to Elasticsearch

## Overview

In this guide you'll learn how to add extended fields of the product entity to the elasticsearch engine to make it searchable.

In this example we'll assume an extension of the `ProductDefinition` with a string field `customString` like described in [Adding Complex data to existing entities](../framework/data-handling/add-complex-data-to-existing-entities#adding-a-field-without-database).

## Prerequisites

This guide is built upon the [Plugin Base Guide](../plugin-base-guide), and the entity extension described in [Adding Complex data to existing entities](../framework/data-handling/add-complex-data-to-existing-entities#adding-a-field-without-database).
We will extend the product extension with an `OneToOneAssociationField` and `OneToManyAssociationField`.

## Decorate the ElasticsearchProductDefinition

To extend the elasticsearch definition we need to extend the product definition first and add the subscriber. This is described in the above mentioned articles.
Here we show you how this could look like in the end.

The service.xml with all needed definitions.

```xml
// <plugin root>/src/Core/Content/DependencyInjection/product.xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Extension\Content\Product\CustomExtension">
            <tag name="shopware.entity.extension"/>
        </service>

        <service id="Swag\BasicExample\Extension\Content\Product\OneToOneExampleExtensionDefinition">
            <tag name="shopware.entity.definition" entity="one_to_one_swag_example_extension" />
        </service>

        <service id="Swag\BasicExample\Extension\Content\Product\OneToManyExampleExtensionDefinition">
            <tag name="shopware.entity.definition" entity="one_to_many_swag_example_extension" />
        </service>

        <service id="Swag\BasicExample\Subscriber\ProductSubscriber">
            <tag name="kernel.event_subscriber"/>
        </service>

        <service id="Swag\BasicExample\Elasticsearch\Product\MyProductEsDecorator" decorates="Shopware\Elasticsearch\Product\ElasticsearchProductDefinition">
            <argument type="service" id="Swag\BasicExample\Elasticsearch\Product\MyProductEsDecorator.inner"/>
            <argument type="service" id="Doctrine\DBAL\Connection"/>
        </service>
    </services>
</container>
```

The product extension `CustomExtension.php` provides the extensions to the product entity.

```php
// <plugin root>/src/Extension/Content/Product/CustomExtension.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Extension\Content\Product;

use Shopware\Core\Content\Product\ProductDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\EntityExtension;
use Shopware\Core\Framework\DataAbstractionLayer\Field\ObjectField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\OneToManyAssociationField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\OneToOneAssociationField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Runtime;

class CustomExtension extends EntityExtension
{
    public function extendFields(FieldCollection $collection): void
    {
        //Add ApiAware flag to make this field searchable
        $collection->add(
            (new OneToOneAssociationField('oneToOneExampleExtension', 'id', 'product_id', OneToOneExampleExtensionDefinition::class, true))->addFlags(new ApiAware())
        );
        //Add ApiAware flag to make this field searchable
        $collection->add(
            (new OneToManyAssociationField('oneToManyExampleExtension', OneToManyExampleExtensionDefinition::class, 'product_id'))->addFlags(new ApiAware())
        );
        //Runtime fields are not searchable
        $collection->add(
            (new ObjectField('custom_string', 'customString'))->addFlags(new Runtime())
        );
    }

    public function getDefinitionClass(): string
    {
        return ProductDefinition::class;
    }
}
```

The entity definition `OneToManyExampleExtensionDefinition.php`.

```php
// <plugin root>/src/Extension/Content/Product/OneToManyExampleExtensionDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Extension\Content\Product;

use Shopware\Core\Content\Product\ProductDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Field\FkField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\ApiAware;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\PrimaryKey;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
use Shopware\Core\Framework\DataAbstractionLayer\Field\IdField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\ManyToOneAssociationField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\ReferenceVersionField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\StringField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;
use Shopware\Core\Framework\DataAbstractionLayer\Entity;

class OneToManyExampleExtensionDefinition extends EntityDefinition
{
    public const ENTITY_NAME = 'one_to_many_swag_example_extension';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    public function getEntityClass(): string
    {
        return Entity::class;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new ApiAware(), new Required(), new PrimaryKey()),
            new FkField('product_id', 'productId', ProductDefinition::class),
            (new ReferenceVersionField(ProductDefinition::class))->addFlags(new Required()),
            (new StringField('custom_string', 'customString'))->addFlags(new ApiAware()),

            new ManyToOneAssociationField('product', 'product_id', ProductDefinition::class),
        ]);
    }
}
```

The entity definition `OneToOneExampleExtensionDefinition.php`.

```php
// <plugin root>/src/Extension/Content/Product/OneToOneExampleExtensionDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Extension\Content\Product;

use Shopware\Core\Content\Product\ProductDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Field\FkField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\ApiAware;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\PrimaryKey;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
use Shopware\Core\Framework\DataAbstractionLayer\Field\IdField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\OneToOneAssociationField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\ReferenceVersionField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\StringField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;
use Shopware\Core\Framework\DataAbstractionLayer\Entity;

class OneToOneExampleExtensionDefinition extends EntityDefinition
{
    public const ENTITY_NAME = 'one_to_one_swag_example_extension';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    public function getEntityClass(): string
    {
        return Entity::class;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new ApiAware(), new Required(), new PrimaryKey()),
            new FkField('product_id', 'productId', ProductDefinition::class),
            (new ReferenceVersionField(ProductDefinition::class))->addFlags(new Required()),
            (new StringField('custom_string', 'customString'))->addFlags(new ApiAware()),

            new OneToOneAssociationField('product', 'product_id', 'id', ProductDefinition::class, false)
        ]);
    }
}
```

Here is a decoration to add a new field named `customString`, an `oneToOneAssociationField` named `oneToOneExampleExtension` and an `oneToManyAssociationField` named `oneToManyExampleExtension` to the index.
For adding more information from the database you should execute a single query with all document ids `(array_column($documents, 'id'))` and map the values.

```php
// <plugin root>/src/Elasticsearch/Product/MyProductEsDecorator.php
<?php

namespace Swag\BasicExample\Elasticsearch\Product;

use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Elasticsearch\Framework\AbstractElasticsearchDefinition;
use Shopware\Elasticsearch\Framework\Indexing\EntityMapper;
use Doctrine\DBAL\Connection;
use Swag\BasicExample\Subscriber\ProductSubscriber;

class MyProductEsDecorator extends AbstractElasticsearchDefinition
{
    private AbstractElasticsearchDefinition $productDefinition;
    private Connection $connection;

    public function __construct(AbstractElasticsearchDefinition $productDefinition, Connection $connection)
    {
        $this->productDefinition = $productDefinition;
        $this->connection = $connection;
    }

    public function getEntityDefinition(): EntityDefinition
    {
        return $this->productDefinition->getEntityDefinition();
    }

    public function buildTermQuery(Context $context, Criteria $criteria): BoolQuery
    {
        return $this->decoratedService->buildTermQuery($context, $criteria);
    }

    /**
     * Extend the mapping with your own changes
     * Take care to get the default mapping first by `$this->productDefinition->getMapping($context);`
     */
    public function getMapping(Context $context): array
    {
        $mapping = $this->productDefinition->getMapping($context);

        //The mapping for a simple keyword field
        $mapping['properties']['customString'] = EntityMapper::KEYWORD_FIELD;

        // Adding an association as keyword
        $mapping['properties']['oneToOneExampleExtension'] = [
                'type' => 'nested',
                'properties' => [
                    'customString' => EntityMapper::KEYWORD_FIELD,
            ],
        ];

        // Adding a nested field with id
        $mapping['properties']['oneToManyExampleExtension'] = [
            'type' => 'nested',
            'properties' => [
                'id' => EntityMapper::KEYWORD_FIELD,
            ],
        ];

        return $mapping;
    }

    public function fetch(array $ids, Context $context): array
    {
        $documents = $this->productDefinition->fetch($ids, $context);

        $associationOneToOne = $this->fetchOneToOneExample($ids);
        $associationOneToMany = $this->fetchOneToManyExample($ids);

        foreach ($documents as &$document) {
            /**
             * A field directly on the product.
             * The value should be filled with the same Runtime value which will be set by the ProductSubscriber
             */
            $document['customString'] = ProductSubscriber::getRuntimeValue($document['id'])->getValue();

            /**
             * Field with value from associated entity
             */
            if (isset($associationOneToOne[$document['id']])) {
                $document['oneToOneExampleExtension']['customString'] = $associationOneToOne[$document['id']];
            }

            /**
             * Field with multiple id entries from associated entity
             */
            if (isset($associationOneToMany[$document['id']])) {
                $document['oneToManyExampleExtension'] = array_map(function (string $id) {
                    return ['id' => $id];
                }, array_filter(explode('|', $associationOneToMany[$document['id']] ?? '')));
            }
        }

        return $documents;
    }

    /**
     * Read the associated entries directly from the database
     */
    private function fetchOneToOneExample(array $ids): array
    {
        $query = <<<SQL
            SELECT LOWER(HEX(product_id)) as id, custom_string
            FROM one_to_one_swag_example_extension
            WHERE
                product_id IN(:ids)
        SQL;

        return $this->connection->fetchAllKeyValue(
            $query,
            [
                'ids' => $ids,
            ],
            [
                'ids' => Connection::PARAM_STR_ARRAY
            ]
        );
    }

    /**
     * Read the associated entries directly from the database
     */
    private function fetchOneToManyExample(array $ids): array
    {
        $query = <<<SQL
            SELECT LOWER(HEX(product_id)) as id, GROUP_CONCAT(id SEPARATOR "|")
            FROM one_to_many_swag_example_extension
            WHERE
                product_id IN(:ids)
        SQL;

        return $this->connection->fetchAllKeyValue(
            $query,
            [
                'ids' => $ids,
            ],
            [
                'ids' => Connection::PARAM_STR_ARRAY
            ]
        );
    }
}
```

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/elasticsearch/add-product-entity-extension-to-elasticsearch.md
---

# Adding Product Entity Extension to Elasticsearch

## Overview

In this guide you'll learn how to add extended fields of the product entity to the elasticsearch engine to make it searchable.

In this example we'll assume an extension of the `ProductDefinition` with a string field `customString` like described in [Adding Complex data to existing entities](../framework/data-handling/add-complex-data-to-existing-entities#adding-a-field-without-database).

## Prerequisites

This guide is built upon the [Plugin Base Guide](../plugin-base-guide), and the entity extension described in [Adding Complex data to existing entities](../framework/data-handling/add-complex-data-to-existing-entities#adding-a-field-without-database).
We will extend the product extension with an `OneToOneAssociationField` and `OneToManyAssociationField`.

## Decorate the ElasticsearchProductDefinition

To extend the elasticsearch definition we need to extend the product definition first and add the subscriber. This is described in the above mentioned articles.
Here we show you how this could look like in the end.

The service.xml with all needed definitions.

```xml
// <plugin root>/src/Core/Content/DependencyInjection/product.xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Extension\Content\Product\CustomExtension">
            <tag name="shopware.entity.extension"/>
        </service>

        <service id="Swag\BasicExample\Extension\Content\Product\OneToOneExampleExtensionDefinition">
            <tag name="shopware.entity.definition" entity="one_to_one_swag_example_extension" />
        </service>

        <service id="Swag\BasicExample\Extension\Content\Product\OneToManyExampleExtensionDefinition">
            <tag name="shopware.entity.definition" entity="one_to_many_swag_example_extension" />
        </service>

        <service id="Swag\BasicExample\Subscriber\ProductSubscriber">
            <tag name="kernel.event_subscriber"/>
        </service>

        <service id="Swag\BasicExample\Elasticsearch\Product\MyProductEsDecorator" decorates="Shopware\Elasticsearch\Product\ElasticsearchProductDefinition">
            <argument type="service" id="Swag\BasicExample\Elasticsearch\Product\MyProductEsDecorator.inner"/>
            <argument type="service" id="Doctrine\DBAL\Connection"/>
        </service>
    </services>
</container>
```

The product extension `CustomExtension.php` provides the extensions to the product entity.

```php
// <plugin root>/src/Extension/Content/Product/CustomExtension.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Extension\Content\Product;

use Shopware\Core\Content\Product\ProductDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\EntityExtension;
use Shopware\Core\Framework\DataAbstractionLayer\Field\ObjectField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\OneToManyAssociationField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\OneToOneAssociationField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Runtime;

class CustomExtension extends EntityExtension
{
    public function extendFields(FieldCollection $collection): void
    {
        //Add ApiAware flag to make this field searchable
        $collection->add(
            (new OneToOneAssociationField('oneToOneExampleExtension', 'id', 'product_id', OneToOneExampleExtensionDefinition::class, true))->addFlags(new ApiAware())
        );
        //Add ApiAware flag to make this field searchable
        $collection->add(
            (new OneToManyAssociationField('oneToManyExampleExtension', OneToManyExampleExtensionDefinition::class, 'product_id'))->addFlags(new ApiAware())
        );
        //Runtime fields are not searchable
        $collection->add(
            (new ObjectField('custom_string', 'customString'))->addFlags(new Runtime())
        );
    }

    public function getDefinitionClass(): string
    {
        return ProductDefinition::class;
    }
}
```

The entity definition `OneToManyExampleExtensionDefinition.php`.

```php
// <plugin root>/src/Extension/Content/Product/OneToManyExampleExtensionDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Extension\Content\Product;

use Shopware\Core\Content\Product\ProductDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Field\FkField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\ApiAware;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\PrimaryKey;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
use Shopware\Core\Framework\DataAbstractionLayer\Field\IdField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\ManyToOneAssociationField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\ReferenceVersionField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\StringField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;
use Shopware\Core\Framework\DataAbstractionLayer\Entity;

class OneToManyExampleExtensionDefinition extends EntityDefinition
{
    public const ENTITY_NAME = 'one_to_many_swag_example_extension';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    public function getEntityClass(): string
    {
        return Entity::class;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new ApiAware(), new Required(), new PrimaryKey()),
            new FkField('product_id', 'productId', ProductDefinition::class),
            (new ReferenceVersionField(ProductDefinition::class))->addFlags(new Required()),
            (new StringField('custom_string', 'customString'))->addFlags(new ApiAware()),

            new ManyToOneAssociationField('product', 'product_id', ProductDefinition::class),
        ]);
    }
}
```

The entity definition `OneToOneExampleExtensionDefinition.php`.

```php
// <plugin root>/src/Extension/Content/Product/OneToOneExampleExtensionDefinition.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Extension\Content\Product;

use Shopware\Core\Content\Product\ProductDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Core\Framework\DataAbstractionLayer\Field\FkField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\ApiAware;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\PrimaryKey;
use Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\Required;
use Shopware\Core\Framework\DataAbstractionLayer\Field\IdField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\OneToOneAssociationField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\ReferenceVersionField;
use Shopware\Core\Framework\DataAbstractionLayer\Field\StringField;
use Shopware\Core\Framework\DataAbstractionLayer\FieldCollection;
use Shopware\Core\Framework\DataAbstractionLayer\Entity;

class OneToOneExampleExtensionDefinition extends EntityDefinition
{
    public const ENTITY_NAME = 'one_to_one_swag_example_extension';

    public function getEntityName(): string
    {
        return self::ENTITY_NAME;
    }

    public function getEntityClass(): string
    {
        return Entity::class;
    }

    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            (new IdField('id', 'id'))->addFlags(new ApiAware(), new Required(), new PrimaryKey()),
            new FkField('product_id', 'productId', ProductDefinition::class),
            (new ReferenceVersionField(ProductDefinition::class))->addFlags(new Required()),
            (new StringField('custom_string', 'customString'))->addFlags(new ApiAware()),

            new OneToOneAssociationField('product', 'product_id', 'id', ProductDefinition::class, false)
        ]);
    }
}
```

Here is a decoration to add a new field named `customString`, an `oneToOneAssociationField` named `oneToOneExampleExtension` and an `oneToManyAssociationField` named `oneToManyExampleExtension` to the index.
For adding more information from the database you should execute a single query with all document ids `(array_column($documents, 'id'))` and map the values.

```php
// <plugin root>/src/Elasticsearch/Product/MyProductEsDecorator.php
<?php

namespace Swag\BasicExample\Elasticsearch\Product;

use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\DataAbstractionLayer\EntityDefinition;
use Shopware\Elasticsearch\Framework\AbstractElasticsearchDefinition;
use Doctrine\DBAL\Connection;
use Swag\BasicExample\Subscriber\ProductSubscriber;

class MyProductEsDecorator extends AbstractElasticsearchDefinition
{
    private AbstractElasticsearchDefinition $productDefinition;
    private Connection $connection;

    public function __construct(AbstractElasticsearchDefinition $productDefinition, Connection $connection)
    {
        $this->productDefinition = $productDefinition;
        $this->connection = $connection;
    }

    public function getEntityDefinition(): EntityDefinition
    {
        return $this->productDefinition->getEntityDefinition();
    }

    public function buildTermQuery(Context $context, Criteria $criteria): BoolQuery
    {
        return $this->productDefinition->buildTermQuery($context, $criteria);
    }

    /**
     * Extend the mapping with your own changes
     * Take care to get the default mapping first by `$this->productDefinition->getMapping($context);`
     */
    public function getMapping(Context $context): array
    {
        $mapping = $this->productDefinition->getMapping($context);

        //The mapping for a simple keyword field
        $mapping['properties']['customString'] = AbstractElasticsearchDefinition::KEYWORD_FIELD;

        // Adding an association as keyword
        $mapping['properties']['oneToOneExampleExtension'] = [
                'type' => 'nested',
                'properties' => [
                    'customString' => AbstractElasticsearchDefinition::KEYWORD_FIELD,
            ],
        ];

        // Adding a nested field with id
        $mapping['properties']['oneToManyExampleExtension'] = [
            'type' => 'nested',
            'properties' => [
                'id' => AbstractElasticsearchDefinition::KEYWORD_FIELD,
            ],
        ];

        return $mapping;
    }

    public function fetch(array $ids, Context $context): array
    {
        $documents = $this->productDefinition->fetch($ids, $context);

        $associationOneToOne = $this->fetchOneToOneExample($ids);
        $associationOneToMany = $this->fetchOneToManyExample($ids);

        foreach ($documents as &$document) {
            /**
             * A field directly on the product.
             * The value should be filled with the same Runtime value which will be set by the ProductSubscriber
             */
            $document['customString'] = ProductSubscriber::getRuntimeValue($document['id'])->getValue();

            /**
             * Field with value from associated entity
             */
            if (isset($associationOneToOne[$document['id']])) {
                $document['oneToOneExampleExtension']['customString'] = $associationOneToOne[$document['id']];
            }

            /**
             * Field with multiple id entries from associated entity
             */
            if (isset($associationOneToMany[$document['id']])) {
                $document['oneToManyExampleExtension'] = array_map(function (string $id) {
                    return ['id' => $id];
                }, array_filter(explode('|', $associationOneToMany[$document['id']] ?? '')));
            }
        }

        return $documents;
    }

    /**
     * Read the associated entries directly from the database
     */
    private function fetchOneToOneExample(array $ids): array
    {
        $query = <<<SQL
            SELECT LOWER(HEX(product_id)) as id, custom_string
            FROM one_to_one_swag_example_extension
            WHERE
                product_id IN(:ids)
        SQL;

        return $this->connection->fetchAllKeyValue(
            $query,
            [
                'ids' => $ids,
            ],
            [
                'ids' => Connection::PARAM_STR_ARRAY
            ]
        );
    }

    /**
     * Read the associated entries directly from the database
     */
    private function fetchOneToManyExample(array $ids): array
    {
        $query = <<<SQL
            SELECT LOWER(HEX(product_id)) as id, GROUP_CONCAT(id SEPARATOR "|")
            FROM one_to_many_swag_example_extension
            WHERE
                product_id IN(:ids)
        SQL;

        return $this->connection->fetchAllKeyValue(
            $query,
            [
                'ids' => $ids,
            ],
            [
                'ids' => Connection::PARAM_STR_ARRAY
            ]
        );
    }
}
```

---

---
url: /docs/v6.5/guides/plugins/plugins/administration/adding-responsive-behavior.md
---

# Adding responsive behavior

## Overview

The Shopware 6 Administration provides two ways of adding classes to elements based on their size, the device helper and the `v-responsive` directive. Alternatively you can use `css` media queries to make your plugin responsive. Learn how to use `css` here:

## DeviceHelper

The DeviceHelper provides methods to get device and browser information like the current viewport size. The helper methods can be accessed with `this.$device` in every Vue component, since it is bound to the Vue prototype.

It makes it possible to run functions to react to `onResize` events with adding classes or removing them. The example below shows you how to use the `$device.onResize` helper.

```javascript
const listener = function (ev) {
    // do something on resize with the event, like adding or removing classes to elements   
};

const scope = this;
const component = 'sw-basic-example';

this.$device.onResize({ listener, scope, component });
```

The code snippet before could be placed in the `mounted` [Vue lifecycle](https://vuejs.org/v2/guide/instance.html#Lifecycle-Diagram) hook to register those listeners automatically. Then you can automatically remove the listeners in the `onDestroy` hook

```javascript
this.$device.removeResizeListener(component);
```

It also provides many helper functions e.g. to get the screen dimensions. Although there are many more as seen below:

| Function | Description |
| :--- | :--- |
| `this.$device.getViewportWidth();` | Gets the viewport width |
| `this.$device.getViewportHeight();` | Gets the viewport height |
| `this.$device.getDevicePixelRatio();` | Gets the device pixel ratio |
| `this.$device.getScreenWidth();` | Gets the screen width |
| `this.$device.getScreenHeight();` | Gets screen height |
| `this.$device.getScreenOrientation();` | Gets the screen orientation |

## v-responsive directive

The `v-responsive` directive can be used to dynamically apply classes based on an element's dimensions.

```html
<input v-responsive="{ 'is--compact': el => el.width <= 1620, timeout: 200 }">
```

Let's do a small explanation of this directive:

* Apply class (in this case: `is--compact`) when the width of the element is smaller than 1620px.
* `timeout`: Sets the duration on how much the throttle should wait.

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/administration/ui-ux/adding-responsive-behavior.md
---

# Adding responsive behavior

## Overview

The Shopware 6 Administration provides two ways of adding classes to elements based on their size, the device helper and the `v-responsive` directive. Alternatively you can use `css` media queries to make your plugin responsive. Learn how to use `css` here:

## DeviceHelper

The DeviceHelper provides methods to get device and browser information like the current viewport size. The helper methods can be accessed with `this.$device` in every Vue component, since it is bound to the Vue prototype.

It makes it possible to run functions to react to `onResize` events with adding classes or removing them. The example below shows you how to use the `$device.onResize` helper.

```javascript
const listener = function (ev) {
    // do something on resize with the event, like adding or removing classes to elements   
};

const scope = this;
const component = 'sw-basic-example';

this.$device.onResize({ listener, scope, component });
```

The code snippet before could be placed in the `mounted` [Vue lifecycle](https://vuejs.org/v2/guide/instance.html#Lifecycle-Diagram) hook to register those listeners automatically. Then you can automatically remove the listeners in the `onDestroy` hook

```javascript
this.$device.removeResizeListener(component);
```

It also provides many helper functions e.g. to get the screen dimensions. Although there are many more as seen below:

| Function | Description |
| :--- | :--- |
| `this.$device.getViewportWidth();` | Gets the viewport width |
| `this.$device.getViewportHeight();` | Gets the viewport height |
| `this.$device.getDevicePixelRatio();` | Gets the device pixel ratio |
| `this.$device.getScreenWidth();` | Gets the screen width |
| `this.$device.getScreenHeight();` | Gets screen height |
| `this.$device.getScreenOrientation();` | Gets the screen orientation |

## v-responsive directive

The `v-responsive` directive can be used to dynamically apply classes based on an element's dimensions.

```html
<input v-responsive="{ 'is--compact': el => el.width <= 1620, timeout: 200 }">
```

Let's do a small explanation of this directive:

* Apply class (in this case: `is--compact`) when the width of the element is smaller than 1620px.
* `timeout`: Sets the duration on how much the throttle should wait.

---

---
url: >-
  /docs/guides/plugins/plugins/administration/templates-styling/adding-responsive-behavior.md
---

# Adding Responsive Behavior

## Overview

The Shopware 6 Administration provides two ways of adding classes to elements based on their size, the device helper and the `v-responsive` directive. Alternatively, you can use `css` media queries to make your plugin responsive. Learn how to use `css` here:

## DeviceHelper

The DeviceHelper provides methods to retrieve device and browser information, such as the current viewport size. The helper methods can be accessed with `this.$device` in every Vue component, since it is bound to the Vue prototype.

It makes it possible to run functions that respond to `onResize` events by adding or removing classes. The example below shows you how to use the `$device.onResize` helper.

```javascript
const listener = function (ev) {
    // do something on resize with the event, like adding or removing classes to elements   
};

const scope = this;
const component = 'sw-basic-example';

this.$device.onResize({ listener, scope, component });
```

The code snippet before could be placed in the `mounted` [Vue lifecycle](https://vuejs.org/v2/guide/instance.html#Lifecycle-Diagram) hook to register those listeners automatically. Then you can automatically remove the listeners in the `onDestroy` hook

```javascript
this.$device.removeResizeListener(component);
```

It also provides many helper functions, e.g., to get the screen dimensions. Although there are many more, as seen below:

| Function | Description |
| :--- | :--- |
| `this.$device.getViewportWidth();` | Gets the viewport width |
| `this.$device.getViewportHeight();` | Gets the viewport height |
| `this.$device.getDevicePixelRatio();` | Gets the device pixel ratio |
| `this.$device.getScreenWidth();` | Gets the screen width |
| `this.$device.getScreenHeight();` | Gets screen height |
| `this.$device.getScreenOrientation();` | Gets the screen orientation |

## v-responsive directive

The `v-responsive` directive can be used to apply classes based on an element's dimensions dynamically.

```html
<input v-responsive="{ 'is--compact': el => el.width <= 1620, timeout: 200 }">
```

Let's do a small explanation of this directive:

* Apply class (in this case: `is--compact`) when the width of the element is smaller than 1620px.
* `timeout`: Sets the duration for how long the throttle should wait.

---

---
url: >-
  /docs/guides/plugins/plugins/administration/services-utilities/add-custom-service.md
---

# Adding Services

## Overview

This guide will teach you how to add a service to the Shopware 6 Administration, using [BottleJS](https://github.com/young-steveo/bottlejs).

This documentation chapter will cover the following topics:

* What is an Administration service?
* How to register a new Administration service for your plugin

## Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files and a running plugin. Of course you'll have to understand JavaScript, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation.

## Register a new service

For this example, we want to use the following service. It's supposed to get random jokes. It is placed in `<administration root>/services/joke.service.js` and looks like the example seen below:

```javascript
export default class JokeService {
    constructor(httpClient) {
        this.httpClient = httpClient;
    }

    joke() {
        return this.httpClient
            .get('https://v2.jokeapi.dev/joke/Programming?blacklistFlags=nsfw,religious,political')
            .then(response => response.data)
    }
}
```

For now this service class is not available in the injection container. To fix this, a new script is placed at `<administration root>/init/joke-service.init.js` and imported in the `main.js` file of our plugin:

```javascript
import JokeService from '../services/joke.service'

Shopware.Service().register('joker', (container) => {
    const initContainer = Shopware.Application.getContainer('init');
    return new JokeService(initContainer.httpClient);
});
```

## Service injection

A service is typically injected into a vue component and can simply be referenced in the `inject` property:

```javascript
Shopware.Component.register('swag-basic-example', {
    inject: ['joker'],

    created() {
        this.joker.joke().then(joke => console.log(joke))
    }
});
```

To avoid collision with other properties like computed fields or data fields there is an option to rename the service property using an object:

```javascript
Shopware.Component.register('swag-basic-example', {
    inject: {
        jokeService: 'joker'
    },

    created() {
        this.jokeService.joke().then(joke => console.log(joke))
    }
});
```

## Adding a middleware

BottleJS also allows us to add middleware to our services.

This code sample is based on the example in the [BottleJS documentation](https://github.com/young-steveo/bottlejs#middlewarename-func). For this we need to change our previously used service, as seen below:

```javascript
class JokeService {
    constructor(httpClient) {
        this.httpClient = httpClient;
        this.isActive = false;
    }

    joke() {
        return this.httpClient
            .get(`https://v2.jokeapi.dev/joke/Programming?blacklistFlags=nsfw,religious,political`)
            .then(response => response.data)
    }
}
```

Now that we've added an `isActive` flag, we can react to it in our middleware and throw an exception if the service is not active.

```javascript
Shopware.Application.addServiceProviderMiddleware('joker', (service, next) => {
    if(!service.isActive) {
        return next(new Error('Service is inActive'));
    }

    next();
});

Shopware.Service().register('joker', (container) => {
    const initContainer = Shopware.Application.getContainer('init');
    return new JokeService(initContainer.httpClient);
});
```

## Decorating a service

Service decoration can be us in a variety of ways. Services can be initialized right after their creation and single methods can get an altered behavior. Like in the service registration, a script that is part of the `main.js` is needed.

::: warning
Decorators are just simple functions, which intercept a service in the provider phase. This means that a service can only be decorated in the timeframe between it being created and it being accessed for the first time.
:::

If you need to alter a service method return value or add an additional parameter you can also do this using decoration. For this example a `funny` attribute is added to the requested jokes by the previously registered `JokeService`:

```javascript
Shopware.Application.addServiceProviderDecorator('joker', joker => {
    const decoratedMethod = joker.joke;

    joker.joke = function () {
        return decoratedMethod.call(joker).then(joke => ({
            ...joke,
            funny: joke.id % 2 === 0
        }))
    };

    return joker;
});
```

## Next steps

Now that we have created a service, you might want to create or customize a Administration component:

* [Creating a new administration component](../module-component-management/add-custom-component.md)
* [Extending an existing administration component](../module-component-management/customizing-components.md) .

---

---
url: /docs/v6.5/guides/plugins/plugins/administration/add-custom-service.md
---

# Adding Services

## Overview

This guide will teach you how to add a service to the Shopware 6 Administration, using [BottleJS](https://github.com/young-steveo/bottlejs).

This documentation chapter will cover the following topics:

* What is an Administration service?
* How to register a new Administration service for your plugin

## Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files and a running plugin. Of course you'll have to understand JavaScript, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation.

## Register a new service

For this example, we want to use the following service. It's supposed to get random jokes. It is placed in `<administration root>/services/joke.service.js` and looks like the example seen below:

```javascript
export default class JokeService {
    constructor(httpClient) {
        this.httpClient = httpClient;
    }

    joke() {
        return this.httpClient
            .get('https://v2.jokeapi.dev/joke/Programming?blacklistFlags=nsfw,religious,political')
            .then(response => response.data)
    }
}
```

For now this service class is not available in the injection container. To fix this, a new script is placed at `<administration root>/init/joke-service.init.js` and imported in the `main.js` file of our plugin:

```javascript
import JokeService from '../services/joke.service'

Shopware.Service().register('joker', (container) => {
    const initContainer = Shopware.Application.getContainer('init');
    return new JokeService(initContainer.httpClient);
});
```

## Service injection

A service is typically injected into a vue component and can simply be referenced in the `inject` property:

```javascript
Shopware.Component.register('swag-basic-example', {
    inject: ['joker'],

    created() {
        this.joker.joke().then(joke => console.log(joke))
    }
});
```

To avoid collision with other properties like computed fields or data fields there is an option to rename the service property using an object:

```javascript
Shopware.Component.register('swag-basic-example', {
    inject: {
        jokeService: 'joker'
    },

    created() {
        this.jokeService.joke().then(joke => console.log(joke))
    }
});
```

## Adding a middleware

BottleJS also allows us to add middleware to our services.

This code sample is based on the example in the [BottleJS documentation](https://github.com/young-steveo/bottlejs#middlewarename-func). For this we need to change our previously used service, as seen below:

```javascript
class JokeService {
    constructor(httpClient) {
        this.httpClient = httpClient;
        this.isActive = false;
    }

    joke() {
        return this.httpClient
            .get(`https://v2.jokeapi.dev/joke/Programming?blacklistFlags=nsfw,religious,political`)
            .then(response => response.data)
    }
}
```

Now that we've added an `isActive` flag, we can react to it in our middleware and throw an exception if the service is not active.

```javascript
Shopware.Application.addServiceProviderMiddleware('joker', (service, next) => {
    if(!service.isActive) {
        return next(new Error('Service is inActive'));
    }

    next();
});

Shopware.Service().register('joker', (container) => {
    const initContainer = Shopware.Application.getContainer('init');
    return new JokeService(initContainer.httpClient);
});
```

## Decorating a service

Service decoration can be us in a variety of ways. Services can be initialized right after their creation and single methods can get an altered behavior. Like in the service registration, a script that is part of the `main.js` is needed.

::: warning
Decorators are just simple functions, which intercept a service in the provider phase. This means that a service can only be decorated in the timeframe between it being created and it being accessed for the first time.
:::

If you need to alter a service method return value or add an additional parameter you can also do this using decoration. For this example a `funny` attribute is added to the requested jokes by the previously registered `JokeService`:

```javascript
Shopware.Application.addServiceProviderDecorator('joker', joker => {
    const decoratedMethod = joker.joke;

    joker.joke = function () {
        return decoratedMethod.call(joker).then(joke => ({
            ...joke,
            funny: joke.id % 2 === 0
        }))
    };

    return joker;
});
```

## Next steps

Now that we have created a service, you might want to create or customize a Administration component:

* [Creating a new administration component](add-custom-component)
* [Extending an existing administration component](customizing-components)

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/administration/services-utilities/add-custom-service.md
---

# Adding Services

## Overview

This guide will teach you how to add a service to the Shopware 6 Administration, using [BottleJS](https://github.com/young-steveo/bottlejs).

This documentation chapter will cover the following topics:

* What is an Administration service?
* How to register a new Administration service for your plugin

## Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files and a running plugin. Of course you'll have to understand JavaScript, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation.

## Register a new service

For this example, we want to use the following service. It's supposed to get random jokes. It is placed in `<administration root>/services/joke.service.js` and looks like the example seen below:

```javascript
export default class JokeService {
    constructor(httpClient) {
        this.httpClient = httpClient;
    }

    joke() {
        return this.httpClient
            .get('https://v2.jokeapi.dev/joke/Programming?blacklistFlags=nsfw,religious,political')
            .then(response => response.data)
    }
}
```

For now this service class is not available in the injection container. To fix this, a new script is placed at `<administration root>/init/joke-service.init.js` and imported in the `main.js` file of our plugin:

```javascript
import JokeService from '../services/joke.service'

Shopware.Service().register('joker', (container) => {
    const initContainer = Shopware.Application.getContainer('init');
    return new JokeService(initContainer.httpClient);
});
```

## Service injection

A service is typically injected into a vue component and can simply be referenced in the `inject` property:

```javascript
Shopware.Component.register('swag-basic-example', {
    inject: ['joker'],

    created() {
        this.joker.joke().then(joke => console.log(joke))
    }
});
```

To avoid collision with other properties like computed fields or data fields there is an option to rename the service property using an object:

```javascript
Shopware.Component.register('swag-basic-example', {
    inject: {
        jokeService: 'joker'
    },

    created() {
        this.jokeService.joke().then(joke => console.log(joke))
    }
});
```

## Adding a middleware

BottleJS also allows us to add middleware to our services.

This code sample is based on the example in the [BottleJS documentation](https://github.com/young-steveo/bottlejs#middlewarename-func). For this we need to change our previously used service, as seen below:

```javascript
class JokeService {
    constructor(httpClient) {
        this.httpClient = httpClient;
        this.isActive = false;
    }

    joke() {
        return this.httpClient
            .get(`https://v2.jokeapi.dev/joke/Programming?blacklistFlags=nsfw,religious,political`)
            .then(response => response.data)
    }
}
```

Now that we've added an `isActive` flag, we can react to it in our middleware and throw an exception if the service is not active.

```javascript
Shopware.Application.addServiceProviderMiddleware('joker', (service, next) => {
    if(!service.isActive) {
        return next(new Error('Service is inActive'));
    }

    next();
});

Shopware.Service().register('joker', (container) => {
    const initContainer = Shopware.Application.getContainer('init');
    return new JokeService(initContainer.httpClient);
});
```

## Decorating a service

Service decoration can be us in a variety of ways. Services can be initialized right after their creation and single methods can get an altered behavior. Like in the service registration, a script that is part of the `main.js` is needed.

::: warning
Decorators are just simple functions, which intercept a service in the provider phase. This means that a service can only be decorated in the timeframe between it being created and it being accessed for the first time.
:::

If you need to alter a service method return value or add an additional parameter you can also do this using decoration. For this example a `funny` attribute is added to the requested jokes by the previously registered `JokeService`:

```javascript
Shopware.Application.addServiceProviderDecorator('joker', joker => {
    const decoratedMethod = joker.joke;

    joker.joke = function () {
        return decoratedMethod.call(joker).then(joke => ({
            ...joke,
            funny: joke.id % 2 === 0
        }))
    };

    return joker;
});
```

## Next steps

Now that we have created a service, you might want to create or customize a Administration component:

* [Creating a new administration component](../module-component-management/add-custom-component.md)
* [Extending an existing administration component](../module-component-management/customizing-components.md) .

---

---
url: >-
  /docs/guides/plugins/plugins/administration/advanced-configuration/add-shortcuts.md
---

# Adding Shortcuts

## Overview

Shortcuts in Shopware 6 are defined on a Component basis. This guide will show you how to add your own ones.

## Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files and preferably a registered module and custom component.
Of course, you'll have to understand JavaScript, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation.

## Configuring the Shortcuts

The following code sample will show you how to register shortcuts in your components with help of the `shortcuts` attribute.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/swag-example/index.js
const { Component } = Shopware;

Component.register('swag-basic-example', {
    
    shortcuts: {
        'SYSTEMKEY+S': {
            active() {
                return this.acl.can('product.editor');
            },
            method: 'myEditProductFunction'
        },
        ESCAPE: 'myCancelEditProductFunction'
    },

   
    methods: {
        myEditProductFunction() {
            console.log("myEditProductFunction")
        },
        myCancelEditProductFunction() {
            console.log("myCancelEditProductFunction")
        }
    }
});
```

The first keyboard shortcut reacts to the key combination of `SYSTEMKEY+S`, only if the user has the privilege `product.editor`, with the invocation of the component method with the name `myEditProductFunction`.
The second keyboard shortcut defines that, upon the `ESCAPE` key being pressed, the function with the name `myCancelEditProductFunction` should be invoked.

The before mentioned `SYSTEMKEY` is `CTRL` on macOS and `ALT` on Windows, other system-keys like `CTRL` on Windows or `⌥` on macOS are not supported.

Since ACL is used in the first keyboard shortcut, you might want to learn more about ACL and how to add your own ACL rules [here](../permissions-error-handling/add-acl-rules.md).

## More interesting topics

* [Writing templates](../templates-styling/writing-templates.md)
* [Adding styles](../templates-styling/add-custom-styles.md)

---

---
url: /docs/v6.5/guides/plugins/plugins/administration/add-shortcuts.md
---

# Adding Shortcuts

## Overview

Shortcuts in Shopware 6 are defined on a Component basis. This guide will show you how to add your own ones.

## Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files and preferably a registered module and custom component.
Of course you'll have to understand JavaScript, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation.

## Configuring the Shortcuts

The following code sample will show you how to register shortcuts in your components with help of the `shortcuts` attribute.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/swag-example/index.js
const { Component } = Shopware;

Component.register('swag-basic-example', {
    
    shortcuts: {
        'SYSTEMKEY+S': {
            active() {
                return this.acl.can('product.editor');
            },
            method: 'myEditProductFunction'
        },
        ESCAPE: 'myCancelEditProductFunction'
    },

   
    methods: {
        myEditProductFunction() {
            console.log("myEditProductFunction")
        },
        myCancelEditProductFunction() {
            console.log("myCancelEditProductFunction")
        }
    }
});
```

The first keyboard shortcut reacts to the key combination of `SYSTEMKEY+S`, only if the user has the privilege `product.editor`, with the invocation of the component method with the name `myEditProductFunction`.
The second keyboard shortcut defines that, upon the `ESCAPE` key being pressed, the function with the name `myCancelEditProductFunction` should be invoked.

The before mentioned `SYSTEMKEY` is `CTRL` on macOS and `ALT` on Windows, other system-keys like `CTRL` on Windows or `⌥` on macOS are not supported.

Since ACL is used in the first keyboard shortcut you might want to learn more about ACL and how to add your own ACL rules [here](./add-acl-rules).

## More interesting topics

* [Writing templates](./writing-templates)
* [Adding styles](./add-custom-styles)

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/administration/advanced-configuration/add-shortcuts.md
---

# Adding Shortcuts

## Overview

Shortcuts in Shopware 6 are defined on a Component basis. This guide will show you how to add your own ones.

## Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files and preferably a registered module and custom component.
Of course, you'll have to understand JavaScript, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation.

## Configuring the Shortcuts

The following code sample will show you how to register shortcuts in your components with help of the `shortcuts` attribute.

```javascript
// <plugin root>/src/Resources/app/administration/src/module/swag-example/index.js
const { Component } = Shopware;

Component.register('swag-basic-example', {
    
    shortcuts: {
        'SYSTEMKEY+S': {
            active() {
                return this.acl.can('product.editor');
            },
            method: 'myEditProductFunction'
        },
        ESCAPE: 'myCancelEditProductFunction'
    },

   
    methods: {
        myEditProductFunction() {
            console.log("myEditProductFunction")
        },
        myCancelEditProductFunction() {
            console.log("myCancelEditProductFunction")
        }
    }
});
```

The first keyboard shortcut reacts to the key combination of `SYSTEMKEY+S`, only if the user has the privilege `product.editor`, with the invocation of the component method with the name `myEditProductFunction`.
The second keyboard shortcut defines that, upon the `ESCAPE` key being pressed, the function with the name `myCancelEditProductFunction` should be invoked.

The before mentioned `SYSTEMKEY` is `CTRL` on macOS and `ALT` on Windows, other system-keys like `CTRL` on Windows or `⌥` on macOS are not supported.

Since ACL is used in the first keyboard shortcut, you might want to learn more about ACL and how to add your own ACL rules [here](../permissions-error-handling/add-acl-rules.md).

## More interesting topics

* [Writing templates](../templates-styling/writing-templates.md)
* [Adding styles](../templates-styling/add-custom-styles.md)

---

---
url: /docs/v6.5/guides/plugins/plugins/administration/adding-snippets.md
---

# Adding snippets

## Overview

By default Shopware 6 uses the [Vue I18n](https://kazupon.github.io/vue-i18n/started.html#html) plugin in the `Administration` to deal with translation.

## Creating snippet files

Normally you use snippets in your custom module. To keep things organized, create a new directory named `snippet` inside module directory `<plugin root>/src/Resources/app/administration/src/module/<your-module>/snippet`. For each language you want to support, you need a JSON file inside it, e.g., `de-DE.json`, `en-GB.json`.

::: info
Providing snippets for apps works the same as in plugins but it has a more simplistic file structure. Also, unlike plugins, App-Snippets **are not allowed** to override existing snippet keys. So, use the following path for vendor-prefixed app snippet files: `<app root>/Resources/app/administration/snippet`
:::

Each language then receives a nested object of translations, so let's have a look at an example `snippet/en-GB.json`:

```json
{
    "swag-example": {
        "nested": {
            "value": "example",
            "examplePluralization": "1 Product | {n} Products"
        },
        "foo": "bar"
    }
}
```

In this example you would have access the two translations by the following paths: `swag-example.nested.value` to get the value 'example' and `swag-example.foo` to get the value 'bar'. You can nest those objects as much as you want.

By default, Shopware 6 will collect those files automatically when your plugin is activated.

::: info
When you do not build a module and therefore do not fit into the suggested directory structure, you can still place the translation files anywhere in `<plugin root>/src/Resources/app/administration/`.
:::

## Using the snippets in JavaScript

Since snippets are automatically registered in the scope of your module, you can use them directly:

```javascript
Component.register('my-custom-page', {
    ...

    methods: {
        createdComponent() {
            // call the $tc helper function provided by Vue I18n 
            const myCustomText = this.$tc('swag-example.general.myCustomText');

            console.log(myCustomText);
        }
    }
    ...
});
```

## Using the snippets in templates

The same `$tc` helper function can be used in the templates to access translations.

```twig
{% block my_custom_block %}
    <p>
       {{ $tc('swag-example.general.myCustomText') }}
    </p>
{% endblock %}
```

Another feature of `$tc` is pluralization. Use a `|` in snippets to provide translations depending on the number. The first part shows singular expression, while the second takes care of plural cases.
Let's have a look at this example of `"examplePluralization": "One Product | {n} Products"` with the following implementation:

```twig
{% block my_custom_block %}
    <p>
       {{ $tc('swag-example.nested.examplePluralization', products.length) }}
    </p>
{% endblock %}
```

If you provide `1` as the second parameter to `$tc()`, the text `One Product` would be rendered. For any other value greater than 1, the number itself is shown — for example, `4 Products`.

## More interesting topics

* [Learning about the global Shopware object](the-shopware-object)
* [Learning about the VueX state](https://github.com/shopware/docs/tree/575c2fa12ef272dc25744975e2f1e4d44721f0f1/guides/plugins/plugins/administration/using-vuex-state.md)

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/administration/templates-styling/adding-snippets.md
---

# Adding snippets

## Overview

By default Shopware 6 uses the [Vue I18n](https://kazupon.github.io/vue-i18n/started.html#html) plugin in the `Administration` to deal with translation.

## Creating snippet files

Normally you use snippets in your custom module. To keep things organized, create a new directory named `snippet` inside module directory `<plugin root>/src/Resources/app/administration/src/module/<your-module>/snippet`. For each language you want to support, you need a JSON file inside it, e.g., `de-DE.json`, `en-GB.json`.

::: info
Providing snippets for apps works the same as in plugins but it has a more simplistic file structure. Also, unlike plugins, App-Snippets **are not allowed** to override existing snippet keys. So, use the following path for vendor-prefixed app snippet files: `<app root>/Resources/app/administration/snippet`
:::

Each language then receives a nested object of translations, so let's have a look at an example `snippet/en-GB.json`:

```json
{
    "swag-example": {
        "nested": {
            "value": "example",
            "examplePluralization": "1 Product | {n} Products"
        },
        "foo": "bar"
    }
}
```

In this example you would have access the two translations by the following paths: `swag-example.nested.value` to get the value 'example' and `swag-example.foo` to get the value 'bar'. You can nest those objects as much as you want.

By default, Shopware 6 will collect those files automatically when your plugin is activated.

::: info
When you do not build a module and therefore do not fit into the suggested directory structure, you can still place the translation files anywhere in `<plugin root>/src/Resources/app/administration/src/`.
:::

## Using the snippets in JavaScript

Since snippets are automatically registered in the scope of your module, you can use them directly:

```javascript
Component.register('my-custom-page', {
    ...

    methods: {
        createdComponent() {
            // call the $tc helper function provided by Vue I18n 
            const myCustomText = this.$tc('swag-example.general.myCustomText');

            console.log(myCustomText);
        }
    }
    ...
});
```

Or use `Shopware.Snippet.tc('swag-example.general.myCustomText')` when `this` doesn't point to a component (see also [Vue3 upgrade](../../../../../resources/references/upgrades/administration/vue3.md))

## Using the snippets in templates

The same `$tc` helper function can be used in the templates to access translations.

```twig
{% block my_custom_block %}
    <p>
       {{ $tc('swag-example.general.myCustomText') }}
    </p>
{% endblock %}
```

Another feature of `$tc` is pluralization. Use a `|` in snippets to provide translations depending on the number. The first part shows singular expression, while the second takes care of plural cases.
Let's have a look at this example of `"examplePluralization": "One Product | {n} Products"` with the following implementation:

```twig
{% block my_custom_block %}
    <p>
       {{ $tc('swag-example.nested.examplePluralization', products.length) }}
    </p>
{% endblock %}
```

If you provide `1` as the second parameter to `$tc()`, the text `One Product` would be rendered. For any other value greater than 1, the number itself is shown — for example, `4 Products`.

## More interesting topics

* [Learning about the global Shopware object](../data-handling-processing/the-shopware-object.md)
* [Learning about the VueX state](https://github.com/shopware/docs/tree/575c2fa12ef272dc25744975e2f1e4d44721f0f1/guides/plugins/plugins/administration/using-vuex-state.md)

---

---
url: >-
  /docs/guides/plugins/plugins/administration/templates-styling/adding-snippets.md
---

# Adding Snippets

## Overview

By default Shopware 6 uses the [Vue I18n](https://kazupon.github.io/vue-i18n/started.html#html) plugin in the `Administration` to deal with translation.

## Creating snippet files

Normally you use snippets in your custom module. To keep things organized, create a new directory named `snippet` inside module directory `<plugin root>/src/Resources/app/administration/src/module/<your-module>/snippet`. For each language you want to support, you need a JSON file inside it, e.g., `de-DE.json`, `en-GB.json`. For more details on selecting a fallback language and structuring your snippet files, see the [Fallback Languages guide](../../../../../concepts/framework/translations/fallback-language-selection.md).

::: info
Providing snippets for apps works the same as in plugins but it has a more simplistic file structure. Also, unlike plugins, App-Snippets **are not allowed** to override existing snippet keys. So, use the following path for vendor-prefixed app snippet files: `<app root>/Resources/app/administration/snippet`
:::

Each language then receives a nested object of translations, so let's have a look at an example `snippet/en-GB.json`:

```json
{
    "swag-example": {
        "nested": {
            "value": "example",
            "examplePluralization": "1 Product | {n} Products"
        },
        "foo": "bar"
    }
}
```

In this example you would have access the two translations by the following paths: `swag-example.nested.value` to get the value 'example' and `swag-example.foo` to get the value 'bar'. You can nest those objects as much as you want.

By default, Shopware 6 will collect those files automatically when your plugin is activated.

::: info
When you do not build a module and therefore do not fit into the suggested directory structure, you can still place the translation files anywhere in `<plugin root>/src/Resources/app/administration/src/`.
:::

## Using the snippets in JavaScript

Since snippets are automatically registered in the scope of your module, you can use them directly:

```javascript
Component.register('my-custom-page', {
    ...

    methods: {
        createdComponent() {
            // call the $tc helper function provided by Vue I18n
            const myCustomText = this.$tc('swag-example.general.myCustomText');

            console.log(myCustomText);
        }
    }
    ...
});
```

Or use `Shopware.Snippet.tc('swag-example.general.myCustomText')` when `this` doesn't point to a component (see also [Vue3 upgrade](../../../../upgrades-migrations/administration/vue3.md)).

## Using the snippets in templates

The same `$tc` helper function can be used in the templates to access translations.

```twig
{% block my_custom_block %}
    <p>
       {{ $tc('swag-example.general.myCustomText') }}
    </p>
{% endblock %}
```

Another feature of `$tc` is pluralization. Use a `|` in snippets to provide translations depending on the number. The first part shows singular expression, while the second takes care of plural cases.
Let's have a look at this example of `"examplePluralization": "One Product | {n} Products"` with the following implementation:

```twig
{% block my_custom_block %}
    <p>
       {{ $tc('swag-example.nested.examplePluralization', products.length) }}
    </p>
{% endblock %}
```

If you provide `1` as the second parameter to `$tc()`, the text `One Product` would be rendered. For any other value greater than 1, the number itself is shown — for example, `4 Products`.

## More interesting topics

* [Learning about the global Shopware object](../data-handling-processing/the-shopware-object.md)
* [Learning about the VueX state](https://github.com/shopware/docs/blob/575c2fa12ef272dc25744975e2f1e4d44721f0f1/guides/plugins/plugins/administration/using-vuex-state.md)

---

---
url: >-
  /docs/resources/references/adr/2022-07-21-adding-the-storable-flow-to-implement-delay-action-in-flow-builder.md
---

# Adding the `StorableFlow` instead of the `FlowEvent` for implementing the flow DelayAction in flow builder

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-07-21-adding-the-storable-flow-to-implement-delay-action-in-flow-builder.md)
:::

## Context

The actions in Flow Builder are listening for Business Events. We want to implement the flow DelayAction in Flow Builder,
that means the actions can be delayed, and will be executed after  a set amount of time.
But we have some problems after the action was delayed:

* Events may contain old data, that data may be updated during the delay, and currently we don't have any way to restore
  the data.
* After a delay the rules have to be re-evaluated, but the data in the rules could be outdated or changed, so the rules
  have to be reloaded as well. Or the rules do not exist anymore.

## Decision

We would need to detach the Event System and the Flow System from each other, thus removing the dependency on the runtime objects within an event.
Meaning the Actions must not have access to the original Events.

We would create a class `StorableFlow`, that can store the data in the original event as scalar values, and restore the original data based on this stored data.

```php
class StorableFlow
{
    // contains the scalar values based on the original events
    // $store can be serialized and used to restore the object data
    protected array $store = [];
    
    // contains the restored object data like the data we defined in the `availableData` in original events 
    // $data can not be serialized, but can be restored from $store
    protected array $data = [];
      
    public function __construct(array $store = [], array $data = [])
    {
        $this->store = $store;
        $this->data = $data;
    }
    
    // This method will be called in each `Storer` to store the representation of data
    public function setStore(string $key, $value) {
        $this->store[$key] = $value;
    }
    
    public function getStore(string $key) {
        return $this->store[$key];
    }
    
    // After we restored the data in `Storer`, we can set the data, we'll use `$this->data` instead getter data on original event
    public function setData(string $key, $value) {
        $this->data[$key] = $value;
    }
    
    public function getData(string $key) {
        return $this->data[$key];
    }
}
```

The `StorableFlow` class will be use on Flow Builder:

Before:

```php
class FlowDispatcher 
{
    public function dispatch(Event $event) {
        ...
        // Currently, dispatch on Flow Builder use the original event to execute the Flow 
        $this->callFlowExecutor($event);
        ...
    }
}
```

After:

```php
class FlowDispatcher 
{
    public function dispatch(Event $event) {
        ...
        // The `FlowFactory` will create/restore the `StorableFlow` from original event
        $flow = $this->flowFactory->create($event);
        // use the `StorableFlow` to execute the flow builder actions instead of the original events
        $this->execute($flow);
        ...
    }
}
```

* Flow Builder actions may no longer access the original event.
* Each Aware Interface gets its own `Storer` class to restore the data of Aware, so we have many `Storer` like `OrderStorer`, `MailStorer`, `CustomerStorer` ...
* The main task of a `Storer` is to restore the data from a scalar storage.
* The `Storer` provides a store function, in order to store itself the data, in order restore the object
* The `Storer` provides a restore function to restore the object using the store data.

```php
interface FlowStorer {}
```

Example for `OrderStorer`:

```php
class OrderStorer implements FlowStorer
{
    // This function to check the original event is the instanceof Aware interface, and store the representation.
    public function store(FlowEventAware $event, array $storedData): array 
    {
        if ($event instanceof OrderAware) {
            $storedData['orderId'] = $event->getOrderId();
        }
        
        return $storedData;
    }
    
    // This function is restore the data based on representation in `storedData`
    public function restore(StorableFlow $flow): void
    {
        if ($flow->hasStore('orderId')) {
            // allows to provide a closure for lazy data loading
            // this opens the opportunity to have lazy loading for big data
            // When we load the entity, we need to add the necessary associations for each entity
            $flow->lazy('order', [$this, 'load']);    
        }
        ...
    }
}
```

About the additional data defined in `availableData` in original events, that aren't defined in any Aware Interfaces and we can't restore that data in the `Storer`.
To cover the additional data from original events, we will have another `store` `AdditionalStorer` to store those data.

```php
class AdditionalStorer extends FlowStorer
{
    public function store(FlowEventAware $event, array $storedData)
    {
        ...
        // based on the `getAvailableData` in the original event to get the type of additional data
        $additionalDataTypes = $event::getAvailableData()->toArray();
        
        foreach ($additionalDataTypes as $key => $eventData) {
            // Check if the type of data is Entity or EntityCollection
            // in the $storedData, we only store the presentation like ['id' => id, 'entity' => entity], we'll restore the data in `AdditionalStorer::restore`
            if ($eventData['type'] === 'Entity' || 'EntityCollection') {
                $storedData[$key] = [
                    'id' => $event->getId(),
                    'entity' => Entity                 
                ];
            }
            
            // Check if the type of data is ScalarValueType
            if ($eventData['type'] === ScalarValueType) {
                $storedData[$key] = value
            }
            
            // start to implement /Serializable for ObjectType
            if ($eventData['type'] === ObjectType) {
                $storedData[$key] = value->serialize()
            }
            
            ...
        }
        
        ... 
        
        return $storedData;
    }
      
    // this function  make sure we can restore the additional data from original data are not covered in `Storer`
    // The additional data can be other entity, because the entities we defined in Aware interface like `order`, `customer` ... covered be `Storer`
    public function restore(StorableFlow $flow): void
    {
        if (type === entity) {
            // About the associations for entity data, mostly the additional entity data is the base entity, we don't need to add associations for this
            $flow->setData($key, $this->load());
        } else {
            $flow->setData($key, $flow->getStore($key));
        }
        ...
    }
}
```

About the associations for entity data, mostly the additional entity data is the base entity, we don't need to add associations for this.
About the `ObjectType` data, we enforce all values used in ObjectType implement /Serializable, and serialize the object before store to `$storedData`.

* Flow Builder actions only work with the `StorableFlow` instead of the `FlowEvent`. The `StorableFlow` will restore the data from original events via `Storer`,
  and the Actions can get the data via `getData($key)` from `StorableFlow` instead of `getAvailableData` from original events.

Before, in the flow actions still dependency Aware interfaces:

```php
    public function handle(StorableFlow $event) {
        ...
        $baseEvent = $event->getEvent();
    
        if ($baseEvent instanceof CustomerAware) {
            $customerId= $baseEvent->getCustomerId();
        }
        ...
    }
```

After in the flow actions:

```php
    public function handle(StorableFlow $event) {
        ...
        if ($event->hasStore('customerId') {
            $customerId= $event->getStore('customerId');
        }
        ...
    }
```

* `getAvailableData` must NOT be responsible for the access of the data.
* To create new or restore the `StorableFlow` by on the existing stored data, we need to provider the `FlowFactory`.

```php
class FlowFactory
{    
    ...
    public function create(FlowEventAware $event)
    {
        $storedData = [];
        foreach ($this->storer as $storer) {
            // Storer are responsible to move the corresponding 
            // data from the original event 
            $storer->store($event, $storedData);
        }
        
        return $this->restore($storedData);
    }
  
    public function restore(array $stored = [], array $data = [])
    {
        $flow = new StorableFlow($stored, $data);
      
        foreach ($this->storer as $storer) {
            $storer->restore($flow);
        }
  
        return $flow;
    }
    ...
}
```

But when executing a delayed actions, we won't have a `StorableFlow`, we just have the `$stored` from the previously stored `StorableFlow`,
and based on the `$stored`, we can restore a new `StorableFlow`.

Example in Delay Actions:

```php
// In handler delay actions -> put the actions to `queue`
$stored = json_encode($flow->stored());

$connection->executeStatement('INSERT INTO `swag_delay_action` (store) VALUES (:stored)...', ['stored' => $stored]);
```

```php
// In handler execute delay actions
$stored = 'SELECT store FROM `swag_delay_action` .... ';

$flow = $this->flowFactory->restore(json_decode($stored));
```

## Consequences

Because we use the new class `StorableFlow` instead of the `FlowEvent` class in the Flow Builder, we cannot use the original
events or aware interfaces anymore, but about the symfony event was listeners the `FlowEvent`, those can continue to
use the interfaces as the store is not yet filled during we'll remove it in next major version.

* In symfony event listeners: only use the interfaces as the store is not yet filled
* In the flow builder: Only use the store functionality as the interfaces might not be implemented

---

---
url: >-
  /docs/v6.5/resources/references/adr/2022-07-21-adding-the-storable-flow-to-implement-delay-action-in-flow-builder.md
---

# Adding the `StorableFlow` instead of the `FlowEvent` for implementing the flow DelayAction in flow builder

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-07-21-adding-the-storable-flow-to-implement-delay-action-in-flow-builder.md)
:::

## Context

The actions in Flow Builder are listening for Business Events. We want to implement the flow DelayAction in Flow Builder,
that means the actions can be delayed, and will be executed after  a set amount of time.
But we have some problems after the action was delayed:

* Events may contain old data, that data may be updated during the delay, and currently we don't have any way to restore
  the data.
* After a delay the rules have to be re-evaluated, but the data in the rules could be outdated or changed, so the rules
  have to be reloaded as well. Or the rules do not exist anymore.

## Decision

We would need to detach the Event System and the Flow System from each other, thus removing the dependency on the runtime objects within an event.
Meaning the Actions must not have access to the original Events.

We would create a class `StorableFlow`, that can store the data in the original event as scalar values, and restore the original data based on this stored data.

```php
class StorableFlow
{
    // contains the scalar values based on the original events
    // $store can be serialized and used to restore the object data
    protected array $store = [];
    
    // contains the restored object data like the data we defined in the `availableData` in original events 
    // $data can not be serialized, but can be restored from $store
    protected array $data = [];
      
    public function __construct(array $store = [], array $data = [])
    {
        $this->store = $store;
        $this->data = $data;
    }
    
    // This method will be called in each `Storer` to store the representation of data
    public function setStore(string $key, $value) {
        $this->store[$key] = $value;
    }
    
    public function getStore(string $key) {
        return $this->store[$key];
    }
    
    // After we restored the data in `Storer`, we can set the data, we'll use `$this->data` instead getter data on original event
    public function setData(string $key, $value) {
        $this->data[$key] = $value;
    }
    
    public function getData(string $key) {
        return $this->data[$key];
    }
}
```

The `StorableFlow` class will be use on Flow Builder:

Before:

```php
class FlowDispatcher 
{
    public function dispatch(Event $event) {
        ...
        // Currently, dispatch on Flow Builder use the original event to execute the Flow 
        $this->callFlowExecutor($event);
        ...
    }
}
```

After:

```php
class FlowDispatcher 
{
    public function dispatch(Event $event) {
        ...
        // The `FlowFactory` will create/restore the `StorableFlow` from original event
        $flow = $this->flowFactory->create($event);
        // use the `StorableFlow` to execute the flow builder actions instead of the original events
        $this->execute($flow);
        ...
    }
}
```

* Flow Builder actions may no longer access the original event.
* Each Aware Interface gets its own `Storer` class to restore the data of Aware, so we have many `Storer` like `OrderStorer`, `MailStorer`, `CustomerStorer` ...
* The main task of a `Storer` is to restore the data from a scalar storage.
* The `Storer` provides a store function, in order to store itself the data, in order restore the object
* The `Storer` provides a restore function to restore the object using the store data.

```php
interface FlowStorer {}
```

Example for `OrderStorer`:

```php
class OrderStorer implements FlowStorer
{
    // This function to check the original event is the instanceof Aware interface, and store the representation.
    public function store(FlowEventAware $event, array $storedData): array 
    {
        if ($event instanceof OrderAware) {
            $storedData['orderId'] = $event->getOrderId();
        }
        
        return $storedData;
    }
    
    // This function is restore the data based on representation in `storedData`
    public function restore(StorableFlow $flow): void
    {
        if ($flow->hasStore('orderId')) {
            // allows to provide a closure for lazy data loading
            // this opens the opportunity to have lazy loading for big data
            // When we load the entity, we need to add the necessary associations for each entity
            $flow->lazy('order', [$this, 'load']);    
        }
        ...
    }
}
```

About the additional data defined in `availableData` in original events, that aren't defined in any Aware Interfaces and we can't restore that data in the `Storer`.
To cover the additional data from original events, we will have another `store` `AdditionalStorer` to store those data.

```php
class AdditionalStorer extends FlowStorer
{
    public function store(FlowEventAware $event, array $storedData)
    {
        ...
        // based on the `getAvailableData` in the original event to get the type of additional data
        $additionalDataTypes = $event::getAvailableData()->toArray();
        
        foreach ($additionalDataTypes as $key => $eventData) {
            // Check if the type of data is Entity or EntityCollection
            // in the $storedData, we only store the presentation like ['id' => id, 'entity' => entity], we'll restore the data in `AdditionalStorer::restore`
            if ($eventData['type'] === 'Entity' || 'EntityCollection') {
                $storedData[$key] = [
                    'id' => $event->getId(),
                    'entity' => Entity                 
                ];
            }
            
            // Check if the type of data is ScalarValueType
            if ($eventData['type'] === ScalarValueType) {
                $storedData[$key] = value
            }
            
            // start to implement /Serializable for ObjectType
            if ($eventData['type'] === ObjectType) {
                $storedData[$key] = value->serialize()
            }
            
            ...
        }
        
        ... 
        
        return $storedData;
    }
      
    // this function  make sure we can restore the additional data from original data are not covered in `Storer`
    // The additional data can be other entity, because the entities we defined in Aware interface like `order`, `customer` ... covered be `Storer`
    public function restore(StorableFlow $flow): void
    {
        if (type === entity) {
            // About the associations for entity data, mostly the additional entity data is the base entity, we don't need to add associations for this
            $flow->setData($key, $this->load());
        } else {
            $flow->setData($key, $flow->getStore($key));
        }
        ...
    }
}
```

About the associations for entity data, mostly the additional entity data is the base entity, we don't need to add associations for this.
About the `ObjectType` data, we enforce all values used in ObjectType implement /Serializable, and serialize the object before store to `$storedData`.

* Flow Builder actions only work with the `StorableFlow` instead of the `FlowEvent`. The `StorableFlow` will restore the data from original events via `Storer`,
  and the Actions can get the data via `getData($key)` from `StorableFlow` instead of `getAvailableData` from original events.

Before, in the flow actions still dependency Aware interfaces:

```php
    public function handle(StorableFlow $event) {
        ...
        $baseEvent = $event->getEvent();
    
        if ($baseEvent instanceof CustomerAware) {
            $customerId= $baseEvent->getCustomerId();
        }
        ...
    }
```

After in the flow actions:

```php
    public function handle(StorableFlow $event) {
        ...
        if ($event->hasStore('customerId') {
            $customerId= $event->getStore('customerId');
        }
        ...
    }
```

* `getAvailableData` must NOT be responsible for the access of the data.
* To create new or restore the `StorableFlow` by on the existing stored data, we need to provider the `FlowFactory`.

```php
class FlowFactory
{    
    ...
    public function create(FlowEventAware $event)
    {
        $storedData = [];
        foreach ($this->storer as $storer) {
            // Storer are responsible to move the corresponding 
            // data from the original event 
            $storer->store($event, $storedData);
        }
        
        return $this->restore($storedData);
    }
  
    public function restore(array $stored = [], array $data = [])
    {
        $flow = new StorableFlow($stored, $data);
      
        foreach ($this->storer as $storer) {
            $storer->restore($flow);
        }
  
        return $flow;
    }
    ...
}
```

But when executing a delayed actions, we won't have a `StorableFlow`, we just have the `$stored` from the previously stored `StorableFlow`,
and based on the `$stored`, we can restore a new `StorableFlow`.

Example in Delay Actions:

```php
// In handler delay actions -> put the actions to `queue`
$stored = json_encode($flow->stored());

$connection->executeStatement('INSERT INTO `swag_delay_action` (store) VALUES (:stored)...', ['stored' => $stored]);
```

```php
// In handler execute delay actions
$stored = 'SELECT store FROM `swag_delay_action` .... ';

$flow = $this->flowFactory->restore(json_decode($stored));
```

## Consequences

Because we use the new class `StorableFlow` instead of the `FlowEvent` class in the Flow Builder, we cannot use the original
events or aware interfaces anymore, but about the symfony event was listeners the `FlowEvent`, those can continue to
use the interfaces as the store is not yet filled during we'll remove it in next major version.

* In symfony event listeners: only use the interfaces as the store is not yet filled
* In the flow builder: Only use the store functionality as the interfaces might not be implemented

---

---
url: >-
  /docs/v6.6/resources/references/adr/2022-07-21-adding-the-storable-flow-to-implement-delay-action-in-flow-builder.md
---

# Adding the `StorableFlow` instead of the `FlowEvent` for implementing the flow DelayAction in flow builder

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-07-21-adding-the-storable-flow-to-implement-delay-action-in-flow-builder.md)
:::

## Context

The actions in Flow Builder are listening for Business Events. We want to implement the flow DelayAction in Flow Builder,
that means the actions can be delayed, and will be executed after  a set amount of time.
But we have some problems after the action was delayed:

* Events may contain old data, that data may be updated during the delay, and currently we don't have any way to restore
  the data.
* After a delay the rules have to be re-evaluated, but the data in the rules could be outdated or changed, so the rules
  have to be reloaded as well. Or the rules do not exist anymore.

## Decision

We would need to detach the Event System and the Flow System from each other, thus removing the dependency on the runtime objects within an event.
Meaning the Actions must not have access to the original Events.

We would create a class `StorableFlow`, that can store the data in the original event as scalar values, and restore the original data based on this stored data.

```php
class StorableFlow
{
    // contains the scalar values based on the original events
    // $store can be serialized and used to restore the object data
    protected array $store = [];
    
    // contains the restored object data like the data we defined in the `availableData` in original events 
    // $data can not be serialized, but can be restored from $store
    protected array $data = [];
      
    public function __construct(array $store = [], array $data = [])
    {
        $this->store = $store;
        $this->data = $data;
    }
    
    // This method will be called in each `Storer` to store the representation of data
    public function setStore(string $key, $value) {
        $this->store[$key] = $value;
    }
    
    public function getStore(string $key) {
        return $this->store[$key];
    }
    
    // After we restored the data in `Storer`, we can set the data, we'll use `$this->data` instead getter data on original event
    public function setData(string $key, $value) {
        $this->data[$key] = $value;
    }
    
    public function getData(string $key) {
        return $this->data[$key];
    }
}
```

The `StorableFlow` class will be use on Flow Builder:

Before:

```php
class FlowDispatcher 
{
    public function dispatch(Event $event) {
        ...
        // Currently, dispatch on Flow Builder use the original event to execute the Flow 
        $this->callFlowExecutor($event);
        ...
    }
}
```

After:

```php
class FlowDispatcher 
{
    public function dispatch(Event $event) {
        ...
        // The `FlowFactory` will create/restore the `StorableFlow` from original event
        $flow = $this->flowFactory->create($event);
        // use the `StorableFlow` to execute the flow builder actions instead of the original events
        $this->execute($flow);
        ...
    }
}
```

* Flow Builder actions may no longer access the original event.
* Each Aware Interface gets its own `Storer` class to restore the data of Aware, so we have many `Storer` like `OrderStorer`, `MailStorer`, `CustomerStorer` ...
* The main task of a `Storer` is to restore the data from a scalar storage.
* The `Storer` provides a store function, in order to store itself the data, in order restore the object
* The `Storer` provides a restore function to restore the object using the store data.

```php
interface FlowStorer {}
```

Example for `OrderStorer`:

```php
class OrderStorer implements FlowStorer
{
    // This function to check the original event is the instanceof Aware interface, and store the representation.
    public function store(FlowEventAware $event, array $storedData): array 
    {
        if ($event instanceof OrderAware) {
            $storedData['orderId'] = $event->getOrderId();
        }
        
        return $storedData;
    }
    
    // This function is restore the data based on representation in `storedData`
    public function restore(StorableFlow $flow): void
    {
        if ($flow->hasStore('orderId')) {
            // allows to provide a closure for lazy data loading
            // this opens the opportunity to have lazy loading for big data
            // When we load the entity, we need to add the necessary associations for each entity
            $flow->lazy('order', [$this, 'load']);    
        }
        ...
    }
}
```

About the additional data defined in `availableData` in original events, that aren't defined in any Aware Interfaces and we can't restore that data in the `Storer`.
To cover the additional data from original events, we will have another `store` `AdditionalStorer` to store those data.

```php
class AdditionalStorer extends FlowStorer
{
    public function store(FlowEventAware $event, array $storedData)
    {
        ...
        // based on the `getAvailableData` in the original event to get the type of additional data
        $additionalDataTypes = $event::getAvailableData()->toArray();
        
        foreach ($additionalDataTypes as $key => $eventData) {
            // Check if the type of data is Entity or EntityCollection
            // in the $storedData, we only store the presentation like ['id' => id, 'entity' => entity], we'll restore the data in `AdditionalStorer::restore`
            if ($eventData['type'] === 'Entity' || 'EntityCollection') {
                $storedData[$key] = [
                    'id' => $event->getId(),
                    'entity' => Entity                 
                ];
            }
            
            // Check if the type of data is ScalarValueType
            if ($eventData['type'] === ScalarValueType) {
                $storedData[$key] = value
            }
            
            // start to implement /Serializable for ObjectType
            if ($eventData['type'] === ObjectType) {
                $storedData[$key] = value->serialize()
            }
            
            ...
        }
        
        ... 
        
        return $storedData;
    }
      
    // this function  make sure we can restore the additional data from original data are not covered in `Storer`
    // The additional data can be other entity, because the entities we defined in Aware interface like `order`, `customer` ... covered be `Storer`
    public function restore(StorableFlow $flow): void
    {
        if (type === entity) {
            // About the associations for entity data, mostly the additional entity data is the base entity, we don't need to add associations for this
            $flow->setData($key, $this->load());
        } else {
            $flow->setData($key, $flow->getStore($key));
        }
        ...
    }
}
```

About the associations for entity data, mostly the additional entity data is the base entity, we don't need to add associations for this.
About the `ObjectType` data, we enforce all values used in ObjectType implement /Serializable, and serialize the object before store to `$storedData`.

* Flow Builder actions only work with the `StorableFlow` instead of the `FlowEvent`. The `StorableFlow` will restore the data from original events via `Storer`,
  and the Actions can get the data via `getData($key)` from `StorableFlow` instead of `getAvailableData` from original events.

Before, in the flow actions still dependency Aware interfaces:

```php
    public function handle(StorableFlow $event) {
        ...
        $baseEvent = $event->getEvent();
    
        if ($baseEvent instanceof CustomerAware) {
            $customerId= $baseEvent->getCustomerId();
        }
        ...
    }
```

After in the flow actions:

```php
    public function handle(StorableFlow $event) {
        ...
        if ($event->hasStore('customerId') {
            $customerId= $event->getStore('customerId');
        }
        ...
    }
```

* `getAvailableData` must NOT be responsible for the access of the data.
* To create new or restore the `StorableFlow` by on the existing stored data, we need to provider the `FlowFactory`.

```php
class FlowFactory
{    
    ...
    public function create(FlowEventAware $event)
    {
        $storedData = [];
        foreach ($this->storer as $storer) {
            // Storer are responsible to move the corresponding 
            // data from the original event 
            $storer->store($event, $storedData);
        }
        
        return $this->restore($storedData);
    }
  
    public function restore(array $stored = [], array $data = [])
    {
        $flow = new StorableFlow($stored, $data);
      
        foreach ($this->storer as $storer) {
            $storer->restore($flow);
        }
  
        return $flow;
    }
    ...
}
```

But when executing a delayed actions, we won't have a `StorableFlow`, we just have the `$stored` from the previously stored `StorableFlow`,
and based on the `$stored`, we can restore a new `StorableFlow`.

Example in Delay Actions:

```php
// In handler delay actions -> put the actions to `queue`
$stored = json_encode($flow->stored());

$connection->executeStatement('INSERT INTO `swag_delay_action` (store) VALUES (:stored)...', ['stored' => $stored]);
```

```php
// In handler execute delay actions
$stored = 'SELECT store FROM `swag_delay_action` .... ';

$flow = $this->flowFactory->restore(json_decode($stored));
```

## Consequences

Because we use the new class `StorableFlow` instead of the `FlowEvent` class in the Flow Builder, we cannot use the original
events or aware interfaces anymore, but about the symfony event was listeners the `FlowEvent`, those can continue to
use the interfaces as the store is not yet filled during we'll remove it in next major version.

* In symfony event listeners: only use the interfaces as the store is not yet filled
* In the flow builder: Only use the store functionality as the interfaces might not be implemented

---

---
url: /docs/guides/plugins/apps/administration/adding-snippets.md
---

# Adding Translations

Adding snippets to the Administration works the same way for plugins and apps. The only difference is the file structure and that apps are not allowed to override existing snippet keys. The only thing to do, therefore, is to create new files in the following directory: `<app root>/Resources/app/administration/snippet`.

Additionally, you need JSON files for each language you want to support, using the respective language locale (e.g., `de.json`, `en.json`). You can also include patch files for dialects, such as `en-US.json`, to provide country-specific translations.

For more details on selecting a fallback language and structuring your snippet files, see the [Fallback Languages guide](../../../../concepts/framework/translations/fallback-language-selection.md).

Since everything else works the same, please refer to our [Adding translations for plugins](../../plugins/administration/templates-styling/adding-snippets) guide for more information.

---

---
url: /docs/v6.5/guides/plugins/apps/administration/adding-snippets.md
---

# Adding translations for apps

Adding snippets to the administration works the same way for plugins and apps. The only difference is the file structure and that apps are not allowed to override existing snippet keys. The only thing to do, therefore, is to create new files in the following directory: `<app root>/Resources/app/administration/snippet`
Additionally, you need JSON file for each language you want to support, using its specific language locale, e.g. `de-DE.json`, `en-GB.json`.

Since everything else works the same, please refer to our [Adding translations for plugins](../../plugins/administration/adding-snippets) guide for more information.

---

---
url: /docs/v6.6/guides/plugins/apps/administration/adding-snippets.md
---

# Adding translations for apps

Adding snippets to the administration works the same way for plugins and apps. The only difference is the file structure and that apps are not allowed to override existing snippet keys. The only thing to do, therefore, is to create new files in the following directory: `<app root>/Resources/app/administration/snippet`
Additionally, you need JSON file for each language you want to support, using its specific language locale, e.g. `de-DE.json`, `en-GB.json`.

Since everything else works the same, please refer to our [Adding translations for plugins](../../plugins/administration/adding-snippets) guide for more information.

---

---
url: /docs/products/paas/shopware/guides/adding-users.md
---

# Adding users to the Organization

Giving someone access to an organization always involves **two people**:

* **The requester** — the person who wants access.
* **The account-admin** — an organization member with the `account-admin` role who grants that access.

***

## Method 1: Add a user via their user ID (recommended)

This is the easiest way. The requester already knows their own user ID (the `sub` field), so they just hand it to the account-admin.

**Step 1 — Requester: find your user ID.**

```sh
sw-paas account whoami
```

This prints the `sub` (subject ID) value. Copy it.

**Step 2 — Requester: share the user ID.**
Send the `sub` value to the account-admin (chat, email, etc.).

**Step 3 — Account-admin: add the user.**

```sh
sw-paas account user add --sub "<user-id of the new user>"
```

The CLI grants the user access at the chosen level.

**Step 4 — Account-admin: confirm it worked.**

```sh
sw-paas account user list
```

The new user should appear in the list.

***

## Method 2: Request access via the organization-id

Use this when the requester should ask for access and the account-admin approves it. The requester does not know the `organization-id`, so the account-admin shares it first.

**Step 1 — Account-admin: find and share the organization-id.**

```sh
sw-paas organization get
```

Copy the `organization-id` and send it to the requester.

**Step 2 — Requester: request access.**

```sh
sw-paas account user request
```

The CLI asks for the `organization-id` from Step 1.

**Step 3 — Account-admin: approve the request.**

```sh
sw-paas account user requests resolve
```

The CLI walks you through choosing the pending request and approving it. Once approved, the access is active.

The requester can check the status of their request anytime:

```sh
sw-paas account user requests list
```

***

## Removing a user

To revoke access later, the account-admin runs:

```sh
sw-paas account user remove
```

***

For more on accounts and roles, see the [account guide](../fundamentals/account.md).

---

---
url: /docs/guides/installation/legacy-setups/devenv-options.md
---

# Additional Devenv Options

## Enable Blackfire

To enable [Blackfire](https://blackfire.io/) profiling in your Devenv setup, add the following configuration to your `devenv.local.nix` file:

```nix
# <PROJECT_ROOT>/devenv.local.nix
{ pkgs, config, lib, ... }:

{
 services.blackfire.enable = true;
 services.blackfire.server-id = "<SERVER_ID>";
 services.blackfire.server-token = "<SERVER_TOKEN>";
 services.blackfire.client-id = "<CLIENT_ID>";
 services.blackfire.client-token = "<CLIENT_TOKEN>";
}
```

## Enable XDebug

To enable [Xdebug](https://xdebug.org/) for debugging or profiling, add the following configuration to your `devenv.local.nix` file:

```nix
# <PROJECT_ROOT>/devenv.local.nix
{ pkgs, config, lib, ... }:

{
 # XDebug
 languages.php.extensions = [ "xdebug" ];
 languages.php.ini = ''
 xdebug.mode = debug
 xdebug.discover_client_host = 1
 xdebug.client_host = 127.0.0.1
 '';
}
```

After modifying your `devenv.local.nix` file, reload your environment.

## Use MariaDB instead of MySQL

To switch from MySQL to [MariaDB](https://mariadb.org/), update your `devenv.local.nix` file:

```nix
# <PROJECT_ROOT>/devenv.local.nix
{ pkgs, config, lib, ... }:

{
 services.mysql.package = pkgs.mariadb;
}
```

## Use a custom MySQL port

You can change the default MySQL port if it conflicts with another service on your system:

```nix
# <PROJECT_ROOT>/devenv.local.nix
{ pkgs, config, lib, ... }:

{
 services.mysql.settings = {
 mysqld = {
 port = 33881;
 };
 };

}
```

After any change, run `devenv reload` to apply updates.

## Customize Caddy ports or virtual hosts

You can adjust the Caddy web server configuration to use a different port or virtual host.

```nix
# <PROJECT_ROOT>/devenv.local.nix
{ pkgs, config, lib, ... }:

{
 services.caddy.virtualHosts.":8029" = {
 extraConfig = ''
 root * public
 php_fastcgi unix/${config.languages.php.fpm.pools.web.socket}
 file_server
 '';
 };
}
```

```nix
# <PROJECT_ROOT>/devenv.local.nix
{ pkgs, config, lib, ... }:

{
 services.caddy.virtualHosts."http://shopware.swag:8029" = {
 extraConfig = ''
 root * public
 php_fastcgi unix/${config.languages.php.fpm.pools.web.socket}
 file_server
 '';
 };
}
```

## Use a custom Adminer port

If you need to change the default Adminer port (for example, to avoid conflicts with another service), update your `devenv.local.nix` file:

```nix
# <PROJECT_ROOT>/devenv.local.nix
{ pkgs, config, lib, ... }:

{
 services.adminer.listen = "127.0.0.1:9084";
}
```

After modifying `devenv.local.nix`, reload your environment.

## Use Varnish

You can integrate [Varnish](https://varnish-cache.org/) into your local Shopware development setup to test reverse caching behavior. The following example shows how to configure Caddy and Varnish in your `devenv.local.nix` file:

```nix
# <PROJECT_ROOT>/devenv.local.nix
{ pkgs, config, lib, ... }:

{
 # caddy config
 services.caddy = {
 enable = true;

 # all traffic to localhost is redirected to Varnish
 virtualHosts."http://localhost" = {
 extraConfig = ''
 reverse_proxy 127.0.0.1:6081 {
 # header_up solves this issue: https://discord.com/channels/1308047705309708348/1309107911175176217
 header_up Host sw.localhost
 }
 '';
 };

 # the actual shopware application is served from sw.localhost,
 # choose any domain you want.
 # you may need to add the domain to /etc/hosts:
 # 127.0.0.1       sw.localhost
 virtualHosts."http://sw.localhost" = {
 extraConfig = ''
 # set header to avoid CORS errors
 header {
 Access-Control-Allow-Origin *
 Access-Control-Allow-Credentials true
 Access-Control-Allow-Methods *
 Access-Control-Allow-Headers *
 defer
 }
 root * public
 php_fastcgi unix/${config.languages.php.fpm.pools.web.socket}
 encode zstd gzip
 file_server
 log {
 output stderr
 format console
 level ERROR
 }
 '';
 };
 };

 # varnish config
 services.varnish = {
 enable = true;
 package = pkgs.varnish;
 listen = "127.0.0.1:6081";
 # enables xkey module
 extraModules = [ pkgs.varnishPackages.modules ];
 # it's a slightly adjusted version from the [docs](https://developer.shopware.com/docs/guides/hosting/infrastructure/reverse-http-cache.html#configure-varnish)
 vcl = ''
 # ...
 # Specify your app nodes here. Use round-robin balancing to add more than one.
 backend default {
 .host = "sw.localhost";
 .port = "80";
 }
 # ...
 # ACL for purgers IP. (This needs to contain app server IPs)
 acl purgers {
 "sw.localhost";
 "127.0.0.1";
 "localhost";
 "::1";
 }
 # ...
 '';
 };
}
```

After updating your `devenv.local.nix`, reload your development environment to apply the changes:

```bash
devenv reload
```

## Use an older package version

Sometimes, you may want to pin a service to an older version, for example, to ensure compatibility with legacy components or reproduce a previous environment state.

Here are examples showing how to use older versions of MySQL and RabbitMQ in your `devenv.local.nix` configuration:

**Example: Use a specific MySQL version**:

```nix
{
 services.mysql = let
 mysql8033 = pkgs.mysql80.overrideAttrs (oldAttrs: {
 version = "8.0.33";
 # the final URL would look like this: https://github.com/mysql/mysql-server/archive/mysql-8.0.33.tar.gz
 # make sure the URL exists.
 # alternatively, you could use that URL directly via pkgs.fetchurl { url = "xyz"; hash="xyz";};
 # for reference see the [different fetchers](https://ryantm.github.io/nixpkgs/builders/fetchers/#chap-pkgs-fetchers)
 src = pkgs.fetchFromGitHub {
 owner = "mysql";
 repo = "mysql-server";
 rev = "mysql-8.0.33";
 # leave empty on the first run, you will get prompted with the expected hash
 sha256 = "sha256-s4llspXB+rCsGLEtI4WJiPYvtnWiKx51oAgxlg/lATg=";
 };
 });
 in
 {
 enable = true;
 package = mysql8033; # use the overridden package
 # ...
 };
}
```

**Example**: Use a specific RabbitMQ version:

```nix
{
 services.rabbitmq = let
 rabbitmq3137 = pkgs.rabbitmq-server.overrideAttrs (oldAttrs: {
 version = "3.13.7";
 src = pkgs.fetchurl {
 url = "https://github.com/rabbitmq/rabbitmq-server/releases/download/v3.13.7/rabbitmq-server-3.13.7.tar.xz";
 sha256 = "sha256-GDUyYudwhQSLrFXO21W3fwmH2tl2STF9gSuZsb3GZh0=";
 };
 });
 in
 {
 enable = true;
 package = rabbitmq3137; # use the overridden package
 };
}
```

Pinning versions may increase build time; use only when necessary.

## Maintenance

Run `devenv gc` periodically to remove unused packages, services, and caches. This helps free disk space and keeps your environment clean.

Use `devenv down` to stop services first. If processes remain, as a last resort, terminate them manually:

```bash
kill $(ps -ax | grep /nix/store | grep -v "grep" | awk '{print $1}')
```

If you can’t access <http://127.0.0.1:8000> in your browser, try <http://localhost:8000> instead. This issue is common when using WSL2 on Windows.

On macOS or Linux, the app should be available at <http://127.0.0.1:8000>.

---

---
url: /docs/resources/references/adr/2021-11-05-adjust-adr-approval-rules.md
---

# Adjust ADR approval rules for the new org structure

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2021-11-05-adjust-adr-approval-rules.md)
:::

## Context

When we decided to introduce ADRs we also decided that there need to be special approval rules for those ADRs.
The approval rules are now outdated after the reorg, so to continuously ensure that the decisions documented in ADRs work in the long run for us, we want to adapt the approval rules.

## Decision

The old approval rules for reference:

```
*  Two additional developers have to review the ADR
   *  One developer must be a member of the core development team
   *  One developer must be a member of a team, other than the team of the creator
*  One product owner or higher role has to approve an ADR
```

The new approval rule is the following:

* At least one member of each of the Component Teams for the Core, Admin and Storefront area have to review the ADR.

## Consequences

ADRs now need to be approved by the new approval rules.

---

---
url: /docs/v6.5/resources/references/adr/2021-11-05-adjust-adr-approval-rules.md
---

# Adjust ADR approval rules for the new org structure

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2021-11-05-adjust-adr-approval-rules.md)
:::

## Context

When we decided to introduce ADRs we also decided that there need to be special approval rules for those ADRs.
The approval rules are now outdated after the reorg, so to continuously ensure that the decisions documented in ADRs work in the long run for us, we want to adapt the approval rules.

## Decision

The old approval rules for reference:

```
*  Two additional developers have to review the ADR
   *  One developer must be a member of the core development team
   *  One developer must be a member of a team, other than the team of the creator
*  One product owner or higher role has to approve an ADR
```

The new approval rule is the following:

* At least one member of each of the Component Teams for the Core, Admin and Storefront area have to review the ADR.

## Consequences

ADRs now need to be approved by the new approval rules.

---

---
url: /docs/v6.6/resources/references/adr/2021-11-05-adjust-adr-approval-rules.md
---

# Adjust ADR approval rules for the new org structure

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2021-11-05-adjust-adr-approval-rules.md)
:::

## Context

When we decided to introduce ADRs we also decided that there need to be special approval rules for those ADRs.
The approval rules are now outdated after the reorg, so to continuously ensure that the decisions documented in ADRs work in the long run for us, we want to adapt the approval rules.

## Decision

The old approval rules for reference:

```
*  Two additional developers have to review the ADR
   *  One developer must be a member of the core development team
   *  One developer must be a member of a team, other than the team of the creator
*  One product owner or higher role has to approve an ADR
```

The new approval rule is the following:

* At least one member of each of the Component Teams for the Core, Admin and Storefront area have to review the ADR.

## Consequences

ADRs now need to be approved by the new approval rules.

---

---
url: /docs/guides/plugins/plugins/services/adjusting-service.md
---

# Adjusting a Service

Service decoration is one of the main ways to extend Shopware behavior from a plugin, alongside reacting to events. Prefer events when you need to react to something Shopware does. Prefer service decoration when you need to change how an existing service behaves.

Shopware services that are designed for decoration often expose an abstract class as their contract instead of a PHP interface. The abstract class provides the `getDecorated()` chain and allows new non-abstract methods to be added without immediately breaking existing decorators.

This guide explains how to adjust a service using decoration. For more details, see the [Symfony documentation](https://symfony.com/doc/current/service_container/service_decoration.html).

## Prerequisites

This guide builds on the [Plugin Base Guide](../plugin-base-guide.md).

::: info
Refer to this video on **[Decorating services](https://www.youtube.com/watch?v=Rgf4c9rd1kw)** explaining service decorations with an easy example. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

## Decorating the service

Register both the original service and the decorator in `services.php`. Use the `decorate` method to point to the service being decorated. The `.inner` reference keeps the original service available inside the decorator.

Here's our example `services.php`:

```php
// <plugin root>/src/Resources/config/services.php
<?php declare(strict_types=1);

use Swag\BasicExample\Service\ExampleService;
use Swag\BasicExample\Service\ExampleServiceDecorator;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(ExampleService::class);

    $services->set(ExampleServiceDecorator::class)
        ->decorate(ExampleService::class)
        ->args([service('.inner')]);
};
```

Define an abstract class for the service contract. Unlike interfaces, abstract classes allow adding new methods without breaking existing decorators — see [Adding new functions](#adding-new-functions-to-an-existing-service) below. The abstract class must include a `getDecorated()` method returning its own type.

::: info
To avoid misunderstandings: The abstract service class and the implementation of it is not part of the decoration process itself and most of the times comes either from the Shopware core or from a plugin you want to extend. They are added here to have an example to decorate.
:::

Example abstract class:

```php
// <plugin root>/src/Service/AbstractExampleService.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

abstract class AbstractExampleService
{
    abstract public function getDecorated(): AbstractExampleService; 

    abstract public function doSomething(): string;
}
```

`ExampleService` extends `AbstractExampleService`. Its `getDecorated()` throws `DecorationPatternException` because it has no decorator yet:

Example service:

```php
// <plugin root>/src/Service/ExampleService.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Framework\Plugin\Exception\DecorationPatternException;

class ExampleService extends AbstractExampleService
{
    public function getDecorated(): AbstractExampleService
    {
        throw new DecorationPatternException(self::class);
    }

    public function doSomething(): string
    {
        return 'Did something.';
    }
}
```

`ExampleServiceDecorator` extends `AbstractExampleService`, accepts the original service in its constructor, and returns it from `getDecorated()`:

Example decorator:

```php
// <plugin root>/src/Service/ExampleServiceDecorator.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

class ExampleServiceDecorator extends AbstractExampleService
{
    private AbstractExampleService $decoratedService;

    public function __construct(AbstractExampleService $exampleService)
    {
        $this->decoratedService = $exampleService;
    }

    public function getDecorated(): AbstractExampleService
    {
        return $this->decoratedService;
    }

    public function doSomething(): string
    {
        $originalResult = $this->decoratedService->doSomething();

        return $originalResult . ' Did something additionally.';
    }
}
```

## Decoration in a shared codebase

Decoration is powerful because it is unrestricted: your decorator replaces the service for every caller, so you can run code before and after the core logic, change its arguments, modify its return value, or skip the core implementation entirely. The same property makes it the most fragile extension mechanism in Shopware. Keep the following in mind, especially in projects that combine several store extensions with project code.

### Decorators nest, and every link must call the next one

Decoration is not limited to one decorator per service. If plugin A decorates a core service and plugin B decorates the same service, plugin B wraps plugin A, which wraps the core. Each decorator only ever sees the next inner service.

A decorator that does not call the inner service silently discards everything the rest of the chain contributes — including other plugins' behavior and the core logic. Unless you deliberately replace the implementation, always delegate to the inner service and keep working with its result:

```php
public function doSomething(): string
{
    // Delegate first, then add your own behavior
    return $this->decoratedService->doSomething() . ' Did something additionally.';
}
```

There is no runtime warning when a chain is broken. Symptoms show up as another extension "not working", so before debugging elsewhere, check which decorators are registered for the service. In PHPStorm, open the abstract class and use *Navigate → Implementations* (**Ctrl+Alt+B** / **Option+Cmd+B**) to list every class in the chain, or run `bin/console debug:container --show-arguments <service-id>`.

### Signature changes break every decorator

All implementations of an abstract method must share its signature. Adding even an optional parameter to a decorated method in the core or in your own abstract class therefore forces every decorator to be adjusted, and a plugin cannot satisfy the old and the new signature at the same time. In practice this means a new plugin major version per Shopware major version.

This is why Shopware avoids interfaces for decoratable services, and why new methods should be added as [regular public methods first](#adding-new-functions-to-an-existing-service) instead of as abstract methods.

::: warning
Type hint the abstract class, never the concrete implementation, in constructors. Type hinting the concrete class means your service is no longer part of the decoration chain and bypasses other extensions. The [Shopware 6 Toolbox plugin](../../../development/tooling/shopware-toolbox.md#inspections) reports this as an error.
:::

### Prefer designed extension points

Decoration works on any service, whether or not the service was designed to be extended. Where the core offers an [extension point](../framework/extension/index.md), prefer it: extension points are subscribed to as events (`.pre`, `.post`, `.error`), so multiple extensions can participate without forming a chain, and their input objects can gain new data without breaking existing subscribers. See the [Extension Points vs Events guide](../framework/extension/extension-vs-events.md) for the differences and the [Listening to Events guide](../framework/event/listening-to-events.md) for plain events.

Use decoration when there is no extension point and you need to change how an existing service behaves.

### Data added to entities is public API

Attaching data to an entity via `addExtension()` inside a decorator is convenient, but the extension is serialized into Store API and Admin API responses. Anything you add there becomes part of the payload that other extensions and storefronts see, so use a vendor-specific key and document it as part of your plugin's public surface.

## Adding new functions to an existing service

If you plan to add new functions to your service, it is recommended to add them as normal public functions due to backwards compatibility, if you decorate the service at several places. In this example we add a new function called `doSomethingNew()` which first calls the `getDecorated()` and then our new function `doSomethingNew()` because if our decorator does not implement it yet, it will call it from the parent. The advantage of adding it as normal public function is that you can implement it step by step into your other services without any issues. After you have implemented the function in every service decorator, you can make it abstract for the next release. If you add it directly as an abstract function, you will get errors because the function is required for every service decorator.

Here's our example abstract class:

```php
// <plugin root>/src/Service/AbstractExampleService.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

abstract class AbstractExampleService
{
    abstract public function getDecorated(): AbstractExampleService; 

    abstract public function doSomething(): string;

    public function doSomethingNew(): string
    {
        return $this->getDecorated()->doSomethingNew();
    }
}
```

Implement the new method in the concrete service as well:

```php
// <plugin root>/src/Service/ExampleService.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Framework\Plugin\Exception\DecorationPatternException;

class ExampleService extends AbstractExampleService
{
    public function getDecorated(): AbstractExampleService
    {
        throw new DecorationPatternException(self::class);
    }

    public function doSomething(): string
    {
        return 'Did something.';
    }

    public function doSomethingNew(): string
    {
        return 'Did something new.';
    }
}
```

---

---
url: /docs/v6.5/guides/plugins/plugins/plugin-fundamentals/adjusting-service.md
---

# Adjusting a Service

## Overview

In this guide you'll learn how to adjust a service. You can read more about service decoration in the [Symfony documentation](https://symfony.com/doc/current/service_container/service_decoration.html).

## Prerequisites

In order to add your own custom service for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide).

::: info
Refer to this video on **[Decorating services](https://www.youtube.com/watch?v=Rgf4c9rd1kw)** explaining service decorations with an easy example. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

## Decorating the service

First of all we have to create a new service for this example which gets decorated in the next step. Then we have to add a new service to our `services.xml` with the attribute `decorates` pointing to our service we want to decorate. Next we have to add our service decorator as argument, but we append an `.inner` to the end of the service to keep the old one as reference.

Here's our example `services.xml`:

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Service\ExampleService" />

        <service id="Swag\BasicExample\Service\ExampleServiceDecorator" decorates="Swag\BasicExample\Service\ExampleService">
            <argument type="service" id="Swag\BasicExample\Service\ExampleServiceDecorator.inner" />
        </service>
    </services>
</container>
```

Now we have to define an abstract class because it's more beautiful and not so strict like interfaces. With an abstract class we can add new functions easier, you can read more about this at the end of this article. The abstract class has to include an abstract function called `getDecorated()` which has the return type of our instance.

::: info
To avoid misunderstandings: The abstract service class and the implementation of it is not part of the decoration process itself and most of the times comes either from the Shopware core or from a plugin you want to extend. They are added here to have an example to decorate.
:::

Therefore, this is how your abstract class could then look like:

```php
// <plugin root>/src/Service/AbstractExampleService.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

abstract class AbstractExampleService
{
    abstract public function getDecorated(): AbstractExampleService; 

    abstract public function doSomething(): string;
}
```

Now we have our abstract class, but no service which uses it. So we create our `ExampleService` which extends from our `AbstractExampleService`. In our service the `getDecorated()` function has to throw an `DecorationPatternException` because it has no decoration yet.

Therefore, your service could then look like this:

```php
// <plugin root>/src/Service/ExampleService.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Framework\Plugin\Exception\DecorationPatternException;

class ExampleService extends AbstractExampleService
{
    public function getDecorated(): AbstractExampleService
    {
        throw new DecorationPatternException(self::class);
    }

    public function doSomething(): string
    {
        return 'Did something.';
    }
}
```

The last step is creating our decorated service called `ExampleServiceDecorator` in this example. Our decorated service has to extend from the `AbstractExampleService` and the constructor has to accept an instance of `AbstractExampleService`. Furthermore, the `getDecorated()` function has to return the decorated service passed into the constructor.

Your service could then look like below:

```php
// <plugin root>/src/Service/ExampleServiceDecorator.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

class ExampleServiceDecorator extends AbstractExampleService
{
    private AbstractExampleService $decoratedService;

    public function __construct(AbstractExampleService $exampleService)
    {
        $this->decoratedService = $exampleService;
    }

    public function getDecorated(): AbstractExampleService
    {
        return $this->decoratedService;
    }

    public function doSomething(): string
    {
        $originalResult = $this->decoratedService->doSomething();

        return $originalResult . ' Did something additionally.';
    }
}
```

## Adding new functions to an existing service

If you plan to add new functions to your service, it is recommended to add them as normal public functions due to backwards compatibility, if you decorate the service at several places. In this example we add a new function called `doSomethingNew()` which first calls the `getDecorated()` and then our new function `doSomethingNew()` because if our decorator does not implement it yet, it will call it from the parent. The advantage of adding it as normal public function is that you can implement it step by step into your other services without any issues. After you have implemented the function in every service decorator, you can make it abstract for the next release. If you add it directly as an abstract function, you will get errors because the function is required for every service decorator.

Here's our example abstract class:

```php
// <plugin root>/src/Service/AbstractExampleService.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

abstract class AbstractExampleService
{
    abstract public function getDecorated(): AbstractExampleService; 

    abstract public function doSomething(): string;

    public function doSomethingNew(): string
    {
        return $this->getDecorated()->doSomethingNew();
    }
}
```

After we have implemented our new function in the abstract class, we implement it in our service too.

```php
// <plugin root>/src/Service/ExampleService.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Framework\Plugin\Exception\DecorationPatternException;

class ExampleService extends AbstractExampleService
{
    public function getDecorated(): AbstractExampleService
    {
        throw new DecorationPatternException(self::class);
    }

    public function doSomething(): string
    {
        return 'Did something.';
    }

    public function doSomethingNew(): string
    {
        return 'Did something new.';
    }
}
```

---

---
url: /docs/v6.6/guides/plugins/plugins/plugin-fundamentals/adjusting-service.md
---

# Adjusting a Service

## Overview

In this guide you'll learn how to adjust a service. You can read more about service decoration in the [Symfony documentation](https://symfony.com/doc/current/service_container/service_decoration.html).

## Prerequisites

In order to add your own custom service for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide).

::: info
Refer to this video on **[Decorating services](https://www.youtube.com/watch?v=Rgf4c9rd1kw)** explaining service decorations with an easy example. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

## Decorating the service

First of all we have to create a new service for this example which gets decorated in the next step. Then we have to add a new service to our `services.xml` with the attribute `decorates` pointing to our service we want to decorate. Next we have to add our service decorator as argument, but we append an `.inner` to the end of the service to keep the old one as reference.

Here's our example `services.xml`:

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Service\ExampleService" />

        <service id="Swag\BasicExample\Service\ExampleServiceDecorator" decorates="Swag\BasicExample\Service\ExampleService">
            <argument type="service" id="Swag\BasicExample\Service\ExampleServiceDecorator.inner" />
        </service>
    </services>
</container>
```

Now we have to define an abstract class because it's more beautiful and not so strict like interfaces. With an abstract class we can add new functions easier, you can read more about this at the end of this article. The abstract class has to include an abstract function called `getDecorated()` which has the return type of our instance.

::: info
To avoid misunderstandings: The abstract service class and the implementation of it is not part of the decoration process itself and most of the times comes either from the Shopware core or from a plugin you want to extend. They are added here to have an example to decorate.
:::

Therefore, this is how your abstract class could then look like:

```php
// <plugin root>/src/Service/AbstractExampleService.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

abstract class AbstractExampleService
{
    abstract public function getDecorated(): AbstractExampleService; 

    abstract public function doSomething(): string;
}
```

Now we have our abstract class, but no service which uses it. So we create our `ExampleService` which extends from our `AbstractExampleService`. In our service the `getDecorated()` function has to throw an `DecorationPatternException` because it has no decoration yet.

Therefore, your service could then look like this:

```php
// <plugin root>/src/Service/ExampleService.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Framework\Plugin\Exception\DecorationPatternException;

class ExampleService extends AbstractExampleService
{
    public function getDecorated(): AbstractExampleService
    {
        throw new DecorationPatternException(self::class);
    }

    public function doSomething(): string
    {
        return 'Did something.';
    }
}
```

The last step is creating our decorated service called `ExampleServiceDecorator` in this example. Our decorated service has to extend from the `AbstractExampleService` and the constructor has to accept an instance of `AbstractExampleService`. Furthermore, the `getDecorated()` function has to return the decorated service passed into the constructor.

Your service could then look like below:

```php
// <plugin root>/src/Service/ExampleServiceDecorator.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

class ExampleServiceDecorator extends AbstractExampleService
{
    private AbstractExampleService $decoratedService;

    public function __construct(AbstractExampleService $exampleService)
    {
        $this->decoratedService = $exampleService;
    }

    public function getDecorated(): AbstractExampleService
    {
        return $this->decoratedService;
    }

    public function doSomething(): string
    {
        $originalResult = $this->decoratedService->doSomething();

        return $originalResult . ' Did something additionally.';
    }
}
```

## Adding new functions to an existing service

If you plan to add new functions to your service, it is recommended to add them as normal public functions due to backwards compatibility, if you decorate the service at several places. In this example we add a new function called `doSomethingNew()` which first calls the `getDecorated()` and then our new function `doSomethingNew()` because if our decorator does not implement it yet, it will call it from the parent. The advantage of adding it as normal public function is that you can implement it step by step into your other services without any issues. After you have implemented the function in every service decorator, you can make it abstract for the next release. If you add it directly as an abstract function, you will get errors because the function is required for every service decorator.

Here's our example abstract class:

```php
// <plugin root>/src/Service/AbstractExampleService.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

abstract class AbstractExampleService
{
    abstract public function getDecorated(): AbstractExampleService; 

    abstract public function doSomething(): string;

    public function doSomethingNew(): string
    {
        return $this->getDecorated()->doSomethingNew();
    }
}
```

After we have implemented our new function in the abstract class, we implement it in our service too.

```php
// <plugin root>/src/Service/ExampleService.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Framework\Plugin\Exception\DecorationPatternException;

class ExampleService extends AbstractExampleService
{
    public function getDecorated(): AbstractExampleService
    {
        throw new DecorationPatternException(self::class);
    }

    public function doSomething(): string
    {
        return 'Did something.';
    }

    public function doSomethingNew(): string
    {
        return 'Did something new.';
    }
}
```

---

---
url: /docs/concepts/api/admin-api.md
---

# Admin API

The Admin API represents the administrative and integration surface of Shopware. It enables structured access to core business entities such as products, orders, customers, media, and configurations. It is intended for backend integrations, automation, data synchronization, and system-to-system communication.

These integrations typically involve structured data exchange, synchronization, imports, exports, and notifications. They prioritize consistency, error handling, validation, and transactional integrity. Performance is also important in terms of high data loads rather than fast response times.

The Admin API provides CRUD operations for every entity within Shopware and is used to build integrations with external systems.

For details on endpoints, authentication methods, schemas, and request formats, always refer to the Admin API documentation.

---

---
url: /docs/v6.5/concepts/api/admin-api.md
---

# Admin API

The Admin API provides CRUD operations for every entity within Shopware and is used to build integrations with external systems.

For more information, refer to the [Guides section](../../guides/integrations-api/index.md).

---

---
url: /docs/v6.6/concepts/api/admin-api.md
---

# Admin API

The Admin API provides CRUD operations for every entity within Shopware and is used to build integrations with external systems.

For more information, refer to the [Guides section](../../guides/integrations-api/index.md).

---

---
url: /docs/resources/references/adr/2021-12-07-admin-extension-api-standards.md
---

# Admin extension API standards

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2021-12-07-admin-extension-api-standards.md)
:::

## Context

We need to provide ways for extension developers to add custom components and views to different places in the administration. Multiple solutions where discussed and tested, this ADR contains a summary of the final solution.

## Decision

### Word definitions

For a better understanding of the following text it is good to have a definition for specific words:

#### Location

Extensions can render custom views with the Admin-Extension-API via iFrames. To support multiple views in different places every "location" of the iFrame gets a unique ID. These can be defined by the app/plugin developer itself.

*Example:*

An app wants to render a custom iFrame in a card on the dashboard. The "location" of the iFrame has then a specific "locationID" like `sw-dashboard-example-app-dashboard-card`. The app can also render another iFrames which also get "locationIDs". In our example it is a iFrame in a custom modal: `example-app-example-modal-content`.

The app want to render different views depending on the "location" of the iFrame. So the app developer can render the correct view depending on the "locationID":

```js
if (sw.location.is('sw-dashboard-example-app-dashboard-card')) {
    renderDashboardCard();
}

if (sw.location.is('example-app-example-modal-content')) {
    renderModalContent();
}
```

#### PositionID (PositionIdentifier)

Developers can extend existing areas or create new areas in the administration with the Admin-Extension-API. To identify the positions which the developer want to extend we need a unique ID for every position. We call these IDs "positionID".

*Example:*

An app wants to add a new tab item to a tab-bar. In the administration are many tab-bars available. So the developer needs to choose the correct "positionID" to determine which tab-bar should be extended. In this example the developer adds a new tab item to the tab-bar in the product detail page.

```js
sw.ui.tabs('sw-product-detail').addTabItem({ ... })
```

### Solution:

We use the concept of component sections for providing injection points for extension components.

#### Component Sections

In most cases developers will directly use the extension capabilities of the UI components (e.g. adding tab items, adding button to grid, ...). This will cover most needs of many extensions.

To give them more flexibility we introduce a feature named "Component Sections". These are sections where any extension developer can inject components. These components are prebuilt and they can also contain custom render views with iFrames. The developer needs to use the feature and choose the matching positionID for the component position.

```js
// Adding a card before the manufacturer card with custom fields entries.
sw.ui.componentSection('sw-manufacturer-card-custom-fields__before').add({
    // The Extension-API provides different components out of the box
    component: 'card', 
    // Props are depending on the type of component
    props: {
        title: 'This is the title',
        subtitle: 'I am the subtitle',
        // Some components can render a custom view. In this case the extension can render custom content in the card.
        locationId: 'example-app-card-before-manufactuer-custom-fields-card'
    }
})
```

#### Vue Devtools Plugin for finding the PositionIDs

It is impossible to create a list of all potential position IDs. And they would be hard to manage. To solve this problem we are writing a custom plugin for the Vue Devtools. This plugin will be available for Vue Devtools 6+. It makes identifying the position IDs very easy.

Just open the plugin in the Devtools (It is available directly when you open the Administration). Then you can see all positions at the current administration view which are available for extending. If you click at one position ID you get more information about it. Like the property in the Meteor-Extension-SDK so that you directly know what functionality this position has.

In summary: the Devtool plugin provides a visual way to see which parts can be extended and what are the positionIDs for the extension position.

## Consequences

We need to implement the componentSectionRenderer to positions where we want to provide an extension position for apps and plugins. These can be positions like before or after cards, at the top or bottom of a page, at the top or bottom of a tab view and many more.

---

---
url: >-
  /docs/v6.5/resources/references/adr/2021-12-07-admin-extension-api-standards.md
---

# Admin extension API standards

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2021-12-07-admin-extension-api-standards.md)
:::

## Context

We need to provide ways for extension developers to add custom components and views to different places in the administration. Multiple solutions where discussed and tested, this ADR contains a summary of the final solution.

## Decision

### Word definitions

For a better understanding of the following text it is good to have a definition for specific words:

#### Location

Extensions can render custom views with the Admin-Extension-API via iFrames. To support multiple views in different places every "location" of the iFrame gets a unique ID. These can be defined by the app/plugin developer itself.

*Example:*

An app wants to render a custom iFrame in a card on the dashboard. The "location" of the iFrame has then a specific "locationID" like `sw-dashboard-example-app-dashboard-card`. The app can also render another iFrames which also get "locationIDs". In our example it is a iFrame in a custom modal: `example-app-example-modal-content`.

The app want to render different views depending on the "location" of the iFrame. So the app developer can render the correct view depending on the "locationID":

```js
if (sw.location.is('sw-dashboard-example-app-dashboard-card')) {
    renderDashboardCard();
}

if (sw.location.is('example-app-example-modal-content')) {
    renderModalContent();
}
```

#### PositionID (PositionIdentifier)

Developers can extend existing areas or create new areas in the administration with the Admin-Extension-API. To identify the positions which the developer want to extend we need a unique ID for every position. We call these IDs "positionID".

*Example:*

An app wants to add a new tab item to a tab-bar. In the administration are many tab-bars available. So the developer needs to choose the correct "positionID" to determine which tab-bar should be extended. In this example the developer adds a new tab item to the tab-bar in the product detail page.

```js
sw.ui.tabs('sw-product-detail').addTabItem({ ... })
```

### Solution:

We use the concept of component sections for providing injection points for extension components.

#### Component Sections

In most cases developers will directly use the extension capabilities of the UI components (e.g. adding tab items, adding button to grid, ...). This will cover most needs of many extensions.

To give them more flexibility we introduce a feature named "Component Sections". These are sections where any extension developer can inject components. These components are prebuilt and they can also contain custom render views with iFrames. The developer needs to use the feature and choose the matching positionID for the component position.

```js
// Adding a card before the manufacturer card with custom fields entries.
sw.ui.componentSection('sw-manufacturer-card-custom-fields__before').add({
    // The Extension-API provides different components out of the box
    component: 'card', 
    // Props are depending on the type of component
    props: {
        title: 'This is the title',
        subtitle: 'I am the subtitle',
        // Some components can render a custom view. In this case the extension can render custom content in the card.
        locationId: 'example-app-card-before-manufactuer-custom-fields-card'
    }
})
```

#### Vue Devtools Plugin for finding the PositionIDs

It is impossible to create a list of all potential position IDs. And they would be hard to manage. To solve this problem we are writing a custom plugin for the Vue Devtools. This plugin will be available for Vue Devtools 6+. It makes identifying the position IDs very easy.

Just open the plugin in the Devtools (It is available directly when you open the Administration). Then you can see all positions at the current administration view which are available for extending. If you click at one position ID you get more information about it. Like the property in the Meteor-Extension-SDK so that you directly know what functionality this position has.

In summary: the Devtool plugin provides a visual way to see which parts can be extended and what are the positionIDs for the extension position.

## Consequences

We need to implement the componentSectionRenderer to positions where we want to provide an extension position for apps and plugins. These can be positions like before or after cards, at the top or bottom of a page, at the top or bottom of a tab view and many more.

---

---
url: >-
  /docs/v6.6/resources/references/adr/2021-12-07-admin-extension-api-standards.md
---

# Admin extension API standards

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2021-12-07-admin-extension-api-standards.md)
:::

## Context

We need to provide ways for extension developers to add custom components and views to different places in the administration. Multiple solutions where discussed and tested, this ADR contains a summary of the final solution.

## Decision

### Word definitions

For a better understanding of the following text it is good to have a definition for specific words:

#### Location

Extensions can render custom views with the Admin-Extension-API via iFrames. To support multiple views in different places every "location" of the iFrame gets a unique ID. These can be defined by the app/plugin developer itself.

*Example:*

An app wants to render a custom iFrame in a card on the dashboard. The "location" of the iFrame has then a specific "locationID" like `sw-dashboard-example-app-dashboard-card`. The app can also render another iFrames which also get "locationIDs". In our example it is a iFrame in a custom modal: `example-app-example-modal-content`.

The app want to render different views depending on the "location" of the iFrame. So the app developer can render the correct view depending on the "locationID":

```js
if (sw.location.is('sw-dashboard-example-app-dashboard-card')) {
    renderDashboardCard();
}

if (sw.location.is('example-app-example-modal-content')) {
    renderModalContent();
}
```

#### PositionID (PositionIdentifier)

Developers can extend existing areas or create new areas in the administration with the Admin-Extension-API. To identify the positions which the developer want to extend we need a unique ID for every position. We call these IDs "positionID".

*Example:*

An app wants to add a new tab item to a tab-bar. In the administration are many tab-bars available. So the developer needs to choose the correct "positionID" to determine which tab-bar should be extended. In this example the developer adds a new tab item to the tab-bar in the product detail page.

```js
sw.ui.tabs('sw-product-detail').addTabItem({ ... })
```

### Solution:

We use the concept of component sections for providing injection points for extension components.

#### Component Sections

In most cases developers will directly use the extension capabilities of the UI components (e.g. adding tab items, adding button to grid, ...). This will cover most needs of many extensions.

To give them more flexibility we introduce a feature named "Component Sections". These are sections where any extension developer can inject components. These components are prebuilt and they can also contain custom render views with iFrames. The developer needs to use the feature and choose the matching positionID for the component position.

```js
// Adding a card before the manufacturer card with custom fields entries.
sw.ui.componentSection('sw-manufacturer-card-custom-fields__before').add({
    // The Extension-API provides different components out of the box
    component: 'card', 
    // Props are depending on the type of component
    props: {
        title: 'This is the title',
        subtitle: 'I am the subtitle',
        // Some components can render a custom view. In this case the extension can render custom content in the card.
        locationId: 'example-app-card-before-manufactuer-custom-fields-card'
    }
})
```

#### Vue Devtools Plugin for finding the PositionIDs

It is impossible to create a list of all potential position IDs. And they would be hard to manage. To solve this problem we are writing a custom plugin for the Vue Devtools. This plugin will be available for Vue Devtools 6+. It makes identifying the position IDs very easy.

Just open the plugin in the Devtools (It is available directly when you open the Administration). Then you can see all positions at the current administration view which are available for extending. If you click at one position ID you get more information about it. Like the property in the Meteor-Extension-SDK so that you directly know what functionality this position has.

In summary: the Devtool plugin provides a visual way to see which parts can be extended and what are the positionIDs for the extension position.

## Consequences

We need to implement the componentSectionRenderer to positions where we want to provide an extension position for apps and plugins. These can be positions like before or after cards, at the top or bottom of a page, at the top or bottom of a tab view and many more.

---

---
url: /docs/v6.5/products/digital-sales-rooms/installation/admin-installation.md
---

# Admin Installation

::: warning
To access the *Digital Sales Rooms* source code, please create a support ticket in your Shopware Account and share your GitLab (not GitHub) username. You will then be granted access to the private repository.
:::

## Get the plugin

1. Clone or download the [SwagDigitalSalesRooms repository 6.6.x](https://gitlab.com/shopware/shopware/shopware-6/services/swagdigitalsalesrooms/-/tree/6.6.x).
2. Extract the plugin, including the outer folder `SwagDigitalSalesRooms`, to `platform/custom/plugins` directory of the Shopware repository.
3. Ensure the plugin has a PHP package structure containing `composer.json` file, `src/` folder, and so on.
4. Prepare a zip file containing the plugin as in the following structure:

```bash
# SwagDigitalSalesRooms.zip

**SwagDigitalSalesRooms**/
├── bin
├── composer.json
├── composer.lock
├── makefile
├── phpstan.neon
├── phpunit.xml
├── README.md
├── src
└── tests
```

## Install & activate the plugin in Admin Extension

To install and use the *Digital Sales Rooms* feature, place and extract the above zip file in this location `<shopware-root-dir>/custom/plugins` directory. Once it is done, you can either refer the guide to [install plugin](../../../guides/plugins/plugins/plugin-base-guide.html#install-your-plugin) or you can run the below Symfony commands:

```bash
# refresh the list of available plugins
bin/console plugin:refresh
# find the plugin **name** (first column on the list). In this case, it is "**SwagDigitalSalesRooms"**
bin/console plugin:install **SwagDigitalSalesRooms** --activate
# clear the cache afterward
bin/console cache:clear

# Now it is ready to use
```

---

---
url: /docs/products/digital-sales-rooms/installation/admin-side-installation.md
---

# Admin Side Installation

::: info
Digital Sales Rooms plugin is a licensed plugin. If you already know how to install a licensed plugin, you can skip this part.
:::

::: warning
As part of the Shopware Beyond plan, the **Digital Sales Rooms** is available to you as an extension.
Same with other plugins, you have multiple ways to install the plugin via composer, direct download or through your Shopware Account.
:::

In this part, we will learn how to get and install the **Digital Sales Rooms** plugin into local Shopware instance.

## Get the plugin

If you are a merchant with **Shopware Beyond**, you can access [account.shopware.com](https://auth.shopware.com/login?return_to=https:%2F%2Faccount.shopware.com%2Fportal) and create a [wildcard environment](https://docs.shopware.com/en/account-en/extension-partner/wildcard-environments?category=account-en/extension-partner) with attached plugins.

![ ](../../../assets/products-digitalSalesRooms-wildcard.png)

By this way, you can get the plugin quickly into Shopware instance in multiple ways (via composer, direct download or through your Shopware Account).

### Via composer

To install a plugin via composer, follow these steps:

* From wildcard environment detail page, click on the plugin and then click on the "Install via composer" button.
* A modal will appear and contain all command lines to install.

### Via download

To install a plugin via download, follow these steps:

* From wildcard environment detail page, click on the plugin and then click on the “Download” button.
* Save the zip file to your computer.
* In your Shopware 6 instance source code, go to the `custom/plugins` directory.
* Extract the zip file into the `custom/plugins` directory with name `SwagDigitalSalesRooms`.

## Install & activate the plugin

Once you fetch the plugin, you can run the Symfony commands below for activating the plugin:

```bash
# refresh the list of available plugins
bin/console plugin:refresh
# find the plugin **name** (first column on the list). In this case, it is "**SwagDigitalSalesRooms"**
bin/console plugin:install **SwagDigitalSalesRooms** --activate
# clear the cache afterward
bin/console cache:clear

# Now it is ready to use
```

---

---
url: >-
  /docs/v6.6/products/digital-sales-rooms/installation/admin-side-installation.md
---

# Admin Side Installation

::: info
Digital Sales Rooms plugin is a licensed plugin. If you already know how to install a licensed plugin, you can skip this part.
:::

::: warning
As part of the Shopware Beyond plan, the **Digital Sales Rooms** is available to you as an extension.
Same with other plugins, you have multiple ways to install the plugin via composer, direct download or through your Shopware Account.
:::

In this part, we will learn how to get and install the **Digital Sales Rooms** plugin into local Shopware instance.

## Get the plugin

If you are a merchant with Shopware Beyond, you can access account.shopware.com and create a wildcard environment with attached plugins. Refer to [guideline](https://docs.shopware.com/en/account-en/extension-partner/wildcard-environments) for more info.

![ ](../../../assets/products-digitalSalesRooms-wildcard.png)

By this way, you can get the plugin quickly into Shopware instance via multiple ways (via composer, direct download or through your Shopware Account).

### Via download

To install a plugin via download, follow these steps:

* From wildcard environment detail page, click on the plugin and then click on the “Download” button.
* Save the zip file to your computer.
* In your Shopware 6 instance source code, go to the `custom/plugins` directory.
* Extract the zip file into the `custom/plugins` directory with name `SwagDigitalSalesRooms`.

### Via composer

To install a plugin via composer, follow these steps:

* From wildcard environment detail page, click on the plugin and then click on the "Install via composer" button.
* A modal will appear and contain all command lines to install.

## Install & activate the plugin

Once you fetch the plugin, you can run the Symfony commands below for activating the plugin:

```bash
# refresh the list of available plugins
bin/console plugin:refresh
# find the plugin **name** (first column on the list). In this case, it is "**SwagDigitalSalesRooms"**
bin/console plugin:install **SwagDigitalSalesRooms** --activate
# clear the cache afterward
bin/console cache:clear

# Now it is ready to use
```

---

---
url: /docs/resources/references/adr/2023-03-27-admin-text-editor-evaluation.md
---

# Admin text editor evaluation

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2023-03-27-admin-text-editor-evaluation.md)
:::

## Context

The current sw-text-editor in the administration has numerous low-level bugs in basic WYSIWYG features. It is built in a
way that is difficult to maintain and understand. Therefore, we require a new text editor that is easy to maintain, has
a good feature set, is flexible to extend and more stable.

## Decision

Building a new text editor from scratch is not a viable option. Therefore, we have evaluated various existing text
editors and narrowed down our options to the following:

```
- CKEditor 5
- TinyMCE
- QuillJS
- Prosemirror
- TipTap V2
- Lexical
```

We have decided to skip CKEditor 5 and TinyMCE because they require a license for our use case and are not 100% open
source. Prosemirror was also ruled out because it provides only a low-level API and requires much more implementation
time than the other editors. Additionally, Lexical is not a valid option for us since it is specialized for React
environments and has no official support for VueJS.

The remaining two editors are TipTap V2 and QuillJS. Both have similar feature sets and APIs, but we have found some
major differences between them. The first difference is that TipTap is a headless editor, which means that it only
provides the editor logic and requires a UI implementation. QuillJS, on the other hand, is a fully featured editor that
provides a UI out of the box. In our case, it is better to use a headless editor like TipTap because we can implement
the UI to fit our needs, especially for several edge cases that are hard to implement in QuillJS.

The second major difference is in extensibility. TipTap's API is more flexible, allowing us to implement our own
features using the existing TipTap and ProseMirror plugins or build our own plugins. In most cases, the powerful main
TipTap API can already solve most of our use cases. QuillJS, on the other hand, is not as flexible as TipTap, and its
extension system is more complicated to use.

The third big difference is in stability. We found that TipTap is more stable than QuillJS, probably because TipTap is
built on top of ProseMirror, which is a very stable and well-tested editor. Although QuillJS is also generally stable,
other developers have reported some issues with it in the past.

Our main decision driver was the extensibility of the editor. We want a text editor that is easy to extend and allows us
to implement our own features. TipTap provides a powerful extension system that is easy to use, and we can implement our
design without overwriting an existing design of other editors. Therefore, we have decided to use TipTap as the base of
our new text editor.

## Consequences

We need to replace our current sw-text-editor with the new editor. We have chosen TipTap as the base for our new text
editor,which means that we need to implement the existing UI to the editor and implement all current features. While
some features have already been implemented during the evaluation in a short amount of time, the most challenging part
will be to ensure backward compatibility.

---

---
url: /docs/v6.5/resources/references/adr/2023-03-27-admin-text-editor-evaluation.md
---

# Admin text editor evaluation

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2023-03-27-admin-text-editor-evaluation.md)
:::

## Context

The current sw-text-editor in the administration has numerous low-level bugs in basic WYSIWYG features. It is built in a
way that is difficult to maintain and understand. Therefore, we require a new text editor that is easy to maintain, has
a good feature set, is flexible to extend and more stable.

## Decision

Building a new text editor from scratch is not a viable option. Therefore, we have evaluated various existing text
editors and narrowed down our options to the following:

```
- CKEditor 5
- TinyMCE
- QuillJS
- Prosemirror
- TipTap V2
- Lexical
```

We have decided to skip CKEditor 5 and TinyMCE because they require a license for our use case and are not 100% open
source. Prosemirror was also ruled out because it provides only a low-level API and requires much more implementation
time than the other editors. Additionally, Lexical is not a valid option for us since it is specialized for React
environments and has no official support for VueJS.

The remaining two editors are TipTap V2 and QuillJS. Both have similar feature sets and APIs, but we have found some
major differences between them. The first difference is that TipTap is a headless editor, which means that it only
provides the editor logic and requires a UI implementation. QuillJS, on the other hand, is a fully featured editor that
provides a UI out of the box. In our case, it is better to use a headless editor like TipTap because we can implement
the UI to fit our needs, especially for several edge cases that are hard to implement in QuillJS.

The second major difference is in extensibility. TipTap's API is more flexible, allowing us to implement our own
features using the existing TipTap and ProseMirror plugins or build our own plugins. In most cases, the powerful main
TipTap API can already solve most of our use cases. QuillJS, on the other hand, is not as flexible as TipTap, and its
extension system is more complicated to use.

The third big difference is in stability. We found that TipTap is more stable than QuillJS, probably because TipTap is
built on top of ProseMirror, which is a very stable and well-tested editor. Although QuillJS is also generally stable,
other developers have reported some issues with it in the past.

Our main decision driver was the extensibility of the editor. We want a text editor that is easy to extend and allows us
to implement our own features. TipTap provides a powerful extension system that is easy to use, and we can implement our
design without overwriting an existing design of other editors. Therefore, we have decided to use TipTap as the base of
our new text editor.

## Consequences

We need to replace our current sw-text-editor with the new editor. We have chosen TipTap as the base for our new text
editor,which means that we need to implement the existing UI to the editor and implement all current features. While
some features have already been implemented during the evaluation in a short amount of time, the most challenging part
will be to ensure backward compatibility.

---

---
url: /docs/v6.6/resources/references/adr/2023-03-27-admin-text-editor-evaluation.md
---

# Admin text editor evaluation

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2023-03-27-admin-text-editor-evaluation.md)
:::

## Context

The current sw-text-editor in the administration has numerous low-level bugs in basic WYSIWYG features. It is built in a
way that is difficult to maintain and understand. Therefore, we require a new text editor that is easy to maintain, has
a good feature set, is flexible to extend and more stable.

## Decision

Building a new text editor from scratch is not a viable option. Therefore, we have evaluated various existing text
editors and narrowed down our options to the following:

```
- CKEditor 5
- TinyMCE
- QuillJS
- Prosemirror
- TipTap V2
- Lexical
```

We have decided to skip CKEditor 5 and TinyMCE because they require a license for our use case and are not 100% open
source. Prosemirror was also ruled out because it provides only a low-level API and requires much more implementation
time than the other editors. Additionally, Lexical is not a valid option for us since it is specialized for React
environments and has no official support for VueJS.

The remaining two editors are TipTap V2 and QuillJS. Both have similar feature sets and APIs, but we have found some
major differences between them. The first difference is that TipTap is a headless editor, which means that it only
provides the editor logic and requires a UI implementation. QuillJS, on the other hand, is a fully featured editor that
provides a UI out of the box. In our case, it is better to use a headless editor like TipTap because we can implement
the UI to fit our needs, especially for several edge cases that are hard to implement in QuillJS.

The second major difference is in extensibility. TipTap's API is more flexible, allowing us to implement our own
features using the existing TipTap and ProseMirror plugins or build our own plugins. In most cases, the powerful main
TipTap API can already solve most of our use cases. QuillJS, on the other hand, is not as flexible as TipTap, and its
extension system is more complicated to use.

The third big difference is in stability. We found that TipTap is more stable than QuillJS, probably because TipTap is
built on top of ProseMirror, which is a very stable and well-tested editor. Although QuillJS is also generally stable,
other developers have reported some issues with it in the past.

Our main decision driver was the extensibility of the editor. We want a text editor that is easy to extend and allows us
to implement our own features. TipTap provides a powerful extension system that is easy to use, and we can implement our
design without overwriting an existing design of other editors. Therefore, we have decided to use TipTap as the base of
our new text editor.

## Consequences

We need to replace our current sw-text-editor with the new editor. We have chosen TipTap as the base for our new text
editor,which means that we need to implement the existing UI to the editor and implement all current features. While
some features have already been implemented during the evaluation in a short amount of time, the most challenging part
will be to ensure backward compatibility.

---

---
url: /docs/concepts/framework/architecture/administration-concept.md
---

# Administration

In this article, you will get to know the Administration component and learn a lot of its main concepts. Along the way, you  will find answers to the following questions:

* What is the Administration, and what is its main purpose?
* Which technologies are being used?
* How is the Administration structured?
* How is the Administration implemented inside the Platform?
* How is the Administration connected to other components?
* Which parts of the Core are being used?
* What are Modules, Pages, and Components?
* How is the Administration handling Inheritance & ACL?

## Introduction

The Administration component is a Symfony bundle that contains a Single Page Application (SPA) written in JavaScript. It conceptually sits on top of the Core - similar to the [Storefront](storefront-concept) component. The SPA itself provides a rich user interface on top of REST-API-based communication. It communicates with the Core component through the Admin API and is an headless application build on custom components written in [Vue.js](https://vuejs.org/). Similar to the frameworks being used in the Storefront component, the Administration component uses SASS for styling purposes and [Twig.js](https://github.com/twigjs/twig.js/wiki) to offer templating functionalities. By default, Shopware 6 uses the [Vue I18n plugin](https://kazupon.github.io/vue-i18n/) in the Administration to deal with translation. Furthermore, [Webpack](https://webpack.js.org/) is being used to bundle and compile the SPA.

## Main concerns

As mentioned previously, the Administration component provides a SPA that communicates with the Core through the [Admin API](../../../concepts/api/admin-api). To summarize, its main concern is to provide a UI for all administrative tasks for a shop owner in Shopware. To be more precise, it does not contain any business logic. Therefore, there is no functional layering but a flat list of modules structured along the Core component and containing Vue.js web components. Every single communication with the Core can, e.g., be inspected throughout the network activities of your browser's developer tools.

Apart from the arguably most central responsibility of creating the UI itself, which can be reached through `/admin`. The Administration components implement a number of cross-cutting concerns. The most important are:

* **Providing inheritance**: As Shopware 6 offers a flexible extension system to develop own apps, plugins, or themes,  one can override or extend the Administration to fit needs. More information can be found in the [inheritance](administration-concept#inheritance) chapter of this article.

* **Data management**: The Administration displays entities of the Core component and handles the management of this data. So, of course, REST-API access is an important concern of [Pages and views](administration-concept#modules-and-their-components) where necessary. You will find many components working with in-memory representations of API-Data.

* **State management**: In contrast to the Core (Backend), the Administration is a long-running process contained in the browser. Proper state management is key here. There is a router present handling the current page selection. View and component rendering is done locally in relation to their parents. Therefore, each component manages the state of its subcomponents.

## Structure

The main Vue.js application is wrapped inside a Symfony bundle. You will find the specific SPA sources inside the Administration component in a specific sub-directory of `shopware/src/Administration`. Therefore, the SPA's main entry point is: `./Resources/app/administration`. Everything else inside `shopware/src/Administration` can be seen as a wrapped configuration around the SPA. This bundle's main concern is to set up the initial Routing (`/admin`) and the Administration's main template file, which initializes the SPA (`./Resources/views/administration/index.html.twig`) and to provide translation handling.

The `src` directory of the SPA below is structured along the three different use cases the Administration faces - provide common functionality, an application skeleton, and modules.

```bash
<shopware/src/Administration/Resources/app/administration/src/>
|- app
|- core
|- module
```

* `app`: Contains the application basis for the Administration. Generally, you will find framework dependant computational components here.
* `core`: Contains the binding to the Admin API and services.
* `module`: UI and state management of specific view pages, structured along the Core modules. More information on this is detailed below.

## Modules and their components

One module represents a navigation entry in the Administrations main menu. Since the Administration is highly dependent on the Shopware ecommerce Core, the module names reappear in the Administration, though in a slightly different order. The main building block, which the Administration knows, is called `component`, adjacent to web components.

A `component` is the combination of styling, markup, and logic. What a component does will not surprise you if you are already familiar with the [MVC pattern](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller). The role of the model and controller collapses into a single class. The components Twig.js template is generally rendered by a JavaScript (`index.js`) file and includes styling from an SCSS file. A template file also notifies the JavaScript, which then reacts to specific (user) interactions. Furthermore, components can be and often are nested. Our [Component library](https://component-library.shopware.com/) will also give you an overview of our default components.

### General module structure

A `page` represents the entry point or the page that needs to be rendered and encapsulates views. A `view` is a subordinate part of the page that encapsulates components. A `component` can itself encapsulate different components. From this level on, there is no distinction in the directory structure made.

At least one `page` is mandatory in each module. Though views and components can be present in the module, a vast default component library is present to help with default cases.

```bash
|- page1
  |- view1
    |- component1
    |- component2
      |- subcomponent1
      |- …
  |- view2
    |- component3
    |- …
```

### Order module

Having a look at a more practical example, one can look closer at the order module. Typically, you will find this structure alongside other modules, especially when creating pages or views for creating/editing, listing, or viewing a specific entity. Refer to the [Add custom module](../../../guides/plugins/plugins/administration/module-component-management/add-custom-module) article if you want to learn more about adding your custom module with a Shopware plugin.

```bash
<shopware/src/Administration/Resources/app/administration/src/module/sw-order/>
|- acl
|- component
  |- sw-order-address-modal
  |- …
|- page
  |- sw-order-create
  |- sw-order-detail
  |- sw-order-list
|- snippet  
|- state  
|- view
  |- sw-order-create-base
  |- sw-order-details-base
|- index.js
```

## Inheritance

To add new functionality or change the behavior of an existing component through plugins, you can either override or extend a component. The difference between the two methods is `Component.extend()` method creates a new component and `Component.override()` method overwrites the previous behavior of the component.

Within plugins, you do have the following options when it comes to adjusting existing components:

* Override a component's logic
* Extend a component's logic
* Customize a component template with Twig.js
* Extending methods and computed properties

You will find more information about [customizing components](../../../guides/plugins/plugins/administration/module-component-management/customizing-components) of the Administration in the guide.

## ACL in the Administration

The Access Control List (ACL) in Shopware ensures that by default, data can only be created, read, updated, or deleted ( CRUD), once the user has specific privileges for a module. Additionally, one can set up custom roles in the Administrations UI or develop individual privileges with plugins. These roles have finely granular rights, which every shop operator can set up himself and be assigned to users. By default, a module of the Administration has a directory called `acl` included. In this directory, one will find a specific mapping of privileges (permissions for roles; additional permissions) for the default roles: `viewer`, `editor`, `creator`, and `deleter`.

For more information, refer to [Adding permissions](../../../guides/plugins/plugins/administration/permissions-error-handling/add-acl-rules) article.

---

---
url: /docs/guides/plugins/apps/administration.md
---

# Administration

You can't extend the Shopware Administration by means of freely overriding and extending Administration components, all js files you provide in the `Resources/administration` namespace will be ignored. Instead, you have more defined extension points and can extend the Administration by other means: You are able to [add your own modules](add-custom-modules), [custom fields](../custom-data/custom-fields) or [action buttons](add-custom-action-button) via manifest file.

Starting with version 6.4.2.0 you can also extend Shopware's CMS module by [adding custom CMS blocks](../content/cms/add-custom-cms-blocks).

---

---
url: /docs/guides/plugins/plugins/administration.md
---

# Administration

The Administration allows customizations and extensions of backend interface functionality. It is possible to add modules, routes, components, services, permissions, and UI logic.

Typical use cases include:

* Adding a custom module
* Registering routes and navigation entries
* Creating Vue components
* Working with repositories and API data
* Handling permissions (ACL)
* Injecting services
* Customizing templates and styling

This section follows a practical development workflow. Start with registering a module and route, then build the components, connect data, and refine permissions and UI behavior.

For stable cross-version extension points, use the [Meteor Admin SDK](../../apps/administration/meteor-admin-sdk.md). The SDK can be used by both apps and plugins.

## Developer workflow

When extending the Administration inside a plugin, follow this sequence:

1. [Add a custom module](module-component-management/add-custom-module.md) and [menu entry](routing-navigation/add-menu-entry.md)
2. [Add custom routes](routing-navigation/add-custom-route.md)
3. [Add custom components](module-component-management/add-custom-component.md) and [use base components](module-component-management/using-base-components.md)
4. Connect [data](data-handling-processing/using-data-handling.md) (repositories or [API requests](services-utilities/making-api-requests.md))
5. Handle permissions and [add ACL rules](permissions-error-handling/add-acl-rules.md)
6. [Inject services](services-utilities/injecting-services.md) and [extend services](services-utilities/extending-services.md)
7. [Customize templates](templates-styling/writing-templates.md) and [add custom styles](templates-styling/add-custom-styles.md)
8. Manage state using [Vuex](data-handling-processing/using-vuex-state.md) or [Pinia](../../../upgrades-migrations/administration/pinia.md)

Advanced topics such as [mixins and directives](mixins-directives/using-mixins.md) or [extending webpack](advanced-configuration/extending-webpack.md) are covered separately.

Let’s start by [adding a custom module](module-component-management/add-custom-module.md).

---

---
url: /docs/guides/upgrades-migrations/administration.md
---

# Administration

These guides cover architectural changes and migration paths affecting Administration extensions, helping you prepare plugins for major system transitions. Depending on the version, some changes—for example, Vue 3, Pinia, and Vite—may have already been completed:

* [Vue 3 migration](./vue3)
* [Meteor components](./meteor-components)
* [Pinia migration](./pinia)
* [Vite migration](./vite)
* [Vue migration build removal](./vue-migration-build)
* [Native Vue implementation](./vue-native)

---

---
url: /docs/products/extensions/b2b-suite/guides/administration.md
---
# Administration

B2B Suite Administration modules are built following the official [Shopware Administration](https://developer.shopware.com/docs/guides/plugins/plugins/administration/) documentation. For a more in-depth guide, please refer to the [User documentation](https://docs.shopware.com/en/shopware-6-en/extensions/b2b-suite-administration).

---

---
url: /docs/v6.5/concepts/framework/architecture/administration-concept.md
---

# Administration

In this article, you will get to know the Administration component and learn a lot of its main concepts. Along the way, you  will find answers to the following questions:

* What is the Administration, and what is its main purpose?
* Which technologies are being used?
* How is the Administration structured?
* How is the Administration implemented inside the Platform?
* How is the Administration connected to other components?
* Which parts of the Core are being used?
* What are Modules, Pages, and Components?
* How is the Administration handling Inheritance & ACL?

## Introduction

The Administration component is a Symfony bundle that contains a Single Page Application (SPA) written in JavaScript. It conceptually sits on top of the Core - similar to the [Storefront](storefront-concept) component. The SPA itself provides a rich user interface on top of REST-API-based communication. It communicates with the Core component through the Admin API and is an headless application build on custom components written in [Vue.js](https://vuejs.org/). Similar to the frameworks being used in the Storefront component, the Administration component uses SASS for styling purposes and [Twig.js](https://github.com/twigjs/twig.js/wiki) to offer templating functionalities. By default, Shopware 6 uses the [Vue I18n plugin](https://kazupon.github.io/vue-i18n/) in the Administration to deal with translation. Furthermore, [Webpack](https://webpack.js.org/) is being used to bundle and compile the SPA.

## Main concerns

As mentioned previously, the Administration component provides a SPA that communicates with the Core through the [Admin API](../../../concepts/api/admin-api). To summarize, its main concern is to provide a UI for all administrative tasks for a shop owner in Shopware. To be more precise, it does not contain any business logic. Therefore, there is no functional layering but a flat list of modules structured along the Core component and containing Vue.js web components. Every single communication with the Core can, e.g., be inspected throughout the network activities of your browser's developer tools.

Apart from the arguably most central responsibility of creating the UI itself, which can be reached through `/admin`. The Administration components implement a number of cross-cutting concerns. The most important are:

* **Providing inheritance**: As Shopware 6 offers a flexible extension system to develop own apps, plugins, or themes,  one can override or extend the Administration to fit needs. More information can be found in the [inheritance](administration-concept#inheritance) chapter of this article.

* **Data management**: The Administration displays entities of the Core component and handles the management of this data. So, of course, REST-API access is an important concern of [Pages and views](administration-concept#modules-and-their-components) where necessary. You will find many components working with in-memory representations of API-Data.

* **State management**: In contrast to the Core (Backend), the Administration is a long-running process contained in the browser. Proper state management is key here. There is a router present handling the current page selection. View and component rendering is done locally in relation to their parents. Therefore, each component manages the state of its subcomponents.

## Structure

The main Vue.js application is wrapped inside a Symfony bundle. You will find the specific SPA sources inside the Administration component in a specific sub-directory of `shopware/src/Administration`. Therefore, the SPA's main entry point is: `./Resources/app/administration`. Everything else inside `shopware/src/Administration` can be seen as a wrapped configuration around the SPA. This bundle's main concern is to set up the initial Routing (`/admin`) and the Administration's main template file, which initializes the SPA (`./Resources/views/administration/index.html.twig`) and to provide translation handling.

The `src` directory of the SPA below is structured along the three different use cases the Administration faces - provide common functionality, an application skeleton, and modules.

```bash
<shopware/src/Administration/Resources/app/administration/src/>
|- app
|- core
|- module
```

* `app`: Contains the application basis for the Administration. Generally, you will find framework dependant computational components here.
* `core`: Contains the binding to the Admin API and services.
* `module`: UI and state management of specific view pages, structured along the Core modules. More information on this is detailed below.

## Modules and their components

One module represents a navigation entry in the Administrations main menu. Since the Administration is highly dependent on the Shopware ecommerce Core, the module names reappear in the Administration, though in a slightly different order. The main building block, which the Administration knows, is called `component`, adjacent to web components.

A `component` is the combination of styling, markup, and logic. What a component does will not surprise you if you are already familiar with the [MVC pattern](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller). The role of the model and controller collapses into a single class. The components Twig.js template is generally rendered by a JavaScript (`index.js`) file and includes styling from an SCSS file. A template file also notifies the JavaScript, which then reacts to specific (user) interactions. Furthermore, components can be and often are nested. Our [Component library](https://component-library.shopware.com/) will also give you an overview of our default components.

### General module structure

A `page` represents the entry point or the page that needs to be rendered and encapsulates views. A `view` is a subordinate part of the page that encapsulates components. A `component` can itself encapsulate different components. From this level on, there is no distinction in the directory structure made.

At least one `page` is mandatory in each module. Though views and components can be present in the module, a vast default component library is present to help with default cases.

```bash
|- page1
  |- view1
    |- component1
    |- component2
      |- subcomponent1
      |- …
  |- view2
    |- component3
    |- …
```

### Order module

Having a look at a more practical example, one can look closer at the order module. Typically, you will find this structure alongside other modules, especially when creating pages or views for creating/editing, listing, or viewing a specific entity. Refer to the [Add custom module](../../../guides/plugins/plugins/administration/add-custom-module) article if you want to learn more about adding your custom module with a Shopware plugin.

```bash
<shopware/src/Administration/Resources/app/administration/src/module/sw-order/>
|- acl
|- component
  |- sw-order-address-modal
  |- …
|- page
  |- sw-order-create
  |- sw-order-detail
  |- sw-order-list
|- snippet  
|- state  
|- view
  |- sw-order-create-base
  |- sw-order-details-base
|- index.js
```

## Inheritance

To add new functionality or change the behavior of an existing component through plugins, you can either override or extend a component. The difference between the two methods is `Component.extend()` method creates a new component and `Component.override()` method overwrites the previous behavior of the component.

Within plugins, you do have the following options when it comes to adjusting existing components:

* Override a component's logic
* Extend a component's logic
* Customize a component template with Twig.js
* Extending methods and computed properties

You will find more information about [customizing components](../../../guides/plugins/plugins/administration/customizing-components) of the Administration in the guide.

## ACL in the Administration

The Access Control List (ACL) in Shopware ensures that by default, data can only be created, read, updated, or deleted ( CRUD), once the user has specific privileges for a module. Additionally, one can set up custom roles in the Administrations UI or develop individual privileges with plugins. These roles have finely granular rights, which every shop operator can set up himself and be assigned to users. By default, a module of the Administration has a directory called `acl` included. In this directory, one will find a specific mapping of privileges (permissions for roles; additional permissions) for the default roles: `viewer`, `editor`, `creator`, and `deleter`.

For more information, refer to [Adding permissions](../../../guides/plugins/plugins/administration/add-acl-rules) article.

---

---
url: /docs/v6.5/guides/plugins/apps/administration.md
---

# Administration

You can't extend the Shopware Administration by means of freely overriding and extending Administration components, all js files you provide in the `Resources/administration` namespace will be ignored. Instead, you have more defined extension points and can extend the Administration by other means: You are able to [add your own modules](add-custom-modules), [custom fields](../custom-data/custom-fields) or [action buttons](add-custom-action-button) via manifest file.

Starting with version 6.4.2.0 you can also extend Shopware's CMS module by [adding custom CMS blocks](../content/cms/add-custom-cms-blocks).

---

---
url: /docs/v6.5/guides/plugins/plugins/administration.md
---

# Administration

Shopware allows to extend the functionality of the Shopware administration panel, providing additional features and customization options for managing the e-commerce platform. The plugin allows businesses to tailor the administration interface to their specific needs, adding custom sections, modules, services, or functionalities to streamline their workflow and enhance the user experience. The administration plugin offers flexibility in configuring dashboards, menu structures, permissions, and settings, empowering businesses to create a customized and efficient administration experience that aligns with their unique requirements.

---

---
url: /docs/v6.5/products/extensions/b2b-suite/guides/administration.md
---
# Administration

B2B Suite Administration modules are built following the official [Shopware Administration](https://developer.shopware.com/docs/guides/plugins/plugins/administration/) documentation. For a more in-depth guide, please refer to the [User documentation](https://docs.shopware.com/en/shopware-6-en/extensions/b2b-suite-administration).

---

---
url: /docs/v6.5/resources/references/upgrades/administration.md
---

# Administration

This section contains all upgrade guides related to the Shopware Administration.

---

---
url: /docs/v6.6/concepts/framework/architecture/administration-concept.md
---

# Administration

In this article, you will get to know the Administration component and learn a lot of its main concepts. Along the way, you  will find answers to the following questions:

* What is the Administration, and what is its main purpose?
* Which technologies are being used?
* How is the Administration structured?
* How is the Administration implemented inside the Platform?
* How is the Administration connected to other components?
* Which parts of the Core are being used?
* What are Modules, Pages, and Components?
* How is the Administration handling Inheritance & ACL?

## Introduction

The Administration component is a Symfony bundle that contains a Single Page Application (SPA) written in JavaScript. It conceptually sits on top of the Core - similar to the [Storefront](storefront-concept) component. The SPA itself provides a rich user interface on top of REST-API-based communication. It communicates with the Core component through the Admin API and is an headless application build on custom components written in [Vue.js](https://vuejs.org/). Similar to the frameworks being used in the Storefront component, the Administration component uses SASS for styling purposes and [Twig.js](https://github.com/twigjs/twig.js/wiki) to offer templating functionalities. By default, Shopware 6 uses the [Vue I18n plugin](https://kazupon.github.io/vue-i18n/) in the Administration to deal with translation. Furthermore, [Webpack](https://webpack.js.org/) is being used to bundle and compile the SPA.

## Main concerns

As mentioned previously, the Administration component provides a SPA that communicates with the Core through the [Admin API](../../../concepts/api/admin-api). To summarize, its main concern is to provide a UI for all administrative tasks for a shop owner in Shopware. To be more precise, it does not contain any business logic. Therefore, there is no functional layering but a flat list of modules structured along the Core component and containing Vue.js web components. Every single communication with the Core can, e.g., be inspected throughout the network activities of your browser's developer tools.

Apart from the arguably most central responsibility of creating the UI itself, which can be reached through `/admin`. The Administration components implement a number of cross-cutting concerns. The most important are:

* **Providing inheritance**: As Shopware 6 offers a flexible extension system to develop own apps, plugins, or themes,  one can override or extend the Administration to fit needs. More information can be found in the [inheritance](administration-concept#inheritance) chapter of this article.

* **Data management**: The Administration displays entities of the Core component and handles the management of this data. So, of course, REST-API access is an important concern of [Pages and views](administration-concept#modules-and-their-components) where necessary. You will find many components working with in-memory representations of API-Data.

* **State management**: In contrast to the Core (Backend), the Administration is a long-running process contained in the browser. Proper state management is key here. There is a router present handling the current page selection. View and component rendering is done locally in relation to their parents. Therefore, each component manages the state of its subcomponents.

## Structure

The main Vue.js application is wrapped inside a Symfony bundle. You will find the specific SPA sources inside the Administration component in a specific sub-directory of `shopware/src/Administration`. Therefore, the SPA's main entry point is: `./Resources/app/administration`. Everything else inside `shopware/src/Administration` can be seen as a wrapped configuration around the SPA. This bundle's main concern is to set up the initial Routing (`/admin`) and the Administration's main template file, which initializes the SPA (`./Resources/views/administration/index.html.twig`) and to provide translation handling.

The `src` directory of the SPA below is structured along the three different use cases the Administration faces - provide common functionality, an application skeleton, and modules.

```bash
<shopware/src/Administration/Resources/app/administration/src/>
|- app
|- core
|- module
```

* `app`: Contains the application basis for the Administration. Generally, you will find framework dependant computational components here.
* `core`: Contains the binding to the Admin API and services.
* `module`: UI and state management of specific view pages, structured along the Core modules. More information on this is detailed below.

## Modules and their components

One module represents a navigation entry in the Administrations main menu. Since the Administration is highly dependent on the Shopware ecommerce Core, the module names reappear in the Administration, though in a slightly different order. The main building block, which the Administration knows, is called `component`, adjacent to web components.

A `component` is the combination of styling, markup, and logic. What a component does will not surprise you if you are already familiar with the [MVC pattern](https://en.wikipedia.org/wiki/Model%E2%80%93view%E2%80%93controller). The role of the model and controller collapses into a single class. The components Twig.js template is generally rendered by a JavaScript (`index.js`) file and includes styling from an SCSS file. A template file also notifies the JavaScript, which then reacts to specific (user) interactions. Furthermore, components can be and often are nested. Our [Component library](https://component-library.shopware.com/) will also give you an overview of our default components.

### General module structure

A `page` represents the entry point or the page that needs to be rendered and encapsulates views. A `view` is a subordinate part of the page that encapsulates components. A `component` can itself encapsulate different components. From this level on, there is no distinction in the directory structure made.

At least one `page` is mandatory in each module. Though views and components can be present in the module, a vast default component library is present to help with default cases.

```bash
|- page1
  |- view1
    |- component1
    |- component2
      |- subcomponent1
      |- …
  |- view2
    |- component3
    |- …
```

### Order module

Having a look at a more practical example, one can look closer at the order module. Typically, you will find this structure alongside other modules, especially when creating pages or views for creating/editing, listing, or viewing a specific entity. Refer to the [Add custom module](../../../guides/plugins/plugins/administration/add-custom-module) article if you want to learn more about adding your custom module with a Shopware plugin.

```bash
<shopware/src/Administration/Resources/app/administration/src/module/sw-order/>
|- acl
|- component
  |- sw-order-address-modal
  |- …
|- page
  |- sw-order-create
  |- sw-order-detail
  |- sw-order-list
|- snippet  
|- state  
|- view
  |- sw-order-create-base
  |- sw-order-details-base
|- index.js
```

## Inheritance

To add new functionality or change the behavior of an existing component through plugins, you can either override or extend a component. The difference between the two methods is `Component.extend()` method creates a new component and `Component.override()` method overwrites the previous behavior of the component.

Within plugins, you do have the following options when it comes to adjusting existing components:

* Override a component's logic
* Extend a component's logic
* Customize a component template with Twig.js
* Extending methods and computed properties

You will find more information about [customizing components](../../../guides/plugins/plugins/administration/customizing-components) of the Administration in the guide.

## ACL in the Administration

The Access Control List (ACL) in Shopware ensures that by default, data can only be created, read, updated, or deleted ( CRUD), once the user has specific privileges for a module. Additionally, one can set up custom roles in the Administrations UI or develop individual privileges with plugins. These roles have finely granular rights, which every shop operator can set up himself and be assigned to users. By default, a module of the Administration has a directory called `acl` included. In this directory, one will find a specific mapping of privileges (permissions for roles; additional permissions) for the default roles: `viewer`, `editor`, `creator`, and `deleter`.

For more information, refer to [Adding permissions](../../../guides/plugins/plugins/administration/add-acl-rules) article.

---

---
url: /docs/v6.6/guides/plugins/apps/administration.md
---

# Administration

You can't extend the Shopware Administration by means of freely overriding and extending Administration components, all js files you provide in the `Resources/administration` namespace will be ignored. Instead, you have more defined extension points and can extend the Administration by other means: You are able to [add your own modules](add-custom-modules), [custom fields](../custom-data/custom-fields) or [action buttons](add-custom-action-button) via manifest file.

Starting with version 6.4.2.0 you can also extend Shopware's CMS module by [adding custom CMS blocks](../content/cms/add-custom-cms-blocks).

---

---
url: /docs/v6.6/guides/plugins/plugins/administration.md
---

# Administration

Shopware allows to extend the functionality of the Shopware administration panel, providing additional features and customization options for managing the e-commerce platform. The plugin allows businesses to tailor the administration interface to their specific needs, adding custom sections, modules, services, or functionalities to streamline their workflow and enhance the user experience. The administration plugin offers flexibility in configuring dashboards, menu structures, permissions, and settings, empowering businesses to create a customized and efficient administration experience that aligns with their unique requirements.

---

---
url: /docs/v6.6/products/extensions/b2b-suite/guides/administration.md
---
# Administration

B2B Suite Administration modules are built following the official [Shopware Administration](https://developer.shopware.com/docs/guides/plugins/plugins/administration/) documentation. For a more in-depth guide, please refer to the [User documentation](https://docs.shopware.com/en/shopware-6-en/extensions/b2b-suite-administration).

---

---
url: /docs/v6.6/resources/references/upgrades/administration.md
---

# Administration

This section contains all upgrade guides related to the Shopware Administration.

---

---
url: /docs/resources/references/adr/2026-05-13-administration-pr-guidelines.md
---

# Administration Pull Request Guidelines

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2026-05-13-administration-pr-guidelines.md)
:::

## Context

Administration pull requests are often reviewed by people who do not have the same feature context as the author. Without clear review guidance, reviewers must reconstruct the affected area, the reason for the diff, and the intended behavior from code alone. This slows down reviews and increases the risk that important changes are missed while minor feedback receives too much attention.

## Decision

Administration pull requests must be prepared for reviewers who do not share the author's context:

* **Review your PR diff:** Authors review their own diff before requesting review and check whether the PR is understandable, sufficiently scoped, and small enough.
* **Explain the area:** PR descriptions explain the affected area when the change touches a niche or non-obvious feature. They should link existing documentation or briefly describe the relevant concept.
* **How to reproduce:** PR descriptions include concrete reproduction or verification steps. They state the behavior before and after the change and explain how a reviewer can confirm that the PR solves the problem.
* **Give context how to review:** PR descriptions explain non-obvious diffs. If a change is hard to understand from the diff alone, the explanation belongs in the PR description or as a GitHub comment on the relevant lines.
* **How should I review your PR?**: PR descriptions guide the review order when useful. For example: read a concept document first, then the test file, then the API implementation.
* **Only small PRs:** Administration PRs should stay below 500 changed lines. Larger changes should be split into stacked PRs with a clear review order.
* **Pareto Principle:** Reviewers focus on the small part of the change that carries most of the risk or impact, and avoid spending review attention on low-impact feedback that tooling or existing guidelines already cover.
* **Code Guidelines:** Authors and reviewers follow the existing Administration coding guidelines and required linting.

## Consequences

Administration PRs become easier to understand, verify, and review asynchronously. Authors invest more effort before requesting review, but reviewers need less time to reconstruct context. Large Administration changes need to be planned as smaller, stackable PRs instead of being reviewed as one broad diff.

---

---
url: /docs/guides/plugins/plugins/administration/administration-reference.md
---

# Administration Reference

Plugins extend the Administration by integrating directly into the Vue-based admin framework. Use these guides when building custom admin modules or components, or when extending existing ones.

## Core Concepts

* [Directives](directives.md): Globally registered Vue directives.
* [Mixins](mixins.md): Shared Vue mixins used across the Administration.
* [Utils](utils.md): Global utility functions available on the `Shopware` object.

Use these guides to:

* Reuse core functionality instead of implementing it again
* Follow Administration extension conventions
* Build extensions that integrate cleanly into the Admin UI

---

---
url: /docs/v6.5/resources/references/administration-reference.md
---

# Administration Reference

This section covers concepts on Utils, Mixins and Directives.

---

---
url: /docs/v6.6/resources/references/administration-reference.md
---

# Administration Reference

This section covers concepts on Utils, Mixins and Directives.

---

---
url: /docs/resources/guidelines/code/core/adr.md
---
::: info
This document represents core guidelines and has been mirrored from the core in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/coding-guidelines/core/adr.md)
:::

# ADR

This guideline describes what we expect from our ADRs and how you can write some.

Joel Parker Henderson has done a lot of work on this topic, collected excellent ideas, tips, templates, and examples, and published them on [github](https://github.com/joelparkerhenderson/architecture-decision-record).

The ADRs examples published there are good.

Expectations for an ADR:

* Write a complete description of the requirements
* List all technical domains that are affected by the ADR
* List all affected logic in the system that are affected
* Write some pseudo code for your new logic to visualize what you want to realize
* Define all public APIs that are to be created or changed with your new logic
* Define how developers can extend the new APIs and logic and what possible business cases you see
* Define the reason why you made the decision. It often helps to understand why you made a specific architectural change in the future.
* Define all consequences of the decision and how they impact a developer who has used the code/product.

Everyone takes a different approach to create ADRs and meeting the expectations above. One possible approach is the following:

* Create a list of domains you want to touch (Store-API, admin process, indexing, ...)
* Create a headline for each domain
* Describe the domains. After each headline, write in 2 sentences why this domain is relevant for this ADR
* Describe the "problems" of each domain... write in each domain which logic has to be touched... not how you want to change them, only why
  * e.G. indexing: "We have to extend the product indexing process because calculating the new product data is too expensive, and we want to calculate the values in a background job."
* Describe the "solution" of each domain... write in each domain how you want to extend the above logic to solve your "problems."
* Add a new section about extendability and write down how developers should be able to extend your system and which business cases you see
* Last, add some pseudocode at the end to visualize your solutions and ideas.

---

---
url: /docs/v6.5/resources/guidelines/code/core/adr.md
---
::: info
This document represents core guidelines and has been mirrored from the core in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/coding-guidelines/core/adr.md)
:::

# ADR

This guideline describes what we expect from our ADRs and how you can write some.

Joel Parker Henderson has done a lot of work on this topic, collected excellent ideas, tips, templates, and examples, and published them on [github](https://github.com/joelparkerhenderson/architecture-decision-record).

The ADRs examples published there are good.

Expectations for an ADR:

* Write a complete description of the requirements
* List all technical domains that are affected by the ADR
* List all affected logic in the system that are affected
* Write some pseudo code for your new logic to visualize what you want to realize
* Define all public APIs that are to be created or changed with your new logic
* Define how developers can extend the new APIs and logic and what possible business cases you see
* Define the reason why you made the decision. It often helps to understand why you made a specific architectural change in the future.
* Define all consequences of the decision and how they impact a developer who has used the code/product.

Everyone takes a different approach to create ADRs and meeting the expectations above. One possible approach is the following:

* Create a list of domains you want to touch (Store-API, admin process, indexing, ...)
* Create a headline for each domain
* Describe the domains. After each headline, write in 2 sentences why this domain is relevant for this ADR
* Describe the "problems" of each domain... write in each domain which logic has to be touched... not how you want to change them, only why
  * e.G. indexing: "We have to extend the product indexing process because calculating the new product data is too expensive, and we want to calculate the values in a background job."
* Describe the "solution" of each domain... write in each domain how you want to extend the above logic to solve your "problems."
* Add a new section about extendability and write down how developers should be able to extend your system and which business cases you see
* Last, add some pseudocode at the end to visualize your solutions and ideas.

---

---
url: /docs/v6.6/resources/guidelines/code/core/adr.md
---
::: info
This document represents core guidelines and has been mirrored from the core in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/coding-guidelines/core/adr.md)
:::

# ADR

This guideline describes what we expect from our ADRs and how you can write some.

Joel Parker Henderson has done a lot of work on this topic, collected excellent ideas, tips, templates, and examples, and published them on [github](https://github.com/joelparkerhenderson/architecture-decision-record).

The ADRs examples published there are good.

Expectations for an ADR:

* Write a complete description of the requirements
* List all technical domains that are affected by the ADR
* List all affected logic in the system that are affected
* Write some pseudo code for your new logic to visualize what you want to realize
* Define all public APIs that are to be created or changed with your new logic
* Define how developers can extend the new APIs and logic and what possible business cases you see
* Define the reason why you made the decision. It often helps to understand why you made a specific architectural change in the future.
* Define all consequences of the decision and how they impact a developer who has used the code/product.

Everyone takes a different approach to create ADRs and meeting the expectations above. One possible approach is the following:

* Create a list of domains you want to touch (Store-API, admin process, indexing, ...)
* Create a headline for each domain
* Describe the domains. After each headline, write in 2 sentences why this domain is relevant for this ADR
* Describe the "problems" of each domain... write in each domain which logic has to be touched... not how you want to change them, only why
  * e.G. indexing: "We have to extend the product indexing process because calculating the new product data is too expensive, and we want to calculate the values in a background job."
* Describe the "solution" of each domain... write in each domain how you want to extend the above logic to solve your "problems."
* Add a new section about extendability and write down how developers should be able to extend your system and which business cases you see
* Last, add some pseudocode at the end to visualize your solutions and ideas.

---

---
url: /docs/guides/plugins/plugins/administration/advanced-configuration.md
---

# Advanced Configuration

This section covers advanced Administration and build-related customizations for plugins. Use these guides to extend or override core behavior in a more advanced way:

* [Add Rule Assignment Configuration](./add-rule-assignment-configuration)
* [Add Shortcuts](./add-shortcuts)
* [Extending Webpack](./extending-webpack)
* [Modify Blacklist for Dynamic Product Groups](./modify-blacklist-for-dynamic-product-groups)

These topics go beyond basic plugin setup and require familiarity with the Administration architecture and component overriding.

---

---
url: /docs/guides/installation/advanced-options.md
---

# Advanced Options

This section covers optional and advanced Docker configuration for Shopware projects. Refer to it once your local environment is running and you want to customize your setup, mirror production more closely, or support advanced workflows.

## Installing into an existing directory

If you already have a target directory, `cd` into it and run the `project create` command. When prompted for a project name, leave the field empty. The project will
be generated in the current directory:

```bash
cd /path/to/project
shopware-cli project create
```

In non-interactive mode, omit the project name argument (or pass `.`) to
achieve the same result:

```bash
shopware-cli project create --no-interaction
```

## Customizing the runtime environment

### Image variations

Shopware provides multiple Docker image variants so you can match your local setup to your project's PHP version, Node version, and preferred web server. The image tag format is `ghcr.io/shopware/docker-dev:php(PHP_VERSION)-node(NODE_VERSION)-(WEBSERVER)`.

Version matrix:

PHP versions

* `8.4` - PHP 8.4
* `8.3` - PHP 8.3
* `8.2` - PHP 8.2

Node versions

* `node24` - Node 24
* `node22` - Node 22

Web server

* `caddy` - Caddy as a web server
* `nginx` - Nginx as a web server

Examples

* `ghcr.io/shopware/docker-dev:php8.4-node24-caddy` - PHP 8.4, Node 24, Caddy as web server
* `ghcr.io/shopware/docker-dev:php8.3-node24-caddy` - PHP 8.3, Node 24, Caddy as web server
* `ghcr.io/shopware/docker-dev:php8.4-node22-nginx` - PHP 8.4, Node 22, Nginx as web server
* `ghcr.io/shopware/docker-dev:php8.3-node22-nginx` - PHP 8.3, Node 22, Nginx as web server

Choose the variant that best matches your production stack.

## Adding S3-compatible storage (Minio)

Some projects use Amazon S3 for production file storage. If you want to mimic that behavior locally - for example, to test uploads or CDN-like delivery, you can add [Minio](https://www.min.io/), an open source, S3-compatible storage server.

### 1. Add the Minio service

Include a `minio` service in your `compose.yaml`:

```yaml
services:
  # ....
  minio:
    image: minio/minio
    command: server /data --console-address ":9001"
    environment:
      MINIO_ROOT_USER: minioadmin
      MINIO_ROOT_PASSWORD: minioadmin
    healthcheck:
      test: ["CMD", "mc", "ready", "local"]
      start_period: 20s
      start_interval: 10s
      interval: 1m
      timeout: 20s
      retries: 3
    ports:
 - "9000:9000"
 - "9001:9001"
    volumes:
 - minio-data:/data

  minio-setup:
    image: minio/mc
    depends_on:
      minio:
        condition: service_healthy
    entrypoint: >
 /bin/sh -c "
 set -e;
 mc alias set local http://minio:9000 minioadmin minioadmin;
 mc mb local/shopware-public local/shopware-private --ignore-existing;
 mc anonymous set download local/shopware-public;
 "
    restart: no
  # ...

volumes:
  # ...
  minio-data:
```

### 2. Configure Shopware to use Minio

Create a `config/packages/minio.yaml`:

```yaml
# yaml-language-server: $schema=https://raw.githubusercontent.com/shopware/shopware/refs/heads/trunk/config-schema.json

shopware:
  filesystem:
    public: &s3_public
      type: "amazon-s3"
      url: "http://localhost:9000/shopware-public"
      config:
        bucket: shopware-public
        endpoint: http://minio:9000
        use_path_style_endpoint: true
        region: us-east-1
        credentials:
          key: minioadmin
          secret: minioadmin
    theme: *s3_public
    sitemap: *s3_public
    private:
      type: "amazon-s3"
      config:
        bucket: shopware-private
        endpoint: http://minio:9000
        use_path_style_endpoint: true
        region: us-east-1
        credentials:
          key: minioadmin
          secret: minioadmin

```

After adding the Minio service to your `compose.yaml` and creating the configuration file, Shopware will use Minio as the S3 storage for public and private files.

### 3. Run Minio containers

Run the below command to start the Minio containers:

```bash
docker compose up -d
```

You can access the Minio console at <http://localhost:9001> with the username `minioadmin` and password `minioadmin`.

Finally, regenerate the assets to upload them to S3:

```bash
make shell
bin/console asset:install
bin/console theme:compile
```

## Using OrbStack routing

If you're using [OrbStack](https://orbstack.dev) on macOS, you can avoid manual port management by using its built-in routing feature. OrbStack automatically assigns local `.orb.local` URLs to your containers, allowing you to run multiple Shopware instances at the same time without port conflicts.

To enable it, create a `compose.override.yaml` in your project root with the following content:

```yaml
services:
  web:
      ports: !override []
      environment:
          APP_URL: https://web.sw.orb.local
          SYMFONY_TRUSTED_PROXIES: REMOTE_ADDR

###> symfony/mailer ###
  mailer:
    image: axllent/mailpit
    environment:
      MP_SMTP_AUTH_ACCEPT_ANY: 1
      MP_SMTP_AUTH_ALLOW_INSECURE: 1
###< symfony/mailer ###

```

The `APP_URL` environment variable follows this pattern: `web.<project-name>.orb.local`, where`<project-name>` comes from your local project directory name. For example, a project folder named `shopware` results in the URL `https://web.shopware.orb.local`, while a folder named `shopware-6` results in `https://web.shopware-6.orb.local`.

You can also open `https://orb.local` in your browser to view all running containers and their assigned URLs.

## Working with production data locally

When importing production databases into your local environment, image URLs in the data may still point to production servers - leading to broken or missing images in your local store. You can proxy those images locally instead of downloading everything.

Add the `imageproxy` service to your `compose.override.yaml`:

```yaml
services:
    imageproxy:
        image: ghcr.io/shopwarelabs/devcontainer/image-proxy
        ports:
 - "8050:8000"
        environment:
          # Your production URL.
          REMOTE_SERVER_HOST: shopware.com
```

This starts a proxy server that fetches images from the production environment and caches them locally. For example, a request to `http://localhost:8050/assets/images.png` will be served from `https://[REMOTE_SERVER_HOST]/assets/images.png` and then stored in the local cache for faster reuse.

Next, configure Shopware to use the proxy server. Create a new YAML file `config/packages/media-proxy.yaml`:

```yaml
shopware:
  filesystem:
    public:
      url: "http://localhost:8050"
```

Images are fetched from production on demand and cached locally.

---

---
url: /docs/products/extensions/advanced-search.md
---

# Advanced Search

::: info
Advanced Search is available starting with Commercial 5.5.0
:::

Shopware Advanced Search is a part of the Commercial plugin available along with the Evolve and Beyond plan.

Advanced search module is based on Elasticsearch. In addition to a high performance product search, it also offers you the possibilities to customize the search experience depending on your needs. So you could also search for manufacturers and categories. The simple Administration module allows quick and easy configuration of the search.

Before continuing, you should make sure you have a basic knowledge of [Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/7.10/index.html) and the Shopware implementation of it.

---

---
url: /docs/v6.5/products/extensions/advanced-search.md
---

# Advanced Search

::: info
Advanced Search is available starting with Commercial 5.5.0
:::

Shopware Advanced Search is a part of the Commercial plugin available along with the Evolve and Beyond plan.

Advanced search module is based on Elasticsearch. In addition to a high performance product search, it also offers you the possibilities to customize the search experience depending on your needs. So you could also search for manufacturers and categories. The simple Administration module allows quick and easy configuration of the search.

Before continuing, you should make sure you have a basic knowledge of [Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/7.10/index.html) and the Shopware implementation of it.

---

---
url: /docs/v6.6/products/extensions/advanced-search.md
---

# Advanced Search

::: info
Advanced Search is available starting with Commercial 5.5.0
:::

Shopware Advanced Search is a part of the Commercial plugin available along with the Evolve and Beyond plan.

Advanced search module is based on Elasticsearch. In addition to a high performance product search, it also offers you the possibilities to customize the search experience depending on your needs. So you could also search for manufacturers and categories. The simple Administration module allows quick and easy configuration of the search.

Before continuing, you should make sure you have a basic knowledge of [Elasticsearch](https://www.elastic.co/guide/en/elasticsearch/reference/7.10/index.html) and the Shopware implementation of it.

---

---
url: /docs/guides/plugins/plugins/storefront/advanced.md
---

# Advanced Storefront Customization

This section covers advanced topics for extending and customizing the Storefront in plugins.

These guides focus on performance optimization, caching behavior, cookie consent integration, and JavaScript plugin control:

* [Add caching to custom controller](./add-caching-to-custom-controller.md)
* [Add cookie to manager](./add-cookie-to-manager.md)
* [Reacting to cookie consent changes](./reacting-to-cookie-consent-changes.md)
* [Remove JavaScript plugin](./remove-unnecessary-js-plugin.md)

---

---
url: /docs/resources/guidelines/code/core/agent-skills.md
---
::: info
This document represents core guidelines and has been mirrored from the core in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/coding-guidelines/core/agent-skills.md)
:::

# Agent Skills

How to add an AI Skill to this repository — file layout, the optional
unattended twin, and the conventions that keep two skills looking like two
skills, not two snowflakes.

A **Skill** packages an AI capability in the [Anthropic Agent Skills](https://agentskills.io/specification)
format. It is offered to Claude Code, opencode, Codex CLI, Cursor, Gemini
CLI and other Agent-Skills-compatible runtimes. Skills normally match their
`description` against the user message (best-effort, model-decided); skills
with unattended CI twins require explicit invocation. This repository ships
several skills; the same pattern applies to any new skill.

## Two surfaces per skill

Each skill has up to two surfaces — keep them in lockstep:

1. **Interactive** — `.agents/skills/<name>/SKILL.md`. Loaded into a developer's
   editor session. `.claude/skills` points to the same directory for Claude
   Code compatibility. Emits whatever output format is most useful to a human
   (typically Markdown).
2. **Unattended (optional)** — a [GitHub Agentic Workflow](https://github.com/githubnext/gh-aw)
   at `.github/workflows/<name>.md` plus a `runtime-import`-ed policy fragment
   at `.github/aw/<name>-policy.md`. Emits through `safe-outputs`
   (`upload-artifact`, `create-pull-request`, `push-to-pull-request-branch`,
   `add-labels`, `add-comment`, `noop`, depending on the workflow).

When both surfaces exist, they share the same rubric under
`.github/aw/shared/<name>-policy.md` so they cannot drift in policy. Keep
interactive-only references under `.agents/skills/<name>/references/` when the
gh aw workflow does not need to import them.

## Prerequisite

Install the `gh aw` extension once per workstation, pinned to the version this
repo's `.github/aw/actions-lock.json` is built against. The canonical pin and
install command live in [`.github/aw/README.md`](../../.github/aw/) →
"Pinning".

## File layout

```
.agents/skills/<name>/
├── SKILL.md                   # required — frontmatter + body
├── agents/
│   └── openai.yaml            # optional — Codex UI metadata and policy
├── references/                # optional — on-demand context for the agent
│   ├── CLASSIFICATION.md
│   ├── DOMAINS.md
│   └── TOOLS.md
└── assets/                    # optional — worked examples, fixtures
    └── examples.md

.claude/skills -> ../.agents/skills  # symlink, do not edit separately

.github/workflows/<name>.md    # optional — gh aw SOURCE (edit this)
.github/workflows/<name>.lock.yml   # compiled — `gh aw compile` regenerates
.github/workflows/agentics-maintenance.yml # generated when gh aw needs safe-output maintenance/replay
.github/aw/<name>-policy.md    # optional — gh-aw-mode-specific fragment,
                               # runtime-imported by the workflow
.github/aw/shared/<name>-policy.md  # optional — shared rubric loaded by
                                    # both the interactive skill and the
                                    # gh aw policy fragment
```

`.github/aw/actions-lock.json` and `.github/aw/logs/` are shared across all
skills — never per-skill.

## Adding a new skill — checklist

1. **Skill body.** Create `.agents/skills/<name>/SKILL.md` with at minimum
   `name` and `description` in the frontmatter (see the
   [Agent Skills spec](https://agentskills.io/specification)). Keep SKILL.md
   short; push detail into `references/`.

2. **References.** Move anything load-bearing but stable into
   `references/<TOPIC>.md`. The agent loads them on demand; they keep
   SKILL.md scannable.

   **If you build both an interactive surface and an unattended twin,**
   the shared policy must live under `.github/aw/shared/<name>-policy.md`,
   not inside `.agents/skills/<name>/references/`. gh aw's runtime-import
   security validation forbids importing files outside `.github/`. The
   interactive skill references the same file via its repo-root path; the
   gh aw policy fragment imports it via
   {{#runtime-import .github/aw/shared/\<name>-policy.md}}. See how the
   `sw-triage` skill wires it up for the exact pattern.

3. **Decide on the unattended path.** If the skill should also run in CI:
   create `.github/workflows/<name>.md` (gh aw frontmatter) plus
   `.github/aw/<name>-policy.md` (frontmatter-free fragment, runtime-imported
   by the workflow). Make the interactive skill explicit-only by adding
   `disable-model-invocation: true` to `SKILL.md` for Claude Code and
   `policy.allow_implicit_invocation: false` to `agents/openai.yaml` for Codex,
   then run `gh aw compile`. The mechanics — secrets remap, engine model pin,
   registration trick, output validation — live in
   [`.github/aw/README.md`](../../.github/aw/).

4. **Update the catalogue.** Add a row to `.agents/skills/README.md`
   describing the trigger phrases and the deliverable.

5. **Run it once.** `gh aw run <name> -f …` and inspect with
   `gh aw audit <run-id>`.

## Skill-specific conventions

* **CI twins are explicit-only in interactive sessions.** A skill with a
  GitHub Agentic Workflow twin must not auto-load from an ordinary conversation.
  Set `disable-model-invocation: true` in `SKILL.md` for Claude Code and
  `policy.allow_implicit_invocation: false` in `agents/openai.yaml` for Codex.
  Users can still invoke it deliberately as `/name` in Claude Code or `$name`
  in Codex.
* **Frontmatter `description` is matched against user messages** in the
  interactive surface unless automatic invocation is disabled. Be specific
  about trigger phrases for skills that may auto-load.
* **References load on demand.** Keep SKILL.md scannable; push lookups,
  taxonomies, and tool catalogues into `references/`.
* **Default to Sonnet; escalate with a reason.** gh aw workflows pin the
  concrete model version in their own `engine.model` frontmatter (the single
  source of truth) — the Sonnet tier by default (e.g. `sw-triage`, `sw-review`).
  Escalate only with a concrete reason, documented in the workflow source
  comment — currently `sw-bugfixer` (code-fixing runs) and the
  `security`/`architecture` personas of `sw-review` escalate to the Opus tier.
* **Inline sub-agents (`## agent:` blocks in a gh aw source) have three
  hard-won requirements** (see `sw-review.md` for the working pattern):
  * The frontmatter **must include `name:`** — Claude Code registers a
    sub-agent only via that field, not via the file name. Without it the
    orchestrator silently reviews inline and any per-agent `model:` pin
    (e.g. an Opus escalation) never applies.
  * **Restrict `tools:`** to what the worker needs (typically
    `Read, Grep, Glob, Bash`). Sub-agents otherwise inherit every tool,
    including safe-output MCP tools — a worker that publishes on its own can
    consume capped safe-output quotas meant for the orchestrator.
  * Workers **return their result as the final message**; only the
    orchestrator publishes. State this in both the worker prompt and the
    orchestrator prompt, and make dispatch mandatory ("you MUST dispatch via
    the `Task` tool; never review inline") — a soft "otherwise do it
    yourself" fallback reliably degrades into inline handling.

## Reference docs

* [`.github/aw/README.md`](../../.github/aw/) — gh aw setup,
  pinning, secrets, registration, output validation.
* [`.agents/skills/README.md`](../../.agents/skills/) — interactive
  skill catalogue.
* [`gh aw` Reference](https://github.github.com/gh-aw/) — upstream docs.
* [Agent Skills specification](https://agentskills.io/specification) — the
  SKILL.md frontmatter contract.

---

---
url: /docs/guides/plugins/plugins/storefront/templates/agentic-files.md
---

# Agentic Files

Agentic files are public sales-channel files that help AI assistants understand
how they should interact with a shop.

Shopware ships the `agentic` file family with these default files:

* [`/llms.txt`](https://llmstxt.org/): A concise entry point to public
  sales-channel resources.
* [`/agents.md`](https://agents.md/): Guidance for AI agents interacting with
  the shop.
* [`/.well-known/ai-catalog.json`](https://agenticresourcediscovery.org/spec/):
  An Agentic Resource Discovery catalog for machine-readable resources, such as
  the Store API MCP server for headless/API sales channels.

The files are generated from Twig templates and can be enabled per sales
channel in the Administration. Merchants can also add custom notes or override
individual content sources from the sales-channel detail page.

::: info
The core agentic files feature is available since Shopware 6.7.12.0. Older
Shopware versions can serve compatible `/llms.txt`, `/agents.md`, and
`/.well-known/ai-catalog.json` files through the Agentic Commerce plugin
fallback. See
[Agentic Commerce plugin compatibility](#agentic-commerce-plugin-compatibility)
for details.
:::

## Public paths

Templates are registered below `Resources/views/files/<file-family>/`.
Shopware derives the public path by removing the `files/<file-family>/` prefix and the `.twig` suffix.
The following table shows example mappings from template paths to public paths.

| Template path                                    | Public path                    |
|--------------------------------------------------|--------------------------------|
| `files/agentic/llms.txt.twig`                    | `/llms.txt`                    |
| `files/agentic/agents.md.twig`                   | `/agents.md`                   |
| `files/agentic/.well-known/ai-catalog.json.twig` | `/.well-known/ai-catalog.json` |

Files are served only for sales channels where the file is enabled. Disabled
files and unknown files behave like regular 404 responses.

## Extend default files

Plugins, apps, and themes can contribute to existing agentic files by shipping
templates at the same path. Use `sw_extends` with the unqualified template path
so the normal Shopware Twig inheritance chain can resolve the next template in
both core and compatibility modes.

When you use one of the dedicated extension blocks, always render
{{ parent() }}. This keeps multi inheritance intact when
several extensions contribute content to the same file.

::: code-group

```twig [PLUGIN_ROOT/src/Resources/views/files/agentic/llms.txt.twig]
{% sw_extends 'files/agentic/llms.txt.twig' %}

{% block agentic_llms_extensions %}
    {{ parent() }}

    ## My integration

    - [Integration profile](/.well-known/my-integration): Machine-readable
      capabilities for this sales channel.
{% endblock %}
```

```twig [PLUGIN_ROOT/src/Resources/views/files/agentic/agents.md.twig]
{% sw_extends 'files/agentic/agents.md.twig' %}

{% block agentic_agents_extensions %}
    {{ parent() }}

    ## My integration

    - Only use this integration when it is explicitly available for this sales
      channel.
    - Follow the user's explicit intent before performing state-changing
      actions.
{% endblock %}
```

```twig [PLUGIN_ROOT/src/Resources/views/files/agentic/.well-known/ai-catalog.json.twig]
{% sw_extends 'files/agentic/.well-known/ai-catalog.json.twig' %}

{% block agentic_ai_catalog_entries %}
    {% set entries = entries|merge([{
        identifier: 'urn:air:example.com:server:my-integration',
        displayName: 'My integration MCP server',
        type: 'application/mcp-server-card+json',
        url: salesChannelFileContext.myIntegrationMcpServerUrl,
        description: 'MCP server for my integration.',
        tags: ['integration', 'mcp'],
        capabilities: ['my-integration-capability'],
        representativeQueries: [
            'inspect available integration capabilities',
        ],
    }]) %}

    {{ parent() }}
{% endblock %}
```

:::

Prefer the dedicated extension blocks for additive content:

* `agentic_llms_extensions`
* `agentic_agents_extensions`
* `agentic_ai_catalog_entries`

## Add custom files

Extensions can also add new files by shipping new templates below
`Resources/views/files/<file-family>/`.

For example, a plugin can add `/my-integration.md` with this template path:

```text
PLUGIN_ROOT/src/Resources/views/files/agentic/my-integration.md.twig
```

::: warning
Every Twig file below `Resources/views/files/<file-family>/` is discovered as a
public sales-channel file. Put private partials or include templates outside
`Resources/views/files/**` and include them with an explicit Twig namespace,
for example `@MyPlugin/agentic/includes/content.md.twig`.
:::

Use the `agentic` file family when your file belongs to the public AI and agent
guidance surface. Use another file family only when the feature owns a separate
file group and matching Administration support.

Custom files should expose a `user_provided_content` block near the end of the
template. This allows the Administration to offer merchant custom notes without
requiring merchants to replace the whole template.

```twig
{% block my_integration_md %}
    # My integration

    This file explains how AI agents can use the custom public resource.

    {% block user_provided_content %}{% endblock %}
{% endblock %}
```

## Template variables

The following table lists the variables that agentic file templates receive.

| Variable                  | Description                                                                                                                          |
|---------------------------|--------------------------------------------------------------------------------------------------------------------------------------|
| `context`                 | The current sales-channel context                                                                                                    |
| `salesChannel`            | The sales channel, including languages and currencies needed by the default templates                                                |
| `salesChannelFile`        | Read-only metadata for the rendered file, such as file family, file name, template path, content type, and resolved template sources |
| `salesChannelFileContext` | Optional array context for file-specific data. For `/.well-known/ai-catalog.json`, core adds `baseUrl` and `publisher` when a sales-channel domain is available. For sales channels of type API (headless), core also adds `storeApiMcpServerUrl`, pointing at the [Store API MCP server](../../../../../products/tools/mcp-server/store-api.md). The default template only renders the catalog entry when both `storeApiMcpServerUrl` and `publisher` are set. |

Use normal Twig functions such as `path()` and `seoUrl()` to build links.

To add file-specific template context, subscribe to
`SalesChannelFileRenderParametersExtension::onPost()`:

```php
use Shopware\Core\System\SalesChannel\File\Discovery\SalesChannelFile;
use Shopware\Core\System\SalesChannel\File\Rendering\Extension\SalesChannelFileRenderParametersExtension;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

final class MyAgenticFileSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            SalesChannelFileRenderParametersExtension::onPost() => 'addContext',
        ];
    }

    public function addContext(SalesChannelFileRenderParametersExtension $extension): void
    {
        if ($extension->file->fileFamily !== SalesChannelFile::DEFAULT_FILE_FAMILY
            || $extension->file->fileName !== '.well-known/ai-catalog.json'
            || !\is_array($extension->result)
        ) {
            return;
        }

        $context = $extension->result['salesChannelFileContext'] ?? [];
        $context = \is_array($context) ? $context : [];
        $context['myIntegrationMcpServerUrl'] = '/.well-known/my-integration';

        $extension->result['salesChannelFileContext'] = $context;
    }
}
```

The extension result is the full Twig parameter array. Preserve existing keys
and add only the data needed for the concrete file you handle.

## Add Administration descriptions

The Administration can show a description for discovered files. Add snippets
with the predefined key pattern:

```json [PLUGIN_ROOT/src/Resources/app/administration/src/module/my-module/snippet/en-GB.json]
{
  "sw-sales-channel": {
    "detail": {
      "agenticFiles": {
        "descriptions": {
          "agentic": {
            "my-file.txt": "Explains how AI agents should use the custom public resource."
          }
        }
      }
    }
  }
}
```

If no snippet exists, the description stays empty.

## Agentic Commerce plugin compatibility

The [Agentic Commerce plugin](https://store.shopware.com/de/swag705756117823f/agentic-commerce-beta.html) is compatible with shops that already provide the
core agentic files feature and with older Shopware versions that do not.

When the core feature is available:

* Core handles discovery, Administration enablement, rendering, cache
  invalidation, and public serving.
* The plugin only contributes UCP sections through the templates
  `files/agentic/llms.txt.twig`, `files/agentic/agents.md.twig`, and
  `files/agentic/.well-known/ai-catalog.json.twig`.
* When UCP is activated for a sales channel, the plugin automatically enables
  `/llms.txt`, `/agents.md`, and `/.well-known/ai-catalog.json` for that sales
  channel.
* After a shop is upgraded to a Shopware version with the core feature, the
  plugin enables the files for sales channels that already have UCP configured.

When the core feature is not available:

* The plugin provides fallback routes for `GET /llms.txt`, `GET /agents.md`,
  and `GET /.well-known/ai-catalog.json`.
* Fallback files are served only for sales channels where UCP is active.
* The fallback mode does not backport the core Administration file-management UI,
  merchant template overrides, discovery API, or cache tagging.
* Third-party templates should still use unqualified `sw_extends`, for example
  `{% sw_extends 'files/agentic/llms.txt.twig' %}`. The same template then works
  when the shop later switches from plugin fallback mode to the core feature.

After an upgrade, clear the cache and rebuild the Storefront or Administration
assets as usual. The plugin then switches from fallback serving to
template-extension-only mode.

---

---
url: /docs/resources/references/adr/2026-05-28-agentic-files-for-sales-channels.md
---

# Agentic files for sales channels

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2026-05-28-agentic-files-for-sales-channels.md)
:::

## Context

Merchants need a way to expose agentic public files such as `llms.txt`, `AGENTS.md`, and metadata below `.well-known/` for each sales channel. These files should be generated from Shopware context, be customizable by merchants, and be extensible by core, plugins, apps, and themes.

The feature should reuse Shopware's established Twig extension model. Core should be able to ship base templates, and extensions should be able to overwrite or extend those templates through normal Twig behavior. We should not introduce an explicit provider interface because the existence of a template in a known location is enough to declare the file.

The merchant-facing configuration belongs to the sales channel detail module. Enablement, preview, public URL, and overrides are sales-channel specific and should not be stored in global system config.

## Decision

We introduce a generic sales-channel file backend. Agentic files are the first file family and are based on template discovery below:

```text
Resources/views/files/agentic/**.twig
```

The feature currently scopes itself to `files/agentic`. The `files` segment acts as a generic public-file template root, while `agentic` is the first supported file family. This leaves room to add other families later, for example `Resources/views/files/seo/robots.txt.twig`.

Terminology is important here: `agentic` and future values such as `seo` are file families. `Framework`, plugin names, app names, and theme names are Twig namespaces. Merchant overrides are keyed by Twig namespace, not by file family.

The relative path below `files/agentic` becomes the public path after removing the `.twig` suffix:

| Template path | Public path |
|---|---|
| `Resources/views/files/agentic/llms.txt.twig` | `/llms.txt` |
| `Resources/views/files/agentic/AGENTS.md.twig` | `/AGENTS.md` |
| `Resources/views/files/agentic/.well-known/ai-catalog.json.twig` | `/.well-known/ai-catalog.json` |
| `Resources/views/files/agentic/.well-known/ucp.json.twig` | `/.well-known/ucp.json` |

Subfolders are supported explicitly. Dot-prefixed folders such as `.well-known` are valid public path segments, so template discovery must include dot files and dot directories.

Discovery is intentionally split into two steps:

1. Catalogue registered file templates from Shopware's Twig template iterator.
2. Resolve the contributing Twig template chain for each catalogued file through the existing `TemplateFinder`.

This keeps file discovery aligned with the templates registered in the main Twig environment. The catalogue step determines which public files exist, while the chain resolution step follows the same namespace hierarchy Twig uses during rendering.

The catalogue step uses an explicit filtered template-iterator lookup for the `files/<family>` sub path and opts into dot paths for this use case. The default template iterator behavior remains aligned with Symfony and does not expose dot files unless a caller asks for them.

The content type is derived from the public file extension.

File-name lookup is case-insensitive. Templates whose paths differ only by case contribute to the same public file, which keeps legacy lowercase templates and persisted configuration compatible with the canonical uppercase `AGENTS.md` core template.

Merchant overrides are applied through an internal high-priority Twig loader that participates in the normal Twig loader chain. The loader does not read the database and does not infer state from the current request. Instead, the sales-channel file renderer activates the already loaded override templates for the duration of a single render. This keeps the existing Twig environment, extension set, inheritance behavior, and security configuration intact while allowing Administration previews to render unsaved override content.

The Administration adds an "Agentic files" tab to Storefront and Headless sales channel detail pages. The tab shows a list of discovered files. Selecting a file opens a detail page with rendered preview, enablement, public URL, detected content type, and a list of Twig namespaces that can be overridden individually. The UI stores only merchant overrides and does not copy shipped templates into the database.

The detail page offers two customization levels. Merchants can add simple append-only text through Custom Notes when the template chain exposes `user_provided_content`. Advanced users can open an individual content source and edit the override for that source directly. This keeps the common customization path non-technical while still making full source overrides available when needed.

Core also ships an Agentic Resource Discovery manifest at `files/agentic/.well-known/ai-catalog.json.twig`. It publishes a generated `ai-catalog.json` document; the dynamic ARD registry API is out of scope. When the MCP feature is active for a headless sales channel, the catalog includes the sales-channel-scoped Store API MCP server as an `application/mcp-server+json` entry with its built-in capability names.

Some templates need sales-channel-file-specific render data such as the public base URL, publisher host, or Store API MCP endpoint. This data is passed through a small associative `salesChannelFileContext` template variable. The existing `salesChannelFile` object stays unchanged because it is already exposed as the file metadata object in Twig.

## Template Examples

Core can ship a base template:

```twig
{# src/Core/Framework/Resources/views/files/agentic/llms.txt.twig #}

{% block agentic_llms_header %}
# {{ context.salesChannel.name }}
{% endblock %}

{% block agentic_llms_summary %}
This shop is powered by Shopware.
{% endblock %}

{% block agentic_llms_guidance %}
Agents may use the public storefront and documented APIs. Respect robots.txt, rate limits, and checkout boundaries.
{% endblock %}

{% block agentic_llms_extensions %}{% endblock %}

{% block user_provided_content %}{% endblock %}
```

Built-in text templates expose empty extension blocks such as `agentic_llms_extensions` and `agentic_agents_extensions` so extensions can append their own content without taking over the core-owned structure blocks. They also expose `user_provided_content`, which the Administration can fill with simple merchant notes through a generated override.

A UCP plugin can extend that template:

```twig
{# custom/plugins/Ucp/Resources/views/files/agentic/llms.txt.twig #}

{% sw_extends '@Framework/files/agentic/llms.txt.twig' %}

{% block agentic_llms_extensions %}
UCP clients may use the product discovery and cart capabilities exposed by this plugin.
{% endblock %}
```

The same plugin can introduce a nested `.well-known` file:

```twig
{# custom/plugins/Ucp/Resources/views/files/agentic/.well-known/ucp.json.twig #}
{
    "schema_version": "1",
    "name_for_model": "{{ context.salesChannel.name|e('js') }}",
    "description_for_model": "Shopware sales channel with UCP capabilities."
}
```

## Routing

Sales channel files are served by a core 404 subscriber on `KernelEvents::EXCEPTION`. The subscriber is intentionally a fallback: it only handles main-request `GET` and `HEAD` requests when normal routing already failed with an unresolved 404.

The public file handling is not an SEO URL and does not participate in SEO URL generation. It must support Storefront and Headless sales channel domains.

Existing explicit routes keep precedence. For example, `/robots.txt`, `/sitemap.xml`, and `/.well-known/change-password` continue to be handled by their dedicated controllers because the subscriber returns early as soon as the request already has a matched route.

The subscriber does not resolve a sales channel context itself. It uses the already-resolved `SalesChannelContext` request attribute and returns early when it is missing. That keeps the implementation independent from Storefront-specific context resolution and lets the active request scope decide whether the file can be served. The subscriber also does not set a hard-coded route scope; it keeps the route scope already resolved for the request.

When the request is eligible, the subscriber validates and normalizes the public path, maps it to the configured `files/agentic` template path, looks up the discovered file descriptor, checks the `sales_channel_file` row for the current sales channel, renders the resolved Twig template stack with merchant overrides, marks the response HTTP-cacheable, and returns it with the derived content type. It returns early for invalid paths, disabled files, and paths that do not resolve to a discovered file descriptor.

Responses are cacheable per sales channel, file family, and public file path. Runtime cache entries are tagged with the matching `sales_channel_file.id` and invalidated through that row-specific tag when the row changes. Discovery and shipped-template changes are code changes and are expected to be deployed with a full cache clear, so no global sales-channel-file cache tag is needed.

## Path Safety

The public path is validated before discovery lookup, database lookup, or Twig rendering. Request input must never be concatenated directly into a Twig template name.

Validation rejects:

* empty paths
* absolute paths
* paths ending with `/`
* empty path segments
* `.` segments
* `..` segments
* backslashes
* NUL bytes
* paths without a file extension
* path segments containing characters outside the allowed segment character set

Dot-prefixed normal segments such as `.well-known` are allowed. The request path is decoded once by the HTTP stack; the resolver must not double-decode encoded input.

The rendering flow is:

```text
request path -> normalize and validate -> discovered descriptor lookup -> load stored overrides -> activate overrides for render -> render descriptor template name
```

This keeps traversal protection in the shared resolver/controller boundary while avoiding template-name construction from raw request input.

## Storage

Sales-channel specific state is stored in a dedicated table:

```text
sales_channel_file
```

The table contains one row per sales channel, file family, and public file:

* `id`
* `sales_channel_id`
* `file_family`
* `file_name`
* `enabled`
* `template_overrides`
* `created_at`
* `updated_at`

`file_name` stores the normalized public file path without a leading slash, for example `llms.txt` or `.well-known/ucp.json`.

`file_family` stores the file family below `Resources/views/files`, for example `agentic`.

`template_overrides` is a JSON object keyed by Twig namespace. The value is the merchant-provided override for that Twig namespace:

```json
{
    "Framework": "{% block agentic_llms_extensions %}...{% endblock %}",
    "Ucp": "{% block agentic_llms_extensions %}...{% endblock %}"
}
```

The reserved `user_provided_content` key stores plain merchant notes. During rendering, it is converted into a generated Twig override for the `user_provided_content` block instead of exposing Twig editing for simple append-only additions.

Resetting an individual source override removes the matching Twig namespace key from `template_overrides`. It never writes the currently shipped template content into the database, so later core or extension template changes become visible again after the reset.

Only overrides are stored in the database. Base templates remain in core, plugin, app, or theme template storage. When a shipped template changes, there is no need to update database rows with a migration.

The Twig override loader is deliberately not a database loader. Persisted overrides are loaded by the sales-channel file application service before rendering, and preview overrides can be supplied directly by the Administration request. This avoids making the global Twig loader depend on sales-channel request state and prevents one sales channel's override from being selected for another sales channel that renders the same Twig template name.

Initial built-in files are opt-in per sales channel. Switching a file from opt-in to opt-out later can be done with a simple migration on a per-file basis.

## Public API and Extension Point

The public API surface should be intentionally small. Only the documented HTTP behavior becomes part of the backward compatibility promise once the feature is released. All PHP services, DAL entities, database tables, generated entity endpoints, template context objects, and implementation details are internal unless they are separately documented as public API.

### Administration HTTP API

The Administration needs an HTTP API to list discovered files and preview unsaved overrides. The HTTP route contract is public, while the PHP controller class remains internal implementation.

* `GET /api/_action/sales-channel-file/{fileFamily}/{salesChannelId}`
* `GET /api/_action/sales-channel-file/{fileFamily}/{salesChannelId}/detail?fileName=<fileName>`
* `POST /api/_action/sales-channel-file/{fileFamily}/{salesChannelId}/preview`

The detail route accepts `fileName` as a query parameter because public file paths can include subfolders such as `.well-known/ucp.json`; this avoids a greedy wildcard route segment for arbitrary file paths. The list response is intentionally lightweight and does not include resolved Twig templates or template source content. The detail response includes resolved template names and the current source template content so the Administration can render the content sources table and prefill the advanced override editor without persisting shipped templates. The exact response shape is documented in the OpenAPI schema.

### Public File HTTP API

* Eligible agentic files are served on sales channel domains by their derived public path, for example `/llms.txt`, `/AGENTS.md`, or `/.well-known/ucp.json`.
* Existing explicit routes keep precedence because the file serving runs only as an unresolved 404 fallback.
* Only `GET` and `HEAD` requests are eligible.
* Disabled files, files without a matching `sales_channel_file` row, invalid paths, and undiscovered files behave like normal 404s.
* The response content type is derived from the public file extension and includes UTF-8 charset.

### Designed Extension Point

Public file template files are the designed extension point for template content. Core, plugins, apps, and themes can ship templates below `Resources/views/files/<file-family>/**/*.twig` and use normal Shopware Twig inheritance through Twig namespaces.

The initial extension point is the `agentic` file family with the built-in file paths `files/agentic/llms.txt.twig`, `files/agentic/AGENTS.md.twig`, and `files/agentic/.well-known/ai-catalog.json.twig`. Subfolders below the file family are supported, including dot-prefixed folders such as `.well-known`.

The exact default text shipped by core is not part of the BC promise and may evolve. Core-owned structure blocks in public file templates may exist to keep templates readable, but extensions should prefer the explicit built-in extension blocks `agentic_llms_extensions` and `agentic_agents_extensions` for additive content. Templates can expose `user_provided_content` when they want the Administration to offer a simple "Custom Notes" field that appends merchant-provided text.

Additional Twig parameters can be added through `SalesChannelFileRenderParametersExtension::onPost()`. Subscribers receive the concrete file, sales channel context, and loaded sales channel, so costly data can be added only for the files that need it.

Administration components, services, and Administration Twig templates for this feature are private implementation. They are not designed extension points, are not part of the BC promise, and intentionally do not expose Administration Twig blocks for extension.

## Consequences

Extension authors can add agentic files by shipping Twig templates in a predictable location. They can also extend core templates through standard Twig inheritance instead of registering a provider service.

Merchant customizations are isolated per sales channel and per file. Because the database stores only overrides, deployed template changes remain effective immediately unless a merchant explicitly overrides the affected Twig namespace.

The implementation must ensure template discovery includes dot files and dot directories. App template loading must also allow the `files` template root if apps should ship these templates.

The generic `files/<family>` template structure gives us a path to support other public file families later, such as SEO files.

## Alternatives Considered

### Store overrides in system config

System config would be easy to expose in Administration settings, but it is a poor fit for per-file, sales-channel scoped state and for cache invalidation. A dedicated table gives clearer ownership.

### Store one override row per Twig namespace

A normalized one-row-per-Twig-namespace model would make individual overrides addressable, but rendering and the detail page always need all overrides for a sales channel file. Storing the overrides as one JSON object keeps the read model simple.

### Add a provider interface

A provider interface would make file registration explicit, but it would duplicate information already encoded by the template path. Template discovery keeps the extension point smaller and closer to Shopware's existing Twig model.

### Put the UI in global settings

Global settings would hide the sales-channel specific nature of enablement, public URL, preview, and overrides. The sales channel detail module is the better fit.

## Future Improvements

The model can be extended so merchants can create new public files themselves without core or an extension first shipping a template.

Additional file families can be introduced below `Resources/views/files/*`, for example `files/seo`, while reusing the same validation, routing, storage, and override concepts.

---

---
url: /docs/AGENTS.md
---
# AGENTS.md

This file provides guidance to coding agents like CursorAI or Claude Code.

## Repository Overview

This is the **Shopware Developer Documentation** repository (`shopware/docs`) that contains comprehensive developer documentation for Shopware 6, served at [developer.shopware.com/docs](https://developer.shopware.com/docs/). The documentation is integrated with the main [developer portal](https://github.com/shopware/developer-portal) repository.

> **Note:**
> This documentation covers **Shopware 6** and is intended for use with the [shopware/shopware](https://github.com/shopware/shopware) open-source e-commerce framework.
>
> For contributing to or understanding Shopware core, see the [shopware/shopware GitHub repository](https://github.com/shopware/shopware) for source code and core platform issues.

## Documentation Structure

The repository follows a 4-tier hierarchical organization:

* **`/concepts/`** - High-level architectural concepts (API, commerce, extensions, framework)
* **`/guides/`** - Step-by-step tutorials (hosting, installation, integrations, plugins)
* **`/products/`** - Product-specific documentation (CLI, PaaS, extensions, Digital Sales Rooms)
* **`/resources/`** - References, guidelines, ADRs, and tooling documentation

## Common Development Commands

### Documentation Development

```bash
# Setup developer portal environment
pnpm run docs:env

# Link documentation content to developer portal
pnpm run docs:link

# Preview documentation locally
pnpm run docs:preview
```

### Quality Control

```bash
# Run spellcheck via docker
make spellcheck-local

# Run spellcheck with installed sources (aspell and pyspelling)
make spellcheck

# Auto-fix markdown issues (be aware that it can only fix certain issues)
make fix

# Sort spellcheck wordlist
LC_ALL=C sort .wordlist.txt -o .wordlist.txt
```

## Key Architecture Patterns

### Dual Repository System

* **Content Repository**: `shopware/docs` (this repo) - contains all Markdown content
* **Presentation Layer**: `shopware/developer-portal` - handles building and serving
* **Integration**: Content is linked via symlinks using `docs-cli.cjs`

### Automated Content Synchronization

Critical content auto-syncs from main `shopware/shopware` repository every 3 hours:

* `/adr/*.md` → `/resources/references/adr/*.md` (Architecture Decision Records)
* `/adr/assets/*` → `/assets/adr/*` (ADR assets)
* `/coding-guidelines/core` → `/resources/guidelines/code/core` (Coding standards)

### Extension Documentation Architecture

* **Apps**: Server-based external integrations with JWT validation, SDK integration
* **Plugins**: Internal Shopware core extensions with DAL, services, events
* **Themes**: Asset management, SCSS variables, inheritance system

## Quality Assurance Workflows

The repository has extensive automated quality control:

* **Markdown linting**: Validates formatting and style consistency
* **Spell checking**: Uses custom wordlist (`.wordlist.txt`) with pyspelling
* **Grammar checking**: Reviewdog integration for language validation
* **External link validation**: Lychee tool checks for broken links
* **Asset naming validation**: Enforces strict naming conventions
* **PageRef validation**: A custom Deno script checks internal cross-references

## Development Environment

* **Node.js**: 18.x with pnpm package manager
* **Nix**: Uses `devenv.nix` for consistent development environments
* **Build System**: VitePress managed through the developer portal
* **CI/CD**: 11+ GitHub Actions workflows for quality control and synchronization

## File Conventions

### Markdown Style

* Configuration in `markdown-style-config.yml`
* 40+ linting rules enabled
* Consistent formatting enforced via CI/CD

### Asset Management

* All assets in `/assets/` directory
* Strict naming conventions are enforced
* Images, diagrams, and media files (40,000+ characters worth)
* Extensive use of Mermaid diagrams, SVGs, and screenshots

### Code Snippets

* Reusable examples in `/snippets/` directory
* Multi-format support (PHP, JavaScript, Vue, Twig, XML, YAML, JSON)
* Configuration examples for apps, plugins, and system setup

## Cross-linking System

* Uses PageRef components for consistent internal linking
* Hierarchical navigation with clear parent-child relationships
* Context-aware references between Concepts ↔ Guides

## Version Management

* Branch-based versioning (`main`, `v6.5`, `v6.4`)
* Feature flag documentation for experimental features
* Clear deprecation notices and upgrade paths
* Automated format migration (Gitbook → VitePress)

## Redirects

`.gitbook.yaml` is used to manage redirects from old URLs to new ones, ensuring users find the correct content even after structural changes.

This can be done by the following prompt:

```shell
Check the current branch against main. There should be two files to be moved. Create a redirect in the `.gitbook.yaml` in the pattern that already exists.
```

## Do's and Don'ts for AI agents

### Do's

* **Follow repository conventions**: Adhere to the existing documentation structure, markdown style rules, and asset naming conventions.
* **Respect synced content**: When changes are needed in synced areas (`/resources/references/adr/`, `/assets/adr/`, `/resources/guidelines/code/core/`), propose edits against the `shopware/shopware` repository instead of changing them here.
* **Keep redirects consistent**: When pages are moved or removed, compare your branch against `main`, identify changed paths, and add redirects to `.gitbook.yaml` following the existing patterns.
* **Use quality checks when appropriate**: Run `make lint`, `make fix`, or the configured spellcheck tasks when you make non-trivial documentation changes, especially if CI feedback suggests issues.
* **Prefer incremental, focused changes**: Keep pull requests small and well-scoped so they are easy to review and reason about.

### Don't

* **Don't edit synced files directly**: Avoid modifying files that are automatically synchronized from `shopware/shopware`, as those changes will be overwritten.
* **Don't break existing URLs**: Avoid renaming or moving pages without adding a corresponding redirect entry in `.gitbook.yaml`.
* **Don't bypass style and spelling rules**: Do not introduce Markdown formatting that conflicts with `markdown-style-config.yml`, or ignore repeated spelling issues that should be added to `.wordlist.txt`.
* **Don't change repository tooling lightly**: Avoid editing CI workflows, configuration files, or build tooling unless explicitly requested, and always keep changes minimal and well-documented.
* **Don't mix unrelated changes**: Do not bundle large, unrelated modifications (for example, structural moves plus extensive content rewrites) into a single change set.

---

---
url: >-
  /docs/guides/development/troubleshooting/dal-reference/aggregations-reference.md
---

# Aggregations Reference

Aggregations allow you to determine further information about the overall result in addition to the actual search results. These include totals, unique values, or the average of a field.

The DAL knows two types of aggregations:

* `metric` aggregation - This type of aggregation applies a mathematical formula to a field. A metric aggregation always has a calculated result. These are aggregations to calculate sums or maximum values.
* `bucket` aggregation - With this type of aggregation, a list of keys is determined. Further aggregations can then be determined for each key.

| Name | Type | Description |
| :--- | :--- | :--- |
| avg | metric | Average of all numeric values for the specified field |
| count | metric | Number of records for the specified field |
| max | metric | Maximum value for the specified field |
| min | metric | Minimal value for the specified field |
| stats | metric | Stats overall numeric values for the specified field |
| sum | metric | Sum of all numeric values for the specified field |
| entity | bucket | Groups the result for each value of the provided field and fetches the entities for this field |
| filter | bucket | Allows to filter the aggregation result |
| terms | bucket | Groups the result for each value of the provided field and fetches the count of affected documents |
| histogram | bucket | Groups the result for each value of the provided field and fetches the count of affected documents. Although allows to provide date interval (day, month, ...) |
| range | bucket | Groups the result for each defined set of ranges into each bucket - bucket of numerical data and a count of items/documents for each bucket |

## Avg aggregation

The `Avg` aggregation calculates the average value for a field. The following SQL statement is executed in the background: `AVG(price)`.

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new AvgAggregation('avg-price', 'price')
);

$result = $repository->search($criteria, $context);

/** @var AvgResult $aggregation */
$aggregation = $result->getAggregations()->get('avg-price');

$aggregation->getAvg();
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
 },
    "aggregations": [
 {  
            "name": "avg-price",
            "type": "avg",
            "field": "price"
 }
 ]
}
```

Response

```json
{
    "total": 1,
    "data": [
 {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
 }
 ],
    "aggregations": {
        "avg-price": {
            "avg": 505.73333333333335,
            "extensions": []
 }
 }
}
```

## Count aggregation

The `count` aggregation allows you to determine the number of entries in a field that contain a value. The following SQL statement is executed in the background: `COUNT(DISTINCT(manufacturerId))`.

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new CountAggregation('count-manufacturers', 'manufacturerId')
);

$result = $repository->search($criteria, $context);

/** @var CountResult $aggregation */
$aggregation = $result->getAggregations()->get('count-manufacturers');

$aggregation->getCount();
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
 },
    "aggregations": [
 {  
            "name": "count-manufacturers",
            "type": "count",
            "field": "manufacturerId"
 }
 ]
}
```

Response

```json
{
    "total": 1,
    "data": [
 {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
 }
 ],
    "aggregations": {
        "count-manufacturers": {
            "count": 44,
            "extensions": []
 }
 }
}
```

## Max aggregation

The `max` aggregation returns the maximum value of a field. The following SQL statement is executed in the background: `MAX(price)`.

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new MaxAggregation('max-price', 'price')
);

$result = $repository->search($criteria, $context);

/** @var MaxResult $aggregation */
$aggregation = $result->getAggregations()->get('max-price');

$aggregation->getMax();
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
 },
    "aggregations": [
 {  
            "name": "max-price",
            "type": "max",
            "field": "price"
 }
 ]
}
```

Response

```json
{
    "total": 1,
    "data": [
 {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
 }
 ],
    "aggregations": {
        "max-price": {
            "max": "979",
            "extensions": []
 }
 }
}
```

## Min aggregation

The `min` aggregation returns the minimum value of a field. The following SQL statement is executed in the background: `MIN(price)`.

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new MinAggregation('min-price', 'price')
);

$result = $repository->search($criteria, $context);

/** @var MinResult $aggregation */
$aggregation = $result->getAggregations()->get('min-price');

$aggregation->getMin();
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
 },
    "aggregations": [
 {  
            "name": "min-price",
            "type": "min",
            "field": "price"
 }
 ]
}
```

Response

```json
{
    "total": 1,
    "data": [
 {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
 }
 ],
    "aggregations": {
        "min-price": {
            "min": "5",
            "extensions": []
 }
 }
}
```

## Sum aggregation

The `sum` aggregation allows you to compute the total of a field. The following SQL statement is executed in the background: `SUM(price)`.

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new SumAggregation('sum-price', 'price')
);

$result = $repository->search($criteria, $context);

/** @var SumResult $aggregation */
$aggregation = $result->getAggregations()->get('sum-price');

$aggregation->getSum();
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
 },
    "aggregations": [
 {  
            "name": "sum-price",
            "type": "sum",
            "field": "price"
 }
 ]
}
```

Response

```json
{
    "total": 1,
    "data": [
 {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
 }
 ],
    "aggregations": {
        "sum-price": {
            "sum": 30344,
            "extensions": []
 }
 }
}
```

## Stats aggregation

The `stats` aggregation allows you to calculate multiple values for a field at once. This includes the previous `max`, `min`, `avg`, and `sum` aggregations. The following SQL statement is executed in the background: `SELECT MAX(price), MIN(price), AVG(price), SUM(price)`.

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new StatsAggregation('stats-price', 'price')
);

$result = $repository->search($criteria, $context);

/** @var StatsResult $aggregation */
$aggregation = $result->getAggregations()->get('stats-price');

$aggregation->getSum();
$aggregation->getMax();
$aggregation->getAvg();
$aggregation->getMin();
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
 },
    "aggregations": [
 {  
            "name": "stats-price",
            "type": "stats",
            "field": "price"
 }
 ]
}
```

Response

```json
{
    "total": 1,
    "data": [
 {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
 }
 ],
    "aggregations": {
        "stats-price": {
            "min": "5",
            "max": "979",
            "avg": 505.73333333333335,
            "sum": 30344,
            "extensions": []
 }
 }
}
```

## Terms aggregation

The `terms` aggregation belongs to the bucket aggregations. This allows you to determine the values of a field. The result contains each value once, along with how often it occurs. The `terms` aggregation also supports the following parameters:

* `limit` - Defines a maximum number of entries to be returned (default: zero)
* `sort` - Defines the order of the entries. By default, the following is not sorted
* `aggregation` - Enables you to calculate further aggregations for each key

The following SQL statement is executed in the background: `SELECT DISTINCT(manufacturerId) as key, COUNT(manufacturerId) as count`.

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new TermsAggregation(
        'manufacturer-ids',
        'manufacturerId',
        10,
        new FieldSorting('manufacturer.name', FieldSorting::DESCENDING)
    )
);

$result = $repository->search($criteria, $context);

/** @var TermsResult $aggregation */
$aggregation = $result->getAggregations()->get('manufacturer-ids');

foreach ($aggregation->getBuckets() as $bucket) {
    $bucket->getKey();
    $bucket->getCount();
}
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
 },
    "aggregations": [
 {
            "name": "manufacturer-ids",
            "type": "terms",
            "limit": 3,
            "sort": { "field": "manufacturer.name", "order": "DESC" },
            "field": "manufacturerId"
 }
 ]
}
```

Response

```json
{
    "total": 1,
    "data": [
 {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
 }
 ],
    "aggregations": {
        "manufacturer-ids": {
            "buckets": [
 {
                    "key": "7af1534f96604744a4bc16e713550107",
                    "count": 1,
                    "extensions": []
 },
 {
                    "key": "32d5c55f960b409ab209fe25c88a6676",
                    "count": 1,
                    "extensions": []
 },
 {
                    "key": "935ceec182714a8da48227d4772628a4",
                    "count": 1,
                    "extensions": []
 }
 ],
            "extensions": []
 }
 }
}
```

## Filter aggregation

The `filter` aggregation belongs to the bucket aggregations. Unlike all other aggregations, this one does not produce a result. It can't be used alone. It is used only further to restrict the result of an aggregation in a criterion. Filters defined inside the `filter` property of this aggregation type are only used when calculating this aggregation. The filters have no effect on other aggregations or on the search results.

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new FilterAggregation(
        'active-price-avg',
        new AvgAggregation('avg-price', 'price'),
        [
            new EqualsFilter('active', true)
        ]
    )
);

$result = $repository->search($criteria, $context);

/** @var AvgResult $aggregation */
$aggregation = $result->getAggregations()->get('avg-price');

$aggregation->getAvg();
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
 },
    "aggregations": [
 {
            "name": "active-price-avg",
            "type": "filter",
            "filter": [
 { 
                    "type": "equals", 
                    "field": "active", 
                    "value": true
 }
 ],
            "aggregation": {  
                "name": "avg-price",
                "type": "avg",
                "field": "price"
 }
 }
 ]
}
```

Response

```json
{
    "total": 1,
    "data": [
 {
            "name": "Awesome Granite HelpingHand",
            "id": "000bba26e2044b98a3ee4a84b03f9551",
            "apiAlias": "product"
 }
 ],
    "aggregations": {
        "avg-price": {
            "avg": 517.5898195488719,
            "extensions": []
 }
 }
}
```

## Entity aggregation

The `entity` aggregation is similar to the `terms` aggregation. It belongs to the bucket aggregations. As with `terms` aggregation, all unique values are determined for a field. The aggregation then uses the determined keys to load the defined entity. The keys are used here as IDs.

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new EntityAggregation('manufacturers', 'manufacturerId', 'product_manufacturer')
);

$result = $repository->search($criteria, $context);

/** @var EntityResult $aggregation */
$aggregation = $result->getAggregations()->get('manufacturers');

/** @var ProductManufacturerEntity $entity */
foreach ($aggregation->getEntities() as $entity) {
    $entity->getName();
}
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"],
        "product_manufacturer": ["id", "name"]
 },
    "aggregations": [
 {
            "name": "manufacturers",
            "type": "entity",
            "definition": "product_manufacturer",
            "field": "manufacturerId"
 }
 ]
}
```

Response

```json
{
    "total": 1,
    "data": [
 {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
 }
 ],
    "aggregations": {
        "manufacturers": {
            "entities": [
 {
                    "name": "Kris, Thiel and Tillman",
                    "id": "0055fe4c16ac4d34a57b460d225682cb",
                    "apiAlias": "product_manufacturer"
 },
 {
                    "name": "Beier Group",
                    "id": "073e354c7a854287ac8c084cd70ebf90",
                    "apiAlias": "product_manufacturer"
 }
 ],
            "apiAlias": "manufacturers_aggregation"
 }
 }
}
```

## Histogram aggregation

The histogram aggregation is used as soon as the data to be determined refers to a date field. For histogram aggregation, one of the following date intervals can be specified: `minute`, `hour`, `day`, `week`, `month`, `quarter`, `year`, `day`. This interval groups the results and calculates the corresponding count of hits.

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new DateHistogramAggregation(
        'release-dates',
        'releaseDate',
        DateHistogramAggregation::PER_MONTH
    )
);

$result = $repository->search($criteria, $context);

/** @var DateHistogramResult $aggregation */
$aggregation = $result->getAggregations()->get('release-dates');

foreach ($aggregation->getBuckets() as $bucket) {
    $bucket->getKey();
    $bucket->getCount();
}
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
 },
    "aggregations": [
 {
            "name": "release-dates",
            "type": "histogram",
            "field": "releaseDate",
            "interval": "month"
 }
 ]
}
```

Response

```json
{
    "total": 1,
    "data": [
 {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
 }
 ],
    "aggregations": {
        "release-dates": {
            "buckets": [
 {
                    "key": "2020-04-01 00:00:00",
                    "count": 50,
                    "extensions": []
 },
 {
                    "key": "2020-03-01 00:00:00",
                    "count": 4,
                    "extensions": []
 },
 {
                    "key": "2020-04-01 00:00:00",
                    "count": 6,
                    "extensions": []
 }
 ],
            "apiAlias": "release-dates_aggregation"
 }
 }
}
```

## Range aggregations

Allows for aggregation of data on a predefined range of values for more flexibility in the DAL - for example, it provides faceted filters on a predefined range.

* `from` will be compared with greater than or equal to
* `to` will be compared with lower than

```php
$criteria = new Criteria();
$criteria->addAggregation(
    new RangeAggregation(
        'price_ranges', 
        'products.price',
        [
            ['to' => 100],
            ['from' => 100, 'to' => 200],
            ['from' => 200]
        ]
    )
);

$result = $repository->search($criteria, $context);

/** @var RangeResult $aggregation */
$aggregation = $result->getAggregations()->get('price_ranges');

foreach ($aggregation->getRanges() as $key => $docCount) {
    // ...
}
```

```json
{
    ...
    "aggregations": {
        "price_ranges": {
            "range": {
                "field": "products.price",
                    "ranges": [
 { "to": 100.0 },
 { "from": 100.0, "to": 200.0 },
 { "from": 200.0 }
 ]
 }
 }
 }
}
```

Response

```json
{
    ...
    "aggregations": {
        "price_ranges": {
            "buckets": [
 {
                    "key": "*-100.0",
                    "to": 100.0,
                    "doc_count": 2
 },
 {
                    "key": "100.0-200.0",
                    "from": 100.0,
                    "to": 200.0,
                    "doc_count": 2
 },
 {
                    "key": "200.0-*",
                    "from": 200.0,
                    "doc_count": 3
 }
 ]
 }
 }
}
```

## Nesting aggregations

A metric aggregation calculates the value for a specific field. This can be a total or, for example, a minimum or maximum value of the field. Bucket aggregations are different. This determines how often a value occurs in a search result and returns the count along with it. The special thing about bucket aggregation is that it can contain further aggregations. This allows the API to perform complex queries, like, for example:

* Calculate the number of manufacturers per category that have a price over 500 euros. \*

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new FilterAggregation(
        'my-filter',
        new TermsAggregation(
            'per-category',
            'categories.id',
 null,
 null,
            new TermsAggregation(
                'manufacturer-ids',
                'manufacturerId'
            )
        ),
        [
            new RangeFilter('price', ['gte' => 500])
        ]
    )
);

$result = $repository->search($criteria, $context);

/** @var TermsResult $aggregation */
$aggregation = $result->getAggregations()->get('per-category');

foreach ($aggregation->getBuckets() as $bucket) {
    $categoryId = $bucket->getKey();

    /** @var TermsResult $manufacturers */
    $manufacturers = $bucket->getResult();

    foreach ($manufacturers->getBuckets() as $nestedBucket) {
        $manufacturerId = $nestedBucket->getKey();
    }
}
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
 },
    "aggregations": [
 {
            "name": "my-filter",
            "type": "filter",
            "filter": [
 { 
                    "type": "range", 
                    "field": "price", 
                    "parameters": {
                        "gte": 500
 }
 }
 ],
            "aggregation": {  
                "name": "per-category",
                "type": "terms",
                "field": "categories.id",
                "aggregation": {
                    "name": "manufacturer-ids",
                    "type": "terms", 
                    "field": "manufacturerId"
 }
 }
 }
 ]
}
```

Response

```json
{
    "total": 1,
    "data": [
 {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
 }
 ],
    "aggregations": {
        "per-category": {
            "buckets": [
 {
                    "key": "25fb912226fa48c2a5c9f4788f1f552d",
                    "count": 1,
                    "extensions": [],
                    "manufacturer-ids": {
                        "buckets": [
 {
                                "key": "715901f2b5864181a777d1a1b912d9a2",
                                "count": 1,
                                "extensions": []
 }
 ],
                        "extensions": []
 }
 },
 {
                    "key": "59b38c960597446e8c7bb76593ff7043",
                    "count": 2,
                    "extensions": [],
                    "manufacturer-ids": {
                        "buckets": [
 {
                                "key": "98e53a711d8549059325da044da2951d",
                                "count": 1,
                                "extensions": []
 },
 {
                                "key": "ee8b37324c5a4c32962367146be4d7b4",
                                "count": 1,
                                "extensions": []
 }
 ],
                        "extensions": []
 }
 }
 ],
            "apiAlias": "per-category_aggregation"
 }
 }
}
```

---

---
url: >-
  /docs/v6.5/resources/references/core-reference/dal-reference/aggregations-reference.md
---

# Aggregations Reference

Aggregations allow you to determine further information about the overall result in addition to the actual search results. These include totals, unique values, or the average of a field.

The DAL knows two types of aggregations:

* `metric` aggregation - This type of aggregation applies a mathematical formula to a field. A metric aggregation always has a calculated result. These are aggregations to calculate sums or maximum values.
* `bucket` aggregation - With this type of aggregation, a list of keys is determined. Further aggregations can then be determined for each key.

| Name | Type | Description |
| :--- | :--- | :--- |
| avg | metric | Average of all numeric values for the specified field |
| count | metric | Number of records for the specified field |
| max | metric | Maximum value for the specified field |
| min | metric | Minimal value for the specified field |
| stats | metric | Stats overall numeric values for the specified field |
| sum | metric | Sum of all numeric values for the specified field |
| entity | bucket | Groups the result for each value of the provided field and fetches the entities for this field |
| filter | bucket | Allows to filter the aggregation result |
| terms | bucket | Groups the result for each value of the provided field and fetches the count of affected documents |
| histogram | bucket | Groups the result for each value of the provided field and fetches the count of affected documents. Although allows to provide date interval (day, month, ...) |
| range | bucket | Groups the result for each defined set of ranges into each bucket - bucket of numerical data and a count of items/documents for each bucket |

## Avg aggregation

The `Avg` aggregation makes it possible to calculate the average value for a field. The following SQL statement is executed in the background: `AVG(price)`.

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new AvgAggregation('avg-price', 'price')
);

$result = $repository->search($criteria, $context);

/** @var AvgResult $aggregation */
$aggregation = $result->getAggregations()->get('avg-price');

$aggregation->getAvg();
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
    },
    "aggregations": [
        {  
            "name": "avg-price",
            "type": "avg",
            "field": "price"
        }
    ]
}
```

Response

```json
{
    "total": 1,
    "data": [
        {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
        }
    ],
    "aggregations": {
        "avg-price": {
            "avg": 505.73333333333335,
            "extensions": []
        }
    }
}
```

## Count aggregation

The `count` aggregation makes it possible to determine the number of entries for a field that are filled with a value. The following SQL statement is executed in the background: `COUNT(DISTINCT(manufacturerId))`.

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new CountAggregation('count-manufacturers', 'manufacturerId')
);

$result = $repository->search($criteria, $context);

/** @var CountResult $aggregation */
$aggregation = $result->getAggregations()->get('count-manufacturers');

$aggregation->getCount();
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
    },
    "aggregations": [
        {  
            "name": "count-manufacturers",
            "type": "count",
            "field": "manufacturerId"
        }
    ]
}
```

Response

```json
{
    "total": 1,
    "data": [
        {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
        }
    ],
    "aggregations": {
        "count-manufacturers": {
            "count": 44,
            "extensions": []
        }
    }
}
```

## Max aggregation

The `max` aggregation allows you to determine the maximum value of a field. The following SQL statement is executed in the background: `MAX(price)`.

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new MaxAggregation('max-price', 'price')
);

$result = $repository->search($criteria, $context);

/** @var MaxResult $aggregation */
$aggregation = $result->getAggregations()->get('max-price');

$aggregation->getMax();
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
    },
    "aggregations": [
        {  
            "name": "max-price",
            "type": "max",
            "field": "price"
        }
    ]
}
```

Response

```json
{
    "total": 1,
    "data": [
        {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
        }
    ],
    "aggregations": {
        "max-price": {
            "max": "979",
            "extensions": []
        }
    }
}
```

## Min aggregation

The `min` aggregation makes it possible to determine the minimum value of a field. The following SQL statement is executed in the background: `MIN(price)`

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new MinAggregation('min-price', 'price')
);

$result = $repository->search($criteria, $context);

/** @var MinResult $aggregation */
$aggregation = $result->getAggregations()->get('min-price');

$aggregation->getMin();
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
    },
    "aggregations": [
        {  
            "name": "min-price",
            "type": "min",
            "field": "price"
        }
    ]
}
```

Response

```json
{
    "total": 1,
    "data": [
        {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
        }
    ],
    "aggregations": {
        "min-price": {
            "min": "5",
            "extensions": []
        }
    }
}
```

## Sum aggregation

The `sum` aggregation makes it possible to determine the total of a field. The following SQL statement is executed in the background: `SUM(price)`.[PHP](https://docs.shopware.com/en/shopware-platform-dev-en/references-internals/core/dal?category=shopware-platform-dev-en/references-internals/core#)[API](https://docs.shopware.com/en/shopware-platform-dev-en/references-internals/core/dal?category=shopware-platform-dev-en/references-internals/core#)

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new SumAggregation('sum-price', 'price')
);

$result = $repository->search($criteria, $context);

/** @var SumResult $aggregation */
$aggregation = $result->getAggregations()->get('sum-price');

$aggregation->getSum();
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
    },
    "aggregations": [
        {  
            "name": "sum-price",
            "type": "sum",
            "field": "price"
        }
    ]
}
```

Response

```json
{
    "total": 1,
    "data": [
        {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
        }
    ],
    "aggregations": {
        "sum-price": {
            "sum": 30344,
            "extensions": []
        }
    }
}
```

## Stats aggregation

The `stats` aggregation makes it possible to calculate several values at once for a field. This includes the previous `max`, `min`, `avg` and `sum` aggregation. The following SQL statement is executed in the background: `SELECT MAX(price), MIN(price), AVG(price), SUM(price)`.

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new StatsAggregation('stats-price', 'price')
);

$result = $repository->search($criteria, $context);

/** @var StatsResult $aggregation */
$aggregation = $result->getAggregations()->get('stats-price');

$aggregation->getSum();
$aggregation->getMax();
$aggregation->getAvg();
$aggregation->getMin();
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
    },
    "aggregations": [
        {  
            "name": "stats-price",
            "type": "stats",
            "field": "price"
        }
    ]
}
```

Response

```json
{
    "total": 1,
    "data": [
        {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
        }
    ],
    "aggregations": {
        "stats-price": {
            "min": "5",
            "max": "979",
            "avg": 505.73333333333335,
            "sum": 30344,
            "extensions": []
        }
    }
}
```

## Terms aggregation

The `terms` aggregation belongs to the bucket aggregations. This allows you to determine the values of a field. The result contains each value once and how often this value occurs in the result. The `terms` aggregation also supports the following parameters:

* `limit` - Defines a maximum number of entries to be returned (default: zero)
* `sort` - Defines the order of the entries. By default, the following is not sorted
* `aggregation` - Enables you to calculate further aggregations for each key

The following SQL statement is executed in the background: `SELECT DISTINCT(manufacturerId) as key, COUNT(manufacturerId) as count`

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new TermsAggregation(
        'manufacturer-ids',
        'manufacturerId',
        10,
        new FieldSorting('manufacturer.name', FieldSorting::DESCENDING)
    )
);

$result = $repository->search($criteria, $context);

/** @var TermsResult $aggregation */
$aggregation = $result->getAggregations()->get('manufacturer-ids');

foreach ($aggregation->getBuckets() as $bucket) {
    $bucket->getKey();
    $bucket->getCount();
}
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
    },
    "aggregations": [
        {
            "name": "manufacturer-ids",
            "type": "terms",
            "limit": 3,
            "sort": { "field": "manufacturer.name", "order": "DESC" },
            "field": "manufacturerId"
        }
    ]
}
```

Response

```json
{
    "total": 1,
    "data": [
        {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
        }
    ],
    "aggregations": {
        "manufacturer-ids": {
            "buckets": [
                {
                    "key": "7af1534f96604744a4bc16e713550107",
                    "count": 1,
                    "extensions": []
                },
                {
                    "key": "32d5c55f960b409ab209fe25c88a6676",
                    "count": 1,
                    "extensions": []
                },
                {
                    "key": "935ceec182714a8da48227d4772628a4",
                    "count": 1,
                    "extensions": []
                }
            ],
            "extensions": []
        }
    }
}
```

## Filter aggregation

The `filter` aggregation belongs to the bucket aggregations. Unlike all other aggregations, this aggregation does not determine any result. It can't be used alone. It is only used to further restrict the result of an aggregation in a criterion. Filters defined inside the `filter` property of this aggregation type are only used when calculating this aggregation. The filters have no effect on other aggregations or on the result of the search.

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new FilterAggregation(
        'active-price-avg',
        new AvgAggregation('avg-price', 'price'),
        [
            new EqualsFilter('active', true)
        ]
    )
);

$result = $repository->search($criteria, $context);

/** @var AvgResult $aggregation */
$aggregation = $result->getAggregations()->get('avg-price');

$aggregation->getAvg();
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
    },
    "aggregations": [
       {
            "name": "active-price-avg",
            "type": "filter",
            "filter": [
                { 
                    "type": "equals", 
                    "field": "active", 
                    "value": true
                }
            ],
            "aggregation": {  
                "name": "avg-price",
                "type": "avg",
                "field": "price"
            }
        }
    ]
}
```

Response

```json
{
    "total": 1,
    "data": [
        {
            "name": "Awesome Granite HelpingHand",
            "id": "000bba26e2044b98a3ee4a84b03f9551",
            "apiAlias": "product"
        }
    ],
    "aggregations": {
        "avg-price": {
            "avg": 517.5898195488719,
            "extensions": []
        }
    }
}
```

## Entity aggregation

The `entity` aggregation is similar to the `terms` aggregation. It belongs to the bucket aggregations. As with `terms` aggregation, all unique values are determined for a field. The aggregation then uses the determined keys to load the defined entity. The keys are used here as ids.

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new EntityAggregation('manufacturers', 'manufacturerId', 'product_manufacturer')
);

$result = $repository->search($criteria, $context);

/** @var EntityResult $aggregation */
$aggregation = $result->getAggregations()->get('manufacturers');

/** @var ProductManufacturerEntity $entity */
foreach ($aggregation->getEntities() as $entity) {
    $entity->getName();
}
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"],
        "product_manufacturer": ["id", "name"]
    },
    "aggregations": [
        {
            "name": "manufacturers",
            "type": "entity",
            "definition": "product_manufacturer",
            "field": "manufacturerId"
        }
    ]
}
```

Response

```json
{
    "total": 1,
    "data": [
        {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
        }
    ],
    "aggregations": {
        "manufacturers": {
            "entities": [
                {
                    "name": "Kris, Thiel and Tillman",
                    "id": "0055fe4c16ac4d34a57b460d225682cb",
                    "apiAlias": "product_manufacturer"
                },
                {
                    "name": "Beier Group",
                    "id": "073e354c7a854287ac8c084cd70ebf90",
                    "apiAlias": "product_manufacturer"
                }
            ],
            "apiAlias": "manufacturers_aggregation"
        }
    }
}
```

## Histogram aggregation

The histogram aggregation is used as soon as the data to be determined refers to a date field. With the histogram aggregation, one of the following date intervals can be given: `minute`, `hour`, `day`, `week`, `month`, `quarter`, `year`, `day`. This interval groups the result and calculates the corresponding count of hits.

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new DateHistogramAggregation(
        'release-dates',
        'releaseDate',
        DateHistogramAggregation::PER_MONTH
    )
);

$result = $repository->search($criteria, $context);

/** @var DateHistogramResult $aggregation */
$aggregation = $result->getAggregations()->get('release-dates');

foreach ($aggregation->getBuckets() as $bucket) {
    $bucket->getKey();
    $bucket->getCount();
}
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
    },
    "aggregations": [
        {
            "name": "release-dates",
            "type": "histogram",
            "field": "releaseDate",
            "interval": "month"
        }
    ]
}
```

Response

```json
{
    "total": 1,
    "data": [
        {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
        }
    ],
    "aggregations": {
        "release-dates": {
            "buckets": [
                {
                    "key": "2020-04-01 00:00:00",
                    "count": 50,
                    "extensions": []
                },
                {
                    "key": "2020-03-01 00:00:00",
                    "count": 4,
                    "extensions": []
                },
                {
                    "key": "2020-04-01 00:00:00",
                    "count": 6,
                    "extensions": []
                }
            ],
            "apiAlias": "release-dates_aggregation"
        }
    }
}
```

## Range aggregations

Allows to aggregate data on a predefined range of values for more flexibility in the DAL - for example, it provides faceted filters on a predefined range.

Bound are computed in SQL as in the Elasticsearch native range aggregation:

* `from` will be compared with greater than or equal to
* `to` will be compared with lower than

```php
$criteria = new Criteria();
$criteria->addAggregation(
    new RangeAggregation(
        'price_ranges', 
        'products.price',
        [
            ['to' => 100],
            ['from' => 100, 'to' => 200],
            ['from' => 200]
        ]
    )
);

$result = $repository->search($criteria, $context);

/** @var RangeResult $aggregation */
$aggregation = $result->getAggregations()->get('price_ranges');

foreach ($aggregation->getRanges() as $key => $docCount) {
    // ...
}
```

```json
{
    ...
    "aggregations": {
        "price_ranges": {
            "range": {
                "field": "products.price",
                    "ranges": [
                    { "to": 100.0 },
                    { "from": 100.0, "to": 200.0 },
                    { "from": 200.0 }
                ]
            }
        }
    }
}
```

Response

```json
{
    ...
    "aggregations": {
        "price_ranges": {
            "buckets": [
                {
                    "key": "*-100.0",
                    "to": 100.0,
                    "doc_count": 2
                },
                {
                    "key": "100.0-200.0",
                    "from": 100.0,
                    "to": 200.0,
                    "doc_count": 2
                },
                {
                    "key": "200.0-*",
                    "from": 200.0,
                    "doc_count": 3
                }
            ]
        }
    }
}
```

## Nesting aggregations

A metric aggregation calculates the value for a specific field. This can be a total or, for example, a minimum or maximum value of the field. Bucket aggregations are different. This determines how often a value occurs in a search result and returns it together with the count. The special thing about bucket aggregation is that it can contain further aggregations. This allows the API to perform complex queries like, for example:

* Calculate the number of manufacturers per category that have a price over 500 Euro. \*

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new FilterAggregation(
        'my-filter',
        new TermsAggregation(
            'per-category',
            'categories.id',
            null,
            null,
            new TermsAggregation(
                'manufacturer-ids',
                'manufacturerId'
            )
        ),
        [
            new RangeFilter('price', ['gte' => 500])
        ]
    )
);

$result = $repository->search($criteria, $context);

/** @var TermsResult $aggregation */
$aggregation = $result->getAggregations()->get('per-category');

foreach ($aggregation->getBuckets() as $bucket) {
    $categoryId = $bucket->getKey();

    /** @var TermsResult $manufacturers */
    $manufacturers = $bucket->getResult();

    foreach ($manufacturers->getBuckets() as $nestedBucket) {
        $manufacturerId = $nestedBucket->getKey();
    }
}
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
    },
    "aggregations": [
        {
            "name": "my-filter",
            "type": "filter",
            "filter": [
                { 
                    "type": "range", 
                    "field": "price", 
                    "parameters": {
                        "gte": 500
                    }
                }
            ],
            "aggregation": {  
                "name": "per-category",
                "type": "terms",
                "field": "categories.id",
                "aggregation": {
                    "name": "manufacturer-ids",
                    "type": "terms", 
                    "field": "manufacturerId"
                }
            }
        }
    ]
}
```

Response

```json
{
    "total": 1,
    "data": [
        {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
        }
    ],
    "aggregations": {
        "per-category": {
            "buckets": [
                {
                    "key": "25fb912226fa48c2a5c9f4788f1f552d",
                    "count": 1,
                    "extensions": [],
                    "manufacturer-ids": {
                        "buckets": [
                            {
                                "key": "715901f2b5864181a777d1a1b912d9a2",
                                "count": 1,
                                "extensions": []
                            }
                        ],
                        "extensions": []
                    }
                },
                {
                    "key": "59b38c960597446e8c7bb76593ff7043",
                    "count": 2,
                    "extensions": [],
                    "manufacturer-ids": {
                        "buckets": [
                            {
                                "key": "98e53a711d8549059325da044da2951d",
                                "count": 1,
                                "extensions": []
                            },
                            {
                                "key": "ee8b37324c5a4c32962367146be4d7b4",
                                "count": 1,
                                "extensions": []
                            }
                        ],
                        "extensions": []
                    }
                }
            ],
            "apiAlias": "per-category_aggregation"
        }
    }
}
```

---

---
url: >-
  /docs/v6.6/resources/references/core-reference/dal-reference/aggregations-reference.md
---

# Aggregations Reference

Aggregations allow you to determine further information about the overall result in addition to the actual search results. These include totals, unique values, or the average of a field.

The DAL knows two types of aggregations:

* `metric` aggregation - This type of aggregation applies a mathematical formula to a field. A metric aggregation always has a calculated result. These are aggregations to calculate sums or maximum values.
* `bucket` aggregation - With this type of aggregation, a list of keys is determined. Further aggregations can then be determined for each key.

| Name | Type | Description |
| :--- | :--- | :--- |
| avg | metric | Average of all numeric values for the specified field |
| count | metric | Number of records for the specified field |
| max | metric | Maximum value for the specified field |
| min | metric | Minimal value for the specified field |
| stats | metric | Stats overall numeric values for the specified field |
| sum | metric | Sum of all numeric values for the specified field |
| entity | bucket | Groups the result for each value of the provided field and fetches the entities for this field |
| filter | bucket | Allows to filter the aggregation result |
| terms | bucket | Groups the result for each value of the provided field and fetches the count of affected documents |
| histogram | bucket | Groups the result for each value of the provided field and fetches the count of affected documents. Although allows to provide date interval (day, month, ...) |
| range | bucket | Groups the result for each defined set of ranges into each bucket - bucket of numerical data and a count of items/documents for each bucket |

## Avg aggregation

The `Avg` aggregation makes it possible to calculate the average value for a field. The following SQL statement is executed in the background: `AVG(price)`.

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new AvgAggregation('avg-price', 'price')
);

$result = $repository->search($criteria, $context);

/** @var AvgResult $aggregation */
$aggregation = $result->getAggregations()->get('avg-price');

$aggregation->getAvg();
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
    },
    "aggregations": [
        {  
            "name": "avg-price",
            "type": "avg",
            "field": "price"
        }
    ]
}
```

Response

```json
{
    "total": 1,
    "data": [
        {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
        }
    ],
    "aggregations": {
        "avg-price": {
            "avg": 505.73333333333335,
            "extensions": []
        }
    }
}
```

## Count aggregation

The `count` aggregation makes it possible to determine the number of entries for a field that are filled with a value. The following SQL statement is executed in the background: `COUNT(DISTINCT(manufacturerId))`.

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new CountAggregation('count-manufacturers', 'manufacturerId')
);

$result = $repository->search($criteria, $context);

/** @var CountResult $aggregation */
$aggregation = $result->getAggregations()->get('count-manufacturers');

$aggregation->getCount();
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
    },
    "aggregations": [
        {  
            "name": "count-manufacturers",
            "type": "count",
            "field": "manufacturerId"
        }
    ]
}
```

Response

```json
{
    "total": 1,
    "data": [
        {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
        }
    ],
    "aggregations": {
        "count-manufacturers": {
            "count": 44,
            "extensions": []
        }
    }
}
```

## Max aggregation

The `max` aggregation allows you to determine the maximum value of a field. The following SQL statement is executed in the background: `MAX(price)`.

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new MaxAggregation('max-price', 'price')
);

$result = $repository->search($criteria, $context);

/** @var MaxResult $aggregation */
$aggregation = $result->getAggregations()->get('max-price');

$aggregation->getMax();
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
    },
    "aggregations": [
        {  
            "name": "max-price",
            "type": "max",
            "field": "price"
        }
    ]
}
```

Response

```json
{
    "total": 1,
    "data": [
        {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
        }
    ],
    "aggregations": {
        "max-price": {
            "max": "979",
            "extensions": []
        }
    }
}
```

## Min aggregation

The `min` aggregation makes it possible to determine the minimum value of a field. The following SQL statement is executed in the background: `MIN(price)`

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new MinAggregation('min-price', 'price')
);

$result = $repository->search($criteria, $context);

/** @var MinResult $aggregation */
$aggregation = $result->getAggregations()->get('min-price');

$aggregation->getMin();
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
    },
    "aggregations": [
        {  
            "name": "min-price",
            "type": "min",
            "field": "price"
        }
    ]
}
```

Response

```json
{
    "total": 1,
    "data": [
        {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
        }
    ],
    "aggregations": {
        "min-price": {
            "min": "5",
            "extensions": []
        }
    }
}
```

## Sum aggregation

The `sum` aggregation makes it possible to determine the total of a field. The following SQL statement is executed in the background: `SUM(price)`.[PHP](https://docs.shopware.com/en/shopware-platform-dev-en/references-internals/core/dal?category=shopware-platform-dev-en/references-internals/core#)[API](https://docs.shopware.com/en/shopware-platform-dev-en/references-internals/core/dal?category=shopware-platform-dev-en/references-internals/core#)

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new SumAggregation('sum-price', 'price')
);

$result = $repository->search($criteria, $context);

/** @var SumResult $aggregation */
$aggregation = $result->getAggregations()->get('sum-price');

$aggregation->getSum();
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
    },
    "aggregations": [
        {  
            "name": "sum-price",
            "type": "sum",
            "field": "price"
        }
    ]
}
```

Response

```json
{
    "total": 1,
    "data": [
        {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
        }
    ],
    "aggregations": {
        "sum-price": {
            "sum": 30344,
            "extensions": []
        }
    }
}
```

## Stats aggregation

The `stats` aggregation makes it possible to calculate several values at once for a field. This includes the previous `max`, `min`, `avg` and `sum` aggregation. The following SQL statement is executed in the background: `SELECT MAX(price), MIN(price), AVG(price), SUM(price)`.

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new StatsAggregation('stats-price', 'price')
);

$result = $repository->search($criteria, $context);

/** @var StatsResult $aggregation */
$aggregation = $result->getAggregations()->get('stats-price');

$aggregation->getSum();
$aggregation->getMax();
$aggregation->getAvg();
$aggregation->getMin();
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
    },
    "aggregations": [
        {  
            "name": "stats-price",
            "type": "stats",
            "field": "price"
        }
    ]
}
```

Response

```json
{
    "total": 1,
    "data": [
        {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
        }
    ],
    "aggregations": {
        "stats-price": {
            "min": "5",
            "max": "979",
            "avg": 505.73333333333335,
            "sum": 30344,
            "extensions": []
        }
    }
}
```

## Terms aggregation

The `terms` aggregation belongs to the bucket aggregations. This allows you to determine the values of a field. The result contains each value once and how often this value occurs in the result. The `terms` aggregation also supports the following parameters:

* `limit` - Defines a maximum number of entries to be returned (default: zero)
* `sort` - Defines the order of the entries. By default, the following is not sorted
* `aggregation` - Enables you to calculate further aggregations for each key

The following SQL statement is executed in the background: `SELECT DISTINCT(manufacturerId) as key, COUNT(manufacturerId) as count`

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new TermsAggregation(
        'manufacturer-ids',
        'manufacturerId',
        10,
        new FieldSorting('manufacturer.name', FieldSorting::DESCENDING)
    )
);

$result = $repository->search($criteria, $context);

/** @var TermsResult $aggregation */
$aggregation = $result->getAggregations()->get('manufacturer-ids');

foreach ($aggregation->getBuckets() as $bucket) {
    $bucket->getKey();
    $bucket->getCount();
}
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
    },
    "aggregations": [
        {
            "name": "manufacturer-ids",
            "type": "terms",
            "limit": 3,
            "sort": { "field": "manufacturer.name", "order": "DESC" },
            "field": "manufacturerId"
        }
    ]
}
```

Response

```json
{
    "total": 1,
    "data": [
        {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
        }
    ],
    "aggregations": {
        "manufacturer-ids": {
            "buckets": [
                {
                    "key": "7af1534f96604744a4bc16e713550107",
                    "count": 1,
                    "extensions": []
                },
                {
                    "key": "32d5c55f960b409ab209fe25c88a6676",
                    "count": 1,
                    "extensions": []
                },
                {
                    "key": "935ceec182714a8da48227d4772628a4",
                    "count": 1,
                    "extensions": []
                }
            ],
            "extensions": []
        }
    }
}
```

## Filter aggregation

The `filter` aggregation belongs to the bucket aggregations. Unlike all other aggregations, this aggregation does not determine any result. It can't be used alone. It is only used to further restrict the result of an aggregation in a criterion. Filters defined inside the `filter` property of this aggregation type are only used when calculating this aggregation. The filters have no effect on other aggregations or on the result of the search.

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new FilterAggregation(
        'active-price-avg',
        new AvgAggregation('avg-price', 'price'),
        [
            new EqualsFilter('active', true)
        ]
    )
);

$result = $repository->search($criteria, $context);

/** @var AvgResult $aggregation */
$aggregation = $result->getAggregations()->get('avg-price');

$aggregation->getAvg();
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
    },
    "aggregations": [
       {
            "name": "active-price-avg",
            "type": "filter",
            "filter": [
                { 
                    "type": "equals", 
                    "field": "active", 
                    "value": true
                }
            ],
            "aggregation": {  
                "name": "avg-price",
                "type": "avg",
                "field": "price"
            }
        }
    ]
}
```

Response

```json
{
    "total": 1,
    "data": [
        {
            "name": "Awesome Granite HelpingHand",
            "id": "000bba26e2044b98a3ee4a84b03f9551",
            "apiAlias": "product"
        }
    ],
    "aggregations": {
        "avg-price": {
            "avg": 517.5898195488719,
            "extensions": []
        }
    }
}
```

## Entity aggregation

The `entity` aggregation is similar to the `terms` aggregation. It belongs to the bucket aggregations. As with `terms` aggregation, all unique values are determined for a field. The aggregation then uses the determined keys to load the defined entity. The keys are used here as ids.

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new EntityAggregation('manufacturers', 'manufacturerId', 'product_manufacturer')
);

$result = $repository->search($criteria, $context);

/** @var EntityResult $aggregation */
$aggregation = $result->getAggregations()->get('manufacturers');

/** @var ProductManufacturerEntity $entity */
foreach ($aggregation->getEntities() as $entity) {
    $entity->getName();
}
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"],
        "product_manufacturer": ["id", "name"]
    },
    "aggregations": [
        {
            "name": "manufacturers",
            "type": "entity",
            "definition": "product_manufacturer",
            "field": "manufacturerId"
        }
    ]
}
```

Response

```json
{
    "total": 1,
    "data": [
        {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
        }
    ],
    "aggregations": {
        "manufacturers": {
            "entities": [
                {
                    "name": "Kris, Thiel and Tillman",
                    "id": "0055fe4c16ac4d34a57b460d225682cb",
                    "apiAlias": "product_manufacturer"
                },
                {
                    "name": "Beier Group",
                    "id": "073e354c7a854287ac8c084cd70ebf90",
                    "apiAlias": "product_manufacturer"
                }
            ],
            "apiAlias": "manufacturers_aggregation"
        }
    }
}
```

## Histogram aggregation

The histogram aggregation is used as soon as the data to be determined refers to a date field. With the histogram aggregation, one of the following date intervals can be given: `minute`, `hour`, `day`, `week`, `month`, `quarter`, `year`, `day`. This interval groups the result and calculates the corresponding count of hits.

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new DateHistogramAggregation(
        'release-dates',
        'releaseDate',
        DateHistogramAggregation::PER_MONTH
    )
);

$result = $repository->search($criteria, $context);

/** @var DateHistogramResult $aggregation */
$aggregation = $result->getAggregations()->get('release-dates');

foreach ($aggregation->getBuckets() as $bucket) {
    $bucket->getKey();
    $bucket->getCount();
}
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
    },
    "aggregations": [
        {
            "name": "release-dates",
            "type": "histogram",
            "field": "releaseDate",
            "interval": "month"
        }
    ]
}
```

Response

```json
{
    "total": 1,
    "data": [
        {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
        }
    ],
    "aggregations": {
        "release-dates": {
            "buckets": [
                {
                    "key": "2020-04-01 00:00:00",
                    "count": 50,
                    "extensions": []
                },
                {
                    "key": "2020-03-01 00:00:00",
                    "count": 4,
                    "extensions": []
                },
                {
                    "key": "2020-04-01 00:00:00",
                    "count": 6,
                    "extensions": []
                }
            ],
            "apiAlias": "release-dates_aggregation"
        }
    }
}
```

## Range aggregations

Allows to aggregate data on a predefined range of values for more flexibility in the DAL - for example, it provides faceted filters on a predefined range.

Bound are computed in SQL as in the Elasticsearch native range aggregation:

* `from` will be compared with greater than or equal to
* `to` will be compared with lower than

```php
$criteria = new Criteria();
$criteria->addAggregation(
    new RangeAggregation(
        'price_ranges', 
        'products.price',
        [
            ['to' => 100],
            ['from' => 100, 'to' => 200],
            ['from' => 200]
        ]
    )
);

$result = $repository->search($criteria, $context);

/** @var RangeResult $aggregation */
$aggregation = $result->getAggregations()->get('price_ranges');

foreach ($aggregation->getRanges() as $key => $docCount) {
    // ...
}
```

```json
{
    ...
    "aggregations": {
        "price_ranges": {
            "range": {
                "field": "products.price",
                    "ranges": [
                    { "to": 100.0 },
                    { "from": 100.0, "to": 200.0 },
                    { "from": 200.0 }
                ]
            }
        }
    }
}
```

Response

```json
{
    ...
    "aggregations": {
        "price_ranges": {
            "buckets": [
                {
                    "key": "*-100.0",
                    "to": 100.0,
                    "doc_count": 2
                },
                {
                    "key": "100.0-200.0",
                    "from": 100.0,
                    "to": 200.0,
                    "doc_count": 2
                },
                {
                    "key": "200.0-*",
                    "from": 200.0,
                    "doc_count": 3
                }
            ]
        }
    }
}
```

## Nesting aggregations

A metric aggregation calculates the value for a specific field. This can be a total or, for example, a minimum or maximum value of the field. Bucket aggregations are different. This determines how often a value occurs in a search result and returns it together with the count. The special thing about bucket aggregation is that it can contain further aggregations. This allows the API to perform complex queries like, for example:

* Calculate the number of manufacturers per category that have a price over 500 Euro. \*

```php
$criteria = new Criteria();
$criteria->setLimit(1);

$criteria->addAggregation(
    new FilterAggregation(
        'my-filter',
        new TermsAggregation(
            'per-category',
            'categories.id',
            null,
            null,
            new TermsAggregation(
                'manufacturer-ids',
                'manufacturerId'
            )
        ),
        [
            new RangeFilter('price', ['gte' => 500])
        ]
    )
);

$result = $repository->search($criteria, $context);

/** @var TermsResult $aggregation */
$aggregation = $result->getAggregations()->get('per-category');

foreach ($aggregation->getBuckets() as $bucket) {
    $categoryId = $bucket->getKey();

    /** @var TermsResult $manufacturers */
    $manufacturers = $bucket->getResult();

    foreach ($manufacturers->getBuckets() as $nestedBucket) {
        $manufacturerId = $nestedBucket->getKey();
    }
}
```

```json
{
    "limit": 1,
    "includes": {
        "product": ["id", "name"]
    },
    "aggregations": [
        {
            "name": "my-filter",
            "type": "filter",
            "filter": [
                { 
                    "type": "range", 
                    "field": "price", 
                    "parameters": {
                        "gte": 500
                    }
                }
            ],
            "aggregation": {  
                "name": "per-category",
                "type": "terms",
                "field": "categories.id",
                "aggregation": {
                    "name": "manufacturer-ids",
                    "type": "terms", 
                    "field": "manufacturerId"
                }
            }
        }
    ]
}
```

Response

```json
{
    "total": 1,
    "data": [
        {
            "name": "Gorgeous Cotton Magellanic Penguin",
            "id": "0402ca6a746b41458fd000124c308cc8",
            "apiAlias": "product"
        }
    ],
    "aggregations": {
        "per-category": {
            "buckets": [
                {
                    "key": "25fb912226fa48c2a5c9f4788f1f552d",
                    "count": 1,
                    "extensions": [],
                    "manufacturer-ids": {
                        "buckets": [
                            {
                                "key": "715901f2b5864181a777d1a1b912d9a2",
                                "count": 1,
                                "extensions": []
                            }
                        ],
                        "extensions": []
                    }
                },
                {
                    "key": "59b38c960597446e8c7bb76593ff7043",
                    "count": 2,
                    "extensions": [],
                    "manufacturer-ids": {
                        "buckets": [
                            {
                                "key": "98e53a711d8549059325da044da2951d",
                                "count": 1,
                                "extensions": []
                            },
                            {
                                "key": "ee8b37324c5a4c32962367146be4d7b4",
                                "count": 1,
                                "extensions": []
                            }
                        ],
                        "extensions": []
                    }
                }
            ],
            "apiAlias": "per-category_aggregation"
        }
    }
}
```

---

---
url: /docs/products/extensions/b2b-suite/guides/storefront/ajax-panel.md
---

# Ajax Panel

`AjaxPanel` is a mini-framework based on Storefront plugins. It mimics `iFrame` behavior by integrating content from different controller actions through ajax into a single view and intercepting, usually page changing events and transforming them into XHR-Requests.

The diagram below shows how this schematically behaves:

![image](../../../../../assets/ajax-panel-abstract.svg)

## Basic usage

The `AjaxPanel` plugin is part of the b2b frontend and will scan your page automatically for the trigger class `b2b--ajax-panel`.
The most basic ajax panel looks like this:

```twig
<div
    class="b2b--ajax-panel"
    data-url="{{ path('frontend.b2b.b2bcontact.grid') }}"
>
    <!-- will load content here -->
</div>
```

After the document is ready, the ajax panel will trigger an XHR GET-Request and replace its inner HTML with the responses content.
Now, all clicks on links and forms submitted inside the container will be changed to XHR-Requests.

## Extended usage

### Make links clickable

Any HTML element can be used to trigger a location change in an ajax panel, just add a class and set a destination:

```twig
<p class="ajax-panel-link" data-href="{{ path('frontend.b2b.b2bcontact.grid') }}">Click</p>
```

### Ignore links

It might be necessary that certain links in a panel really trigger the default behavior. You just have to add a class to the link or form:

```html
<a href="http://www.shopware.com" class="ignore--b2b-ajax-panel">Go to Shopware Home</a>

<form class="ignore--b2b-ajax-panel">
    [...]
</form>
```

### Link to a different panel

One panel can influence another one by defining and linking to an id.

```html
 <div ... data-id="foreign"></div>
 <a [...] data-target="foreign">Open in another component</a>
```

## Ajax panel plugins

The B2B Suite comes with a library of simple helper plugins to add behavior to the ajax panels.

![image](../../../../../assets/b2bSuite-storefront-ajaxPanel.svg)

As you can see, there is the `AjaxPanelPluginLoader` responsible for initializing and reinitializing plugins inside b2b-panels.
Let's take our last example and extend it with a form plugin:

```twig
<div
    class="b2b--ajax-panel"
    data-url="{{ path('frontend.b2b.b2bcontact.grid') }}"
    data-plugins="ajaxPanelFormDisable"
>
    <!-- will load content here -->
</div>
```

This will disable all form elements inside the panel during panel reload.

While few of them add very specific behavior to the grid or tab's views, there are also a few more commonly interesting plugins.

### Modal

The `b2bAjaxPanelModal` plugin helps to open ajax panel content in a modal dialog box. Let's extend our initial example:

```twig
<div
    class="b2b--ajax-panel b2b-modal-panel"
    data-url="{{ path('frontend.b2b.b2bcontact.grid') }}"
    data-plugins="ajaxPanelFormDisable"
>
    <!-- will load content here -->
</div>
```

This will open the content in a modal box.

### TriggerReload

Sometimes a change in one panel needs to trigger reload in another panel.
This might be the case if you are editing in a dialog and displaying a grid behind it.
In this case, you can just trigger reload on other panel id's, just like that:

```twig
<div class="b2b--ajax-panel" data-url="{{ path('frontend.b2b.b2bcontact.grid') }}" data-id="grid">
    <!-- grid -->
</div>

<div class="b2b--ajax-panel" data-url="{{ path('frontend.b2b.b2bcontact.edit') }}" data-ajax-panel-trigger-reload="grid">
    <!-- form -->
</div>
```

Now every change in the form view will trigger reload in the grid view.

### TreeSelect

This `TreeSelect` plugin allows to display a tree view with enabled drag and drop.
In the view the `div` element needs the class `is--b2b-tree-select-container` and the data attribute data-move-url="{{ path('frontend.b2b.b2brole.move') }}".
The controller has to implement a move action, which accepts the `roleId`, `relatedRoleId`, and the `type`.

Possible types:

* prev-sibling
* last-child
* next-sibling

---

---
url: /docs/v6.5/products/extensions/b2b-suite/guides/storefront/ajax-panel.md
---

# Ajax Panel

`AjaxPanel` is a mini-framework based on Storefront plugins. It mimics `iFrame` behavior by integrating content from different controller actions through ajax into a single view and intercepting, usually page changing events and transforming them into XHR-Requests.

The diagram below shows how this schematically behaves:

![image](../../../../../assets/ajax-panel-abstract.svg)

## Basic usage

The `AjaxPanel` plugin is part of the b2b frontend and will scan your page automatically for the trigger class `b2b--ajax-panel`.
The most basic ajax panel looks like this:

```twig
<div
    class="b2b--ajax-panel"
    data-url="{{ path('frontend.b2b.b2bcontact.grid') }}"
>
    <!-- will load content here -->
</div>
```

After the document is ready, the ajax panel will trigger an XHR GET-Request and replace its inner HTML with the responses content.
Now, all clicks on links and forms submitted inside the container will be changed to XHR-Requests.

## Extended usage

### Make links clickable

Any HTML element can be used to trigger a location change in an ajax panel, just add a class and set a destination:

```twig
<p class="ajax-panel-link" data-href="{{ path('frontend.b2b.b2bcontact.grid') }}">Click</p>
```

### Ignore links

It might be necessary that certain links in a panel really trigger the default behavior. You just have to add a class to the link or form:

```html
<a href="http://www.shopware.com" class="ignore--b2b-ajax-panel">Go to Shopware Home</a>

<form class="ignore--b2b-ajax-panel">
    [...]
</form>
```

### Link to a different panel

One panel can influence another one by defining and linking to an id.

```html
 <div ... data-id="foreign"></div>
 <a [...] data-target="foreign">Open in another component</a>
```

## Ajax panel plugins

The B2B Suite comes with a library of simple helper plugins to add behavior to the ajax panels.

![image](../../../../../assets/b2bSuite-storefront-ajaxPanel.svg)

As you can see, there is the `AjaxPanelPluginLoader` responsible for initializing and reinitializing plugins inside b2b-panels.
Let's take our last example and extend it with a form plugin:

```twig
<div
    class="b2b--ajax-panel"
    data-url="{{ path('frontend.b2b.b2bcontact.grid') }}"
    data-plugins="ajaxPanelFormDisable"
>
    <!-- will load content here -->
</div>
```

This will disable all form elements inside the panel during panel reload.

While few of them add very specific behavior to the grid or tab's views, there are also a few more commonly interesting plugins.

### Modal

The `b2bAjaxPanelModal` plugin helps to open ajax panel content in a modal dialog box. Let's extend our initial example:

```twig
<div
    class="b2b--ajax-panel b2b-modal-panel"
    data-url="{{ path('frontend.b2b.b2bcontact.grid') }}"
    data-plugins="ajaxPanelFormDisable"
>
    <!-- will load content here -->
</div>
```

This will open the content in a modal box.

### TriggerReload

Sometimes a change in one panel needs to trigger reload in another panel.
This might be the case if you are editing in a dialog and displaying a grid behind it.
In this case, you can just trigger reload on other panel id's, just like that:

```twig
<div class="b2b--ajax-panel" data-url="{{ path('frontend.b2b.b2bcontact.grid') }}" data-id="grid">
    <!-- grid -->
</div>

<div class="b2b--ajax-panel" data-url="{{ path('frontend.b2b.b2bcontact.edit') }}" data-ajax-panel-trigger-reload="grid">
    <!-- form -->
</div>
```

Now every change in the form view will trigger reload in the grid view.

### TreeSelect

This `TreeSelect` plugin allows to display a tree view with enabled drag and drop.
In the view the `div` element needs the class `is--b2b-tree-select-container` and the data attribute data-move-url="{{ path('frontend.b2b.b2brole.move') }}".
The controller has to implement a move action, which accepts the `roleId`, `relatedRoleId`, and the `type`.

Possible types:

* prev-sibling
* last-child
* next-sibling

---

---
url: /docs/v6.6/products/extensions/b2b-suite/guides/storefront/ajax-panel.md
---

# Ajax Panel

`AjaxPanel` is a mini-framework based on Storefront plugins. It mimics `iFrame` behavior by integrating content from different controller actions through ajax into a single view and intercepting, usually page changing events and transforming them into XHR-Requests.

The diagram below shows how this schematically behaves:

![image](../../../../../assets/ajax-panel-abstract.svg)

## Basic usage

The `AjaxPanel` plugin is part of the b2b frontend and will scan your page automatically for the trigger class `b2b--ajax-panel`.
The most basic ajax panel looks like this:

```twig
<div
    class="b2b--ajax-panel"
    data-url="{{ path('frontend.b2b.b2bcontact.grid') }}"
>
    <!-- will load content here -->
</div>
```

After the document is ready, the ajax panel will trigger an XHR GET-Request and replace its inner HTML with the responses content.
Now, all clicks on links and forms submitted inside the container will be changed to XHR-Requests.

## Extended usage

### Make links clickable

Any HTML element can be used to trigger a location change in an ajax panel, just add a class and set a destination:

```twig
<p class="ajax-panel-link" data-href="{{ path('frontend.b2b.b2bcontact.grid') }}">Click</p>
```

### Ignore links

It might be necessary that certain links in a panel really trigger the default behavior. You just have to add a class to the link or form:

```html
<a href="http://www.shopware.com" class="ignore--b2b-ajax-panel">Go to Shopware Home</a>

<form class="ignore--b2b-ajax-panel">
    [...]
</form>
```

### Link to a different panel

One panel can influence another one by defining and linking to an id.

```html
 <div ... data-id="foreign"></div>
 <a [...] data-target="foreign">Open in another component</a>
```

## Ajax panel plugins

The B2B Suite comes with a library of simple helper plugins to add behavior to the ajax panels.

![image](../../../../../assets/b2bSuite-storefront-ajaxPanel.svg)

As you can see, there is the `AjaxPanelPluginLoader` responsible for initializing and reinitializing plugins inside b2b-panels.
Let's take our last example and extend it with a form plugin:

```twig
<div
    class="b2b--ajax-panel"
    data-url="{{ path('frontend.b2b.b2bcontact.grid') }}"
    data-plugins="ajaxPanelFormDisable"
>
    <!-- will load content here -->
</div>
```

This will disable all form elements inside the panel during panel reload.

While few of them add very specific behavior to the grid or tab's views, there are also a few more commonly interesting plugins.

### Modal

The `b2bAjaxPanelModal` plugin helps to open ajax panel content in a modal dialog box. Let's extend our initial example:

```twig
<div
    class="b2b--ajax-panel b2b-modal-panel"
    data-url="{{ path('frontend.b2b.b2bcontact.grid') }}"
    data-plugins="ajaxPanelFormDisable"
>
    <!-- will load content here -->
</div>
```

This will open the content in a modal box.

### TriggerReload

Sometimes a change in one panel needs to trigger reload in another panel.
This might be the case if you are editing in a dialog and displaying a grid behind it.
In this case, you can just trigger reload on other panel id's, just like that:

```twig
<div class="b2b--ajax-panel" data-url="{{ path('frontend.b2b.b2bcontact.grid') }}" data-id="grid">
    <!-- grid -->
</div>

<div class="b2b--ajax-panel" data-url="{{ path('frontend.b2b.b2bcontact.edit') }}" data-ajax-panel-trigger-reload="grid">
    <!-- form -->
</div>
```

Now every change in the form view will trigger reload in the grid view.

### TreeSelect

This `TreeSelect` plugin allows to display a tree view with enabled drag and drop.
In the view the `div` element needs the class `is--b2b-tree-select-container` and the data attribute data-move-url="{{ path('frontend.b2b.b2brole.move') }}".
The controller has to implement a move action, which accepts the `roleId`, `relatedRoleId`, and the `type`.

Possible types:

* prev-sibling
* last-child
* next-sibling

---

---
url: /docs/resources/references/adr/2022-01-06-custom-app-api-endpoints.md
---

# Allow apps to define custom api endpoints

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-01-06-custom-app-api-endpoints.md)
:::

## Context

Apps should be allowed to provide their own API and Store-API and Storefront endpoints where they can execute different logics that deviate from the automatic entity API.

## Decision

### API

We implement two new endpoints:

* `/api/script/{hook}`.
* `/store-api/script/{hook}`.

The `{hook}` parameter is used as the script hook name and prefixed with the url prefix (`api-`, `store-api-`).

This hook is then executed, and apps have the possibility to load or even write data in the scripts.

The following data is given to the script:

* \[array] request.request.all
* \[context/sales channel context] context

By default, multiple scripts can be executed on a single hook; however, we will add a `hook.stopPropagation()` method to all API-Hooks, if that was called no further scripts will be executed.
Furthermore, we will document that the hook-name the app developer chooses should contain the vendor-prefix to prevent unwanted overrides from other apps.

### Storefront

We implement a new endpoint:

* `/storefront/script/{hook}`

The `{hook}` parameter is used as the script hook name and prefixed with the url prefix (`storefront-`).

In this hook, the app can load or write data and either return a script response or render a twig template as a response.

The following data is given to the script:

* \[array] request.request.all
* \[array] request.query.all
* \[sales channel context] context
* \[GenericPage] page

#### Response handling

We will add a new `response` service that provides factory methods to create response objects. The returned Response object is a generic wrapper around one of the following responses: `JsonResponse`, `RedirectResponse`, `StorefrontResponse`.

To output the created response, it has to be assigned to the hook:

```twig
{% do hook.setResponse(response) %}
```

If no response is set, an empty 204 response will be sent as default.

##### Returning a custom JsonResponse

The json() method allows to specify the data and the http-status code to be returned:

```twig
{% set response = services.response.json({'data': data}, statusCode) %}
```

##### Redirecting

The redirect() method allows to specify a route and route params, to which should be redirected, and an optional statusCode (302 is default):

```twig
{% set response = services.response.redirect('routeName', params, statusCode) %}
```

##### Rendering a template

The render() factory allows to pass the template name and the parameters (the page object and additional params) and will perform the `StorefrontController->renderStorefront()`.

```twig
{% set response = services.response.render('@myApp/storefront/pages/my-custom-page.html.twig', { 'page': hook.page }) %}
```

If it is called outside of a SalesChannelContext (e.g., from an `/api` endpoint) or called on installations that don't have the storefront-bundle installed it will throw an exception.

#### Login Protection

We will add a helper method to the SalesChannelContext to ensure that a customer is logged in before continuing to execute the script. The helper method will check if there is a customer in the current `SalesChannelContext`
and will throw an `CustomerNotLoggedInException` if there is no customer logged in.

```twig
{% do hook.context.ensureLogin() %}
```

#### Caching

Our script response wrapper allows modifying the caching strategies for the responses.

```twig
{% do response.cache.invalidationState('logged-in', 'cart-filled') %}
{% do response.cache.maxAge(7200) %}
{% do response.cache.disable() %}
{% do response.cache.tag('my-manufacturer-tag-' ~ manufacturerId, 'another-tag') %}
```

By default all /storefront and /store-api routes are cached, so caching it is opt-out for those routes.
For the /api routes caching is not supported, if you provide cache configuration on the response of those routes, it will be ignored.

For individual cache invalidation, we add a new `cache-invalidation`-hook point. That hook-point is a hook on the general EntityWrittenContainerEvent.
The app can analyze the write payload of the event and use a cache-invalidation service to invalid the cache for a given tag.

We will wrap the EntityContainerEvent, so scripts are forced to specify the entity for which they want to inspect the write payload.
Instead of providing the raw payload, we will provide a fluid, functional interface which allows to filter for entityIds that match some criteria.

```twig
{% set ids = hook.event.getIds('manufacturer') %}
{% set ids = ids.only('upated') %} // only update events
{% set ids = ids.with(['name', 'url']) %}  // with name OR url cahnge

{% set ids = hook.event.get('manufacturer').only('upated').with(['name', 'url']) %} // same as above but chained

{% if ids.empty %}
    {% return %}
{% endif %}

{% set tags = [] %}
{% for id in ids %}
    {% set tags = tags|merge(['my-manufacturer-tag-' ~ id]) %}
{% endfor %}

{% do services.cache.invalidate(tags) %}
```

#### No XML-config

App-Scripts in general and custom api endpoints in particular work without further configuration inside the manifest.xml file.
We prefer solutions inside the scripts over a solution that would require additional configuration in the xml file.
The reason is that everything regarding app scripts is in one place inside the app itself, namely the `Resources/scripts` folder.
Additionally, the manifest.xml can get outdated which may lead to confusing errors, and in general, the structure of the xml file is more limited than the possibilities we have in the app scripts itself.

#### SEO-Urls

We won't add seo urls in this iteration, the reason is that that feature is pretty complex, and we don't know yet if the feature would be used at all or not.
Additionally, a feature like that would add a heavy maintenance burden because of the tight coupling to the general seo\_url solution, and we just don't know yet if the feature brings more value

We also dropped the idea of custom-routes aka the (static) seo urls light alternative, because it is an overly specific solution

We prefer more general solutions, as we can't anticipate all use cases the app developers may have, and we can't possibly build a custom solution for every use case they may have.
Therefore, we will create a separate ticket/ADR to add lifecycle scripts to the app scripts. A script like that could be used to add entries into the seo\_url table with aliases for the script routes but is not limited to that use case.
It will greatly simplify the use case that on installation of the app something should be changed/added in the DB of the shop (the current way to go would be to add a webhook on the app\_install event and build an external service that in turn uses the api to change stuff, we would eliminate the need of the external server)

---

---
url: /docs/v6.5/resources/references/adr/2022-01-06-custom-app-api-endpoints.md
---

# Allow apps to define custom api endpoints

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-01-06-custom-app-api-endpoints.md)
:::

## Context

Apps should be allowed to provide their own API and Store-API and Storefront endpoints where they can execute different logics that deviate from the automatic entity API.

## Decision

### API

We implement two new endpoints:

* `/api/script/{hook}`.
* `/store-api/script/{hook}`.

The `{hook}` parameter is used as the script hook name and prefixed with the url prefix (`api-`, `store-api-`).

This hook is then executed, and apps have the possibility to load or even write data in the scripts.

The following data is given to the script:

* \[array] request.request.all
* \[context/sales channel context] context

By default, multiple scripts can be executed on a single hook; however, we will add a `hook.stopPropagation()` method to all API-Hooks, if that was called no further scripts will be executed.
Furthermore, we will document that the hook-name the app developer chooses should contain the vendor-prefix to prevent unwanted overrides from other apps.

### Storefront

We implement a new endpoint:

* `/storefront/script/{hook}`

The `{hook}` parameter is used as the script hook name and prefixed with the url prefix (`storefront-`).

In this hook, the app can load or write data and either return a script response or render a twig template as a response.

The following data is given to the script:

* \[array] request.request.all
* \[array] request.query.all
* \[sales channel context] context
* \[GenericPage] page

#### Response handling

We will add a new `response` service that provides factory methods to create response objects. The returned Response object is a generic wrapper around one of the following responses: `JsonResponse`, `RedirectResponse`, `StorefrontResponse`.

To output the created response, it has to be assigned to the hook:

```twig
{% do hook.setResponse(response) %}
```

If no response is set, an empty 204 response will be sent as default.

##### Returning a custom JsonResponse

The json() method allows to specify the data and the http-status code to be returned:

```twig
{% set response = services.response.json({'data': data}, statusCode) %}
```

##### Redirecting

The redirect() method allows to specify a route and route params, to which should be redirected, and an optional statusCode (302 is default):

```twig
{% set response = services.response.redirect('routeName', params, statusCode) %}
```

##### Rendering a template

The render() factory allows to pass the template name and the parameters (the page object and additional params) and will perform the `StorefrontController->renderStorefront()`.

```twig
{% set response = services.response.render('@myApp/storefront/pages/my-custom-page.html.twig', { 'page': hook.page }) %}
```

If it is called outside of a SalesChannelContext (e.g., from an `/api` endpoint) or called on installations that don't have the storefront-bundle installed it will throw an exception.

#### Login Protection

We will add a helper method to the SalesChannelContext to ensure that a customer is logged in before continuing to execute the script. The helper method will check if there is a customer in the current `SalesChannelContext`
and will throw an `CustomerNotLoggedInException` if there is no customer logged in.

```twig
{% do hook.context.ensureLogin() %}
```

#### Caching

Our script response wrapper allows modifying the caching strategies for the responses.

```twig
{% do response.cache.invalidationState('logged-in', 'cart-filled') %}
{% do response.cache.maxAge(7200) %}
{% do response.cache.disable() %}
{% do response.cache.tag('my-manufacturer-tag-' ~ manufacturerId, 'another-tag') %}
```

By default all /storefront and /store-api routes are cached, so caching it is opt-out for those routes.
For the /api routes caching is not supported, if you provide cache configuration on the response of those routes, it will be ignored.

For individual cache invalidation, we add a new `cache-invalidation`-hook point. That hook-point is a hook on the general EntityWrittenContainerEvent.
The app can analyze the write payload of the event and use a cache-invalidation service to invalid the cache for a given tag.

We will wrap the EntityContainerEvent, so scripts are forced to specify the entity for which they want to inspect the write payload.
Instead of providing the raw payload, we will provide a fluid, functional interface which allows to filter for entityIds that match some criteria.

```twig
{% set ids = hook.event.getIds('manufacturer') %}
{% set ids = ids.only('upated') %} // only update events
{% set ids = ids.with(['name', 'url']) %}  // with name OR url cahnge

{% set ids = hook.event.get('manufacturer').only('upated').with(['name', 'url']) %} // same as above but chained

{% if ids.empty %}
    {% return %}
{% endif %}

{% set tags = [] %}
{% for id in ids %}
    {% set tags = tags|merge(['my-manufacturer-tag-' ~ id]) %}
{% endfor %}

{% do services.cache.invalidate(tags) %}
```

#### No XML-config

App-Scripts in general and custom api endpoints in particular work without further configuration inside the manifest.xml file.
We prefer solutions inside the scripts over a solution that would require additional configuration in the xml file.
The reason is that everything regarding app scripts is in one place inside the app itself, namely the `Resources/scripts` folder.
Additionally, the manifest.xml can get outdated which may lead to confusing errors, and in general, the structure of the xml file is more limited than the possibilities we have in the app scripts itself.

#### SEO-Urls

We won't add seo urls in this iteration, the reason is that that feature is pretty complex, and we don't know yet if the feature would be used at all or not.
Additionally, a feature like that would add a heavy maintenance burden because of the tight coupling to the general seo\_url solution, and we just don't know yet if the feature brings more value

We also dropped the idea of custom-routes aka the (static) seo urls light alternative, because it is an overly specific solution

We prefer more general solutions, as we can't anticipate all use cases the app developers may have, and we can't possibly build a custom solution for every use case they may have.
Therefore, we will create a separate ticket/ADR to add lifecycle scripts to the app scripts. A script like that could be used to add entries into the seo\_url table with aliases for the script routes but is not limited to that use case.
It will greatly simplify the use case that on installation of the app something should be changed/added in the DB of the shop (the current way to go would be to add a webhook on the app\_install event and build an external service that in turn uses the api to change stuff, we would eliminate the need of the external server)

---

---
url: /docs/v6.6/resources/references/adr/2022-01-06-custom-app-api-endpoints.md
---

# Allow apps to define custom api endpoints

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-01-06-custom-app-api-endpoints.md)
:::

## Context

Apps should be allowed to provide their own API and Store-API and Storefront endpoints where they can execute different logics that deviate from the automatic entity API.

## Decision

### API

We implement two new endpoints:

* `/api/script/{hook}`.
* `/store-api/script/{hook}`.

The `{hook}` parameter is used as the script hook name and prefixed with the url prefix (`api-`, `store-api-`).

This hook is then executed, and apps have the possibility to load or even write data in the scripts.

The following data is given to the script:

* \[array] request.request.all
* \[context/sales channel context] context

By default, multiple scripts can be executed on a single hook; however, we will add a `hook.stopPropagation()` method to all API-Hooks, if that was called no further scripts will be executed.
Furthermore, we will document that the hook-name the app developer chooses should contain the vendor-prefix to prevent unwanted overrides from other apps.

### Storefront

We implement a new endpoint:

* `/storefront/script/{hook}`

The `{hook}` parameter is used as the script hook name and prefixed with the url prefix (`storefront-`).

In this hook, the app can load or write data and either return a script response or render a twig template as a response.

The following data is given to the script:

* \[array] request.request.all
* \[array] request.query.all
* \[sales channel context] context
* \[GenericPage] page

#### Response handling

We will add a new `response` service that provides factory methods to create response objects. The returned Response object is a generic wrapper around one of the following responses: `JsonResponse`, `RedirectResponse`, `StorefrontResponse`.

To output the created response, it has to be assigned to the hook:

```twig
{% do hook.setResponse(response) %}
```

If no response is set, an empty 204 response will be sent as default.

##### Returning a custom JsonResponse

The json() method allows to specify the data and the http-status code to be returned:

```twig
{% set response = services.response.json({'data': data}, statusCode) %}
```

##### Redirecting

The redirect() method allows to specify a route and route params, to which should be redirected, and an optional statusCode (302 is default):

```twig
{% set response = services.response.redirect('routeName', params, statusCode) %}
```

##### Rendering a template

The render() factory allows to pass the template name and the parameters (the page object and additional params) and will perform the `StorefrontController->renderStorefront()`.

```twig
{% set response = services.response.render('@myApp/storefront/pages/my-custom-page.html.twig', { 'page': hook.page }) %}
```

If it is called outside of a SalesChannelContext (e.g., from an `/api` endpoint) or called on installations that don't have the storefront-bundle installed it will throw an exception.

#### Login Protection

We will add a helper method to the SalesChannelContext to ensure that a customer is logged in before continuing to execute the script. The helper method will check if there is a customer in the current `SalesChannelContext`
and will throw an `CustomerNotLoggedInException` if there is no customer logged in.

```twig
{% do hook.context.ensureLogin() %}
```

#### Caching

Our script response wrapper allows modifying the caching strategies for the responses.

```twig
{% do response.cache.invalidationState('logged-in', 'cart-filled') %}
{% do response.cache.maxAge(7200) %}
{% do response.cache.disable() %}
{% do response.cache.tag('my-manufacturer-tag-' ~ manufacturerId, 'another-tag') %}
```

By default all /storefront and /store-api routes are cached, so caching it is opt-out for those routes.
For the /api routes caching is not supported, if you provide cache configuration on the response of those routes, it will be ignored.

For individual cache invalidation, we add a new `cache-invalidation`-hook point. That hook-point is a hook on the general EntityWrittenContainerEvent.
The app can analyze the write payload of the event and use a cache-invalidation service to invalid the cache for a given tag.

We will wrap the EntityContainerEvent, so scripts are forced to specify the entity for which they want to inspect the write payload.
Instead of providing the raw payload, we will provide a fluid, functional interface which allows to filter for entityIds that match some criteria.

```twig
{% set ids = hook.event.getIds('manufacturer') %}
{% set ids = ids.only('upated') %} // only update events
{% set ids = ids.with(['name', 'url']) %}  // with name OR url cahnge

{% set ids = hook.event.get('manufacturer').only('upated').with(['name', 'url']) %} // same as above but chained

{% if ids.empty %}
    {% return %}
{% endif %}

{% set tags = [] %}
{% for id in ids %}
    {% set tags = tags|merge(['my-manufacturer-tag-' ~ id]) %}
{% endfor %}

{% do services.cache.invalidate(tags) %}
```

#### No XML-config

App-Scripts in general and custom api endpoints in particular work without further configuration inside the manifest.xml file.
We prefer solutions inside the scripts over a solution that would require additional configuration in the xml file.
The reason is that everything regarding app scripts is in one place inside the app itself, namely the `Resources/scripts` folder.
Additionally, the manifest.xml can get outdated which may lead to confusing errors, and in general, the structure of the xml file is more limited than the possibilities we have in the app scripts itself.

#### SEO-Urls

We won't add seo urls in this iteration, the reason is that that feature is pretty complex, and we don't know yet if the feature would be used at all or not.
Additionally, a feature like that would add a heavy maintenance burden because of the tight coupling to the general seo\_url solution, and we just don't know yet if the feature brings more value

We also dropped the idea of custom-routes aka the (static) seo urls light alternative, because it is an overly specific solution

We prefer more general solutions, as we can't anticipate all use cases the app developers may have, and we can't possibly build a custom solution for every use case they may have.
Therefore, we will create a separate ticket/ADR to add lifecycle scripts to the app scripts. A script like that could be used to add entries into the seo\_url table with aliases for the script routes but is not limited to that use case.
It will greatly simplify the use case that on installation of the app something should be changed/added in the DB of the shop (the current way to go would be to add a webhook on the app\_install event and build an external service that in turn uses the api to change stuff, we would eliminate the need of the external server)

---

---
url: /docs/resources/references/config-reference/server/apache.md
---
# Apache

::: info
The document root must always point to the public folder, to ensure all functionality works.
:::

```text
<VirtualHost *:80>
   ServerName "HOST_NAME"
   DocumentRoot _SHOPWARE_LOCATION_/public

   <Directory _SHOPWARE_LOCATION_>
      Options Indexes FollowSymLinks MultiViews
      AllowOverride All
      Order allow,deny
      allow from all
   </Directory>

   ErrorLog ${APACHE_LOG_DIR}/shopware.error.log
   CustomLog ${APACHE_LOG_DIR}/shopware.access.log combined
</VirtualHost>
```

---

---
url: /docs/v6.5/resources/references/config-reference/server/apache.md
---
# Apache

::: info
The document root must always point to the public folder, to ensure all functionality works.
:::

```text
<VirtualHost *:80>
   ServerName "HOST_NAME"
   DocumentRoot _SHOPWARE_LOCATION_/public

   <Directory _SHOPWARE_LOCATION_>
      Options Indexes FollowSymLinks MultiViews
      AllowOverride All
      Order allow,deny
      allow from all
   </Directory>

   ErrorLog ${APACHE_LOG_DIR}/shopware.error.log
   CustomLog ${APACHE_LOG_DIR}/shopware.access.log combined
</VirtualHost>
```

---

---
url: /docs/v6.6/resources/references/config-reference/server/apache.md
---
# Apache

::: info
The document root must always point to the public folder, to ensure all functionality works.
:::

```text
<VirtualHost *:80>
   ServerName "HOST_NAME"
   DocumentRoot _SHOPWARE_LOCATION_/public

   <Directory _SHOPWARE_LOCATION_>
      Options Indexes FollowSymLinks MultiViews
      AllowOverride All
      Order allow,deny
      allow from all
   </Directory>

   ErrorLog ${APACHE_LOG_DIR}/shopware.error.log
   CustomLog ${APACHE_LOG_DIR}/shopware.access.log combined
</VirtualHost>
```

---

---
url: /docs/concepts/api.md
---

# API

Shopware exposes HTTP-based APIs that allow external systems and custom applications to interact with the platform.

Two functional APIs are available, each representing a different integration surface:

* **Store API**: customer-facing interactions
* **Admin API**: administrative and system-level operations

Both APIs use HTTP and exchange JSON payloads. The Administration API requires OAuth 2.0 authentication, whereas the Store API is publicly accessible and only requires contextual headers, with authentication needed for customer-specific endpoints. While they serve different purposes within the platform, they share some underlying design principles and structural patterns:

* Search criteria abstraction for filtering, sorting, and pagination
* Structured JSON request/response bodies
* Header-based contextual behavior

These patterns form the foundation of integration development.

## Start building

Use the [API](../../guides/development/integrations-api/index.md) guide for practical API setup, authentication, request examples, and links to the generated API reference.

---

---
url: /docs/v6.5/concepts/api.md
---

# API

The Shopware API allows developers to interact with and integrate Shopware with other systems and applications. It provides a set of services that enable developers to perform various operations, such as managing products, customers, orders, and shopping carts.The API supports both read and write operations, allowing developers to retrieve information from Shopware and make modifications or additions to the e-commerce platform. By leveraging the Shopware API, developers can extend the functionality of Shopware, integrate it with external systems, and create seamless experiences for managing and operating online stores.

Shopware supports two major functional APIs: the Store API and the Admin API. These APIs serve different purposes. The Store API is designed to interact with the front-end or storefront of a Shopware online store while the Admin API is intended for administrative operations related to managing the back-end of the Shopware platform.

The API documentation provides details on the available endpoints, request/response formats, authentication mechanisms, and data structures. It supports different authentication methods, including token-based authentication and OAuth 2.0, to ensure secure communication between the API client and the Shopware platform.

---

---
url: /docs/v6.5/guides/plugins/plugins/api.md
---

# API

Commercial plugins are pre-built extensions developed by third-party vendors that offer specific features and integrations. In some cases, commercial plugins may expose their own APIs, which developers can use to interact with the plugin's functionalities allowing customization and integration with other systems.

Overall, commercial plugins and APIs work together to expand the capabilities of the Shopware platform. Commercial plugins offer ready-to-use solutions, while APIs provide the flexibility for developers to build custom integrations and extend the functionality of Shopware even further.

---

---
url: /docs/v6.6/concepts/api.md
---

# API

The Shopware API allows developers to interact with and integrate Shopware with other systems and applications. It provides a set of services that enable developers to perform various operations, such as managing products, customers, orders, and shopping carts.The API supports both read and write operations, allowing developers to retrieve information from Shopware and make modifications or additions to the e-commerce platform. By leveraging the Shopware API, developers can extend the functionality of Shopware, integrate it with external systems, and create seamless experiences for managing and operating online stores.

Shopware supports two major functional APIs: the Store API and the Admin API. These APIs serve different purposes. The Store API is designed to interact with the front-end or storefront of a Shopware online store while the Admin API is intended for administrative operations related to managing the back-end of the Shopware platform.

The API documentation provides details on the available endpoints, request/response formats, authentication mechanisms, and data structures. It supports different authentication methods, including token-based authentication and OAuth 2.0, to ensure secure communication between the API client and the Shopware platform.

---

---
url: /docs/v6.6/guides/plugins/plugins/api.md
---

# API

Commercial plugins are pre-built extensions developed by third-party vendors that offer specific features and integrations. In some cases, commercial plugins may expose their own APIs, which developers can use to interact with the plugin's functionalities allowing customization and integration with other systems.

Overall, commercial plugins and APIs work together to expand the capabilities of the Shopware platform. Commercial plugins offer ready-to-use solutions, while APIs provide the flexibility for developers to build custom integrations and extend the functionality of Shopware even further.

---

---
url: /docs/guides/development/integrations-api/flows.md
---

# API Flows

These guides focus on concrete end-to-end flows where it helps to see API calls together, rather than as isolated endpoint references.

## Available flows

[Create a Product and Complete Checkout](./create-product.md): Create a category and a product with the Admin API, read them through the Store API, add the product to a cart, register a customer, place an order, and handle payment if needed.

More flows to be added over time.

---

---
url: /docs/v6.5/resources/references/api-reference.md
---

# API Reference

The API references provide detailed information about the available endpoints, methods, parameters, request and response formats, and authentication mechanisms of an API. It provides essential information on how to interact with the API, what data can be sent or received, and how to handle different API responses.

These references guide you to use the correct syntax, understand the expected input and output formats, implement the necessary authentication mechanisms and successful API requests and effectively utilize the functionality provided by the API in your applications.

There are two dedicated API reference documents for your reference:

* [Store API reference](https://shopware.stoplight.io/docs/store-api/38777d33d92dc-quick-start-guide) - Focused on customer-facing aspects, the Store API allows you to access and manipulate data related to products, customer interactions, shopping carts, and others that significantly impact the frontend user experience. It caters to both anonymous and authenticated users.

* [Admin API reference](https://shopware.stoplight.io/docs/admin-api/twpxvnspkg3yu-quick-start-guide) - Primarily for backend and administrative functions, the Admin API enables structured data exchanges, bulk operations, data synchronization, and import-export tasks, addressing the backend needs of the Shopware platform.

---

---
url: /docs/v6.6/resources/references/api-reference.md
---

# API Reference

The API references provide detailed information about the available endpoints, methods, parameters, request and response formats, and authentication mechanisms of an API. It provides essential information on how to interact with the API, what data can be sent or received, and how to handle different API responses.

These references guide you to use the correct syntax, understand the expected input and output formats, implement the necessary authentication mechanisms and successful API requests and effectively utilize the functionality provided by the API in your applications.

There are two dedicated API reference documents for your reference:

* [Store API reference](https://shopware.stoplight.io/docs/store-api/38777d33d92dc-quick-start-guide) - Focused on customer-facing aspects, the Store API allows you to access and manipulate data related to products, customer interactions, shopping carts, and others that significantly impact the frontend user experience. It caters to both anonymous and authenticated users.

* [Admin API reference](https://shopware.stoplight.io/docs/admin-api/twpxvnspkg3yu-quick-start-guide) - Primarily for backend and administrative functions, the Admin API enables structured data exchanges, bulk operations, data synchronization, and import-export tasks, addressing the backend needs of the Shopware platform.

---

---
url: /resources/admin-extension-sdk/api-reference.md
---

# API Reference

The Meteor Admin SDK provides APIs for extending the Shopware Administration UI and interacting with Administration data.

These APIs allow extensions to add user interface elements, access and modify entity data, register CMS blocks and elements, and share state between components.

Use the sections below to navigate the available APIs.

## Extending the UI

These components allow extensions to add UI elements to the Shopware Administration. They can be used to register modules, add navigation entries, extend existing pages, and display dialogs or side panels.

Typical use cases include:

* Creating custom modules in the Administration
* Extending entity detail pages
* Adding navigation or settings entries
* Displaying modals or contextual UI elements

UI extension components in this section include:

* [Main Module](./ui/mainModule.md)
* [Menu](./ui/menu.md)
* [Settings Item](./ui/settingsItem.md)
* [Action Button](./ui/actionButton.md)
* [Notification](./ui/notification.md)
* [Toast](./ui/toast.md)
* [Tabs](./ui/tabs.md)
* [Component Sections](./ui/component-sections.md)
* [Sidebars](./ui/sidebars.md)
* [Modals](./ui/modals.md)
* [Media Modal](./ui/mediaModal.md)

**Purchases and payments**

* [In-App Purchases](./ui/purchases-and-payments/in-app-purchases.md): Start an in-app purchase flow
* [Payment Overview Card](./ui/purchases-and-payments/paymentOverviewCard.md): Customize payment method cards

## Working with Data

These tools allow extensions to access and manipulate Shopware entity data from within the Administration.

They follow the same repository-based data access pattern used internally by the Administration.

Typical workflows include:

* Accessing entity repositories
* Retrieving entity data
* Subscribing to changes
* Updating or persisting entities

Tools this section include:

* [Repository](./data/repository.md): Access Shopware entity repositories
* [Get](./data/get.md)
* [Subscribe](./data/subscribe.md)
* [Update](./data/update.md)

## Composable APIs

Composable APIs provide reusable helpers for working with the Administration state and data layer inside extensions.

They simplify common patterns such as accessing repositories or sharing state between components.

APIs in this section include:

* [useRepository](./composables/useRepository.md)
* [useSharedState](./composables/useSharedState.md)

## Extending the CMS

These APIs allow extensions to add new CMS blocks and elements to the Shopware Shopping Experiences editor.

They can be used to introduce custom content components that merchants can use when building storefront pages.

APIs in this section include:

* [Register CMS Block](./cms/registerCmsBlock.md)
* [Register CMS Element](./cms/registerCmsElement.md)

## Shared Options

Some SDK APIs support shared configuration options that control how actions are executed in the Administration.

* [Base Options](./base-options.md)

---

---
url: >-
  /docs/products/extensions/b2b-components/employee-management/guides/api-route-restriction-for-employees.md
---

# API Route Restriction for Employees

## Overview

B2B employees and business partners share the same customer account. This can lead to inconsistency for all users of the shared account because they are allowed to change settings and data (both via Storefront and Store API), which are not related to the B2B permission system. Hence, it is decided to restrict most of the customer account routes by implementing a denylist pattern to prevent the illegal modification of customer data and settings, instead of replicating all customer features for employee accounts. All non-account related routes are still available for B2B employees.

## Denylist

The denylist can be found in the employee management config at: `Resources\config\employee_route_access.xml`. All denied routes are inside `<denied>` tags. The routes inside the `<allowed>` tags are not important for third-party developers because they are used for internal integration tests to remind developers to extend the list if new Store API account routes are added.

### Denylist Example

```xml
<?xml version="1.0" encoding="utf-8"?>
<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../Schema/Xml/employee-route-access-1.0.xsd">
    <denied>store-api.account.change-profile</denied>
    <denied>store-api.account.change-email</denied>
    <denied>...</denied>

    <allowed>store-api.account.login</allowed>
    <allowed>store-api.account.logout</allowed>
    <allowed>...</allowed>
</routes>
```

### How to load the Denylist

The denylist is loaded by using the `load` function in the `Shopware\Commercial\B2b\Domain\RouteAccess\EmployeeRouteAccessLoader` class. The return result is an associative array that includes arrays of all `allowed` and `denied` routes.

### Where is the Denylist loaded

The denylist is loaded in the `Shopware\Commercial\B2b\Subscriber\B2bRouteBlocker`, which listens to each controller event and validates the route access before the request reaches the controller. Illegal attempts cause an exception to be thrown.

### How to override the Denylist

It is possible to create additional `employee_route_access.xml` configs, which include new denied routes. After the config is ready, you can decorate the `Shopware\Commercial\B2b\Domain\RouteAccess\EmployeeRouteAccessLoader`, which supports recommended Shopware decoration pattern. Adapt the solution of the decorated `EmployeeRouteAccessLoader::load` function and return your own config.

#### Decoration Example

```php
<?php declare(strict_types=1);

namespace Shopware\Commercial\B2B\Domain\RouteAccess;

class DecoratedEmployeeRouteAccessLoader extends AbstractEmployeeRouteAccessLoader
{
    private const CONFIG = __DIR__ . '/../../Resources/config/new-custom-employee_route_access.xml';

    public function __construct(
        private readonly AbstractEmployeeRouteAccessLoader $decorated
    ) {
    }

    public function getDecorated(): AbstractEmployeeRouteAccessLoader
    {
        return $this->decorated;
    }

    public function load(): array
    {
        $oldConfig = $this->decorated->load();
        $customConfig = (array) @simplexml_load_file(self::CONFIG);

        // This example merges the old config with the new created custom config.
        // Return the $customConfig variable to override the old completely

        return array_merge_recursive($oldConfig, $customConfig);
    }
}
```

---

---
url: >-
  /docs/v6.5/products/extensions/b2b-components/employee-management/concept/api-route-restriction-for-employees.md
---

# API Route Restriction for Employees

## Overview

B2B employees and business partners share the same customer account. This can lead to inconsistency for all users of the shared account because they are allowed to change settings and data (both via Storefront and Store API), which are not related to the B2B permission system. Hence, it is decided to restrict most of the customer account routes by implementing a denylist pattern to prevent the illegal modification of customer data and settings, instead of replicating all customer features for employee accounts. All non-account related routes are still available for B2B employees.

## Denylist

The denylist can be found in the employee management config at: `Resources\config\employee_route_access.xml`. All denied routes are inside `<denied>` tags. The routes inside the `<allowed>` tags are not important for third-party developers because they are used for internal integration tests to remind developers to extend the list if new Store API account routes are added.

### Denylist Example

```xml
<?xml version="1.0" encoding="utf-8"?>
<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../Schema/Xml/employee-route-access-1.0.xsd">
    <denied>store-api.account.change-profile</denied>
    <denied>store-api.account.change-email</denied>
    <denied>...</denied>

    <allowed>store-api.account.login</allowed>
    <allowed>store-api.account.logout</allowed>
    <allowed>...</allowed>
</routes>
```

### How to load the Denylist

The denylist is loaded by using the `load` function in the `Shopware\Commercial\B2b\Domain\RouteAccess\EmployeeRouteAccessLoader` class. The return result is an associative array that includes arrays of all `allowed` and `denied` routes.

### Where is the Denylist loaded

The denylist is loaded in the `Shopware\Commercial\B2b\Subscriber\B2bRouteBlocker`, which listens to each controller event and validates the route access before the request reaches the controller. Illegal attempts cause an exception to be thrown.

### How to override the Denylist

It is possible to create additional `employee_route_access.xml` configs, which include new denied routes. After the config is ready, you can decorate the `Shopware\Commercial\B2b\Domain\RouteAccess\EmployeeRouteAccessLoader`, which supports recommended Shopware decoration pattern. Adapt the solution of the decorated `EmployeeRouteAccessLoader::load` function and return your own config.

#### Decoration Example

```php
<?php declare(strict_types=1);

namespace Shopware\Commercial\B2B\Domain\RouteAccess;

class DecoratedEmployeeRouteAccessLoader extends AbstractEmployeeRouteAccessLoader
{
    private const CONFIG = __DIR__ . '/../../Resources/config/new-custom-employee_route_access.xml';

    public function __construct(
        private readonly AbstractEmployeeRouteAccessLoader $decorated
    ) {
    }

    public function getDecorated(): AbstractEmployeeRouteAccessLoader
    {
        return $this->decorated;
    }

    public function load(): array
    {
        $oldConfig = $this->decorated->load();
        $customConfig = (array) @simplexml_load_file(self::CONFIG);

        // This example merges the old config with the new created custom config.
        // Return the $customConfig variable to override the old completely

        return array_merge_recursive($oldConfig, $customConfig);
    }
}
```

---

---
url: >-
  /docs/v6.6/products/extensions/b2b-components/employee-management/guides/api-route-restriction-for-employees.md
---

# API Route Restriction for Employees

## Overview

B2B employees and business partners share the same customer account. This can lead to inconsistency for all users of the shared account because they are allowed to change settings and data (both via Storefront and Store API), which are not related to the B2B permission system. Hence, it is decided to restrict most of the customer account routes by implementing a denylist pattern to prevent the illegal modification of customer data and settings, instead of replicating all customer features for employee accounts. All non-account related routes are still available for B2B employees.

## Denylist

The denylist can be found in the employee management config at: `Resources\config\employee_route_access.xml`. All denied routes are inside `<denied>` tags. The routes inside the `<allowed>` tags are not important for third-party developers because they are used for internal integration tests to remind developers to extend the list if new Store API account routes are added.

### Denylist Example

```xml
<?xml version="1.0" encoding="utf-8"?>
<routes xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../Schema/Xml/employee-route-access-1.0.xsd">
    <denied>store-api.account.change-profile</denied>
    <denied>store-api.account.change-email</denied>
    <denied>...</denied>

    <allowed>store-api.account.login</allowed>
    <allowed>store-api.account.logout</allowed>
    <allowed>...</allowed>
</routes>
```

### How to load the Denylist

The denylist is loaded by using the `load` function in the `Shopware\Commercial\B2b\Domain\RouteAccess\EmployeeRouteAccessLoader` class. The return result is an associative array that includes arrays of all `allowed` and `denied` routes.

### Where is the Denylist loaded

The denylist is loaded in the `Shopware\Commercial\B2b\Subscriber\B2bRouteBlocker`, which listens to each controller event and validates the route access before the request reaches the controller. Illegal attempts cause an exception to be thrown.

### How to override the Denylist

It is possible to create additional `employee_route_access.xml` configs, which include new denied routes. After the config is ready, you can decorate the `Shopware\Commercial\B2b\Domain\RouteAccess\EmployeeRouteAccessLoader`, which supports recommended Shopware decoration pattern. Adapt the solution of the decorated `EmployeeRouteAccessLoader::load` function and return your own config.

#### Decoration Example

```php
<?php declare(strict_types=1);

namespace Shopware\Commercial\B2B\Domain\RouteAccess;

class DecoratedEmployeeRouteAccessLoader extends AbstractEmployeeRouteAccessLoader
{
    private const CONFIG = __DIR__ . '/../../Resources/config/new-custom-employee_route_access.xml';

    public function __construct(
        private readonly AbstractEmployeeRouteAccessLoader $decorated
    ) {
    }

    public function getDecorated(): AbstractEmployeeRouteAccessLoader
    {
        return $this->decorated;
    }

    public function load(): array
    {
        $oldConfig = $this->decorated->load();
        $customConfig = (array) @simplexml_load_file(self::CONFIG);

        // This example merges the old config with the new created custom config.
        // Return the $customConfig variable to override the old completely

        return array_merge_recursive($oldConfig, $customConfig);
    }
}
```

---

---
url: /docs/resources/references/adr/2020-12-02-removing-api-version.md
---

# API version removal

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2020-12-02-removing-api-version.md)
:::

## Context

Due to the new deprecation strategy and the 6-8 months major cycle, API versioning is no longer  reasonable or even possible.
Deprecated fields and routes are currently tagged in a minor version and will be removed with the next major version.
The API version is currently not increased in a minor version, which would not make sense, because with every second minor version deprecations would have to be removed.

## Decision

By removing the API versioning within the URL we want to simplify usage and the deprecation strategy of our API.
The deprecated fields and routes are shown in the OpenAPI scheme as well as the API changelog and will be removed with the next major version (`6.x`).

## Consequences

All route URLs are changed from `/api/v{VERSION}/product` to `/api/product`.
Beginning with 6.3.5.0 both route URLs are accessible via `/api/v{VERSION}/product` and `/api/product` before and until the release of 6.4.0.0 in order to enable preparation of connections well in advance.

---

---
url: /docs/v6.5/resources/references/adr/2020-12-02-removing-api-version.md
---

# API version removal

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2020-12-02-removing-api-version.md)
:::

## Context

Due to the new deprecation strategy and the 6-8 months major cycle, API versioning is no longer  reasonable or even possible.
Deprecated fields and routes are currently tagged in a minor version and will be removed with the next major version.
The API version is currently not increased in a minor version, which would not make sense, because with every second minor version deprecations would have to be removed.

## Decision

By removing the API versioning within the URL we want to simplify usage and the deprecation strategy of our API.
The deprecated fields and routes are shown in the OpenAPI scheme as well as the API changelog and will be removed with the next major version (`6.x`).

## Consequences

All route URLs are changed from `/api/v{VERSION}/product` to `/api/product`.
Beginning with 6.3.5.0 both route URLs are accessible via `/api/v{VERSION}/product` and `/api/product` before and until the release of 6.4.0.0 in order to enable preparation of connections well in advance.

---

---
url: /docs/v6.6/resources/references/adr/2020-12-02-removing-api-version.md
---

# API version removal

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2020-12-02-removing-api-version.md)
:::

## Context

Due to the new deprecation strategy and the 6-8 months major cycle, API versioning is no longer  reasonable or even possible.
Deprecated fields and routes are currently tagged in a minor version and will be removed with the next major version.
The API version is currently not increased in a minor version, which would not make sense, because with every second minor version deprecations would have to be removed.

## Decision

By removing the API versioning within the URL we want to simplify usage and the deprecation strategy of our API.
The deprecated fields and routes are shown in the OpenAPI scheme as well as the API changelog and will be removed with the next major version (`6.x`).

## Consequences

All route URLs are changed from `/api/v{VERSION}/product` to `/api/product`.
Beginning with 6.3.5.0 both route URLs are accessible via `/api/v{VERSION}/product` and `/api/product` before and until the release of 6.4.0.0 in order to enable preparation of connections well in advance.

---

---
url: /docs/v6.5/guides/integrations-api/general-concepts/api-versioning.md
---

# API Versioning

## Overview

Starting with Shopware version 6.4.0.0, we decided to change our API versioning strategy. This article will cover what has been done and changed, how it used to be, and what the version strategy looks like now.

### Versioning prior to 6.4.0.0

Prior to Shopware 6.4.0.0, the API version was mainly found in the routes themselves.

`/api/v3/example-route`

By using the version, one could ensure that his application keeps on working because we are not going to introduce breaking changes within a version. Yet, versions had to be removed every now and then, which would then still break the application.

More on this can be found in our guide [ADR regarding the API version removal](https://github.com/shopware/shopware/blob/6.4.0.0/adr/2020-12-02-removing-api-version.md) section.

### Versioning starting with 6.3.5.0

With Shopware 6.4.0.0, we removed the API version from the routes.

**Old**:

`/api/v3/example-route`

**New**:

`/api/example-route`

The version inside the route will keep working with Shopware 6.3.\*, but it will be removed with the next major Shopware version, 6.4.0.

### Deprecations

Deprecations are now added with patch and minor releases but only removed with a major release. This has always been the case for the Core and is now adapted to the API.

Also, deprecated fields and routes are now shown in the Swagger documentation. Have a look at the FAQ beneath to learn how to open Swagger. Have a look for the `@deprecated` annotation on routes or the `Deprecated` flag on entity fields to see which fields or routes are deprecated in the code.

### Route and field availability

The Swagger API reference now includes the necessary information about the route and field availability. For routes, this can look like this:

![Availability route](../../../assets/availability-route.png)

Note the availability information.

Same for fields, here is an example of how it would look like:

![Availability field](../../../assets/availability-field.png)

### API expectations

API expectations can be used as a request header to define the necessary conditions for the server side. Example conditions could be the Shopware version, the existence of plugins, or the version of a plugin. There are some examples:

```text
GET /api/test
sw-expect-packages: shopware/core:~6.4
```

This would expect that at least Shopware with version 6.4 is installed.

```text
GET /api/test
sw-expect-packages: shopware/core:~6.4,swag/paypal:*
```

This would expect that the Shopware version is at least 6.4 and PayPal is installed in any version.

If the conditions are not met, the backend will answer with a *417 Expectation Failed* error.

## FAQ

### I ensure that my application will keep on working by using the version in the route. What now?

Yes, this was necessary for the previous versioning strategy since breaks were also introduced with Shopware minor releases. The new versioning strategy comes with the benefit that breaks are only introduced with major releases, which were always breaking anyway. Thus, one route will keep working for you until the next major release.

### How do I get the currently used version via the API?

You can read the currently used version in the API as well. Starting with Shopware 6.3.5.0, you can use this route to fetch the current version: `GET /api/_info/version`

Prior to that, the version was readable using the following route: `GET /api/v2/_info/config`

### How do I open up the Swagger page?

Simply navigate to the following URL in your shop: `/api/_info/swagger.html`

---

---
url: /docs/v6.6/guides/integrations-api/general-concepts/api-versioning.md
---

# API Versioning

## Overview

Starting with Shopware version 6.4.0.0, we decided to change our API versioning strategy. This article will cover what has been done and changed, how it used to be, and what the version strategy looks like now.

### Versioning prior to 6.4.0.0

Prior to Shopware 6.4.0.0, the API version was mainly found in the routes themselves.

`/api/v3/example-route`

By using the version, one could ensure that his application keeps on working because we are not going to introduce breaking changes within a version. Yet, versions had to be removed every now and then, which would then still break the application.

More on this can be found in our guide [ADR regarding the API version removal](https://github.com/shopware/shopware/blob/trunk/adr/2020-12-02-removing-api-version.md) section.

### Versioning starting with 6.3.5.0

With Shopware 6.4.0.0, we removed the API version from the routes.

**Old**:

`/api/v3/example-route`

**New**:

`/api/example-route`

The version inside the route will keep working with Shopware 6.3.\*, but it will be removed with the next major Shopware version, 6.4.0.

### Deprecations

Deprecations are now added with patch and minor releases but only removed with a major release. This has always been the case for the Core and is now adapted to the API.

Also, deprecated fields and routes are now shown in the Swagger documentation. Have a look at the FAQ beneath to learn how to open Swagger. Have a look for the `@deprecated` annotation on routes or the `Deprecated` flag on entity fields to see which fields or routes are deprecated in the code.

### Route and field availability

The Swagger API reference now includes the necessary information about the route and field availability. For routes, this can look like this:

![Availability route](../../../assets/availability-route.png)

Note the availability information.

Same for fields, here is an example of how it would look like:

![Availability field](../../../assets/availability-field.png)

### API expectations

API expectations can be used as a request header to define the necessary conditions for the server side. Example conditions could be the Shopware version, the existence of plugins, or the version of a plugin. There are some examples:

```text
GET /api/test
sw-expect-packages: shopware/core:~6.4
```

This would expect that at least Shopware with version 6.4 is installed.

```text
GET /api/test
sw-expect-packages: shopware/core:~6.4,swag/paypal:*
```

This would expect that the Shopware version is at least 6.4 and PayPal is installed in any version.

If the conditions are not met, the backend will answer with a *417 Expectation Failed* error.

## FAQ

### I ensure that my application will keep on working by using the version in the route. What now?

Yes, this was necessary for the previous versioning strategy since breaks were also introduced with Shopware minor releases. The new versioning strategy comes with the benefit that breaks are only introduced with major releases, which were always breaking anyway. Thus, one route will keep working for you until the next major release.

### How do I get the currently used version via the API?

You can read the currently used version in the API as well. Starting with Shopware 6.3.5.0, you can use this route to fetch the current version: `GET /api/_info/version`

Prior to that, the version was readable using the following route: `GET /api/v2/_info/config`

### How do I open up the Swagger page?

Simply navigate to the following URL in your shop: `/api/_info/swagger.html`

---

---
url: /docs/guides/development/integrations-api.md
---

# APIs

This guide helps you make your first successful API request. Your Shopware instance should already be running and accessible. If it is not, return to the [Installation Guide](../../installation/index.md).

Shopware provides two HTTP APIs:

* **Admin API** for backend operations such as products, orders, customers, plugins, and — via the Sync API — bulk operations (for example, mass imports)
* **Store API** for storefront-facing interactions such as headless frontends, mobile apps, carts, checkout, and sales channel access

For the complete endpoint reference and schemas, use the official Stoplight documentation:

* [Admin API](https://shopware.stoplight.io/docs/admin-api/twpxvnspkg3yu-quick-start-guide)
* [Store API](https://shopware.stoplight.io/docs/store-api/38777d33d92dc-quick-start-guide)

This page is a practical quick start and does not duplicate the full API reference.

## API overview

### Admin API

Use the [Admin API](https://shopware.stoplight.io/docs/admin-api/twpxvnspkg3yu-quick-start-guide) for backend and administrative tasks such as:

* Managing entities like products, categories, and orders
* Running backend integrations and import or export workflows
* Performing bulk operations
* Building Admin-side applications

Base path: `/api/*`

Complete endpoint documentation (local instance required): `/api/_info/stoplightio.html`.

A common search endpoint looks like this: `POST /api/search/{entity}`

### Store API

Use the [Store API](https://shopware.stoplight.io/docs/store-api/38777d33d92dc-quick-start-guide) for customer-facing use cases such as:

* Working with products and listings
* Managing carts and checkout
* Building headless storefronts or mobile apps (requires a Sales Channel access key)
* Serving anonymous or authenticated customers

Base path: `/store-api/*`.

Local API reference: `/store-api/_info/stoplightio.html`

### Step 1: Verify that the instance is running

Open Storefront:

```text
http://127.0.0.1:8000
```

Open Admin:

```text
http://localhost:8000/admin
```

If both pages load, continue.

If `http://127.0.0.1:8000` does not work, open the Administration and go to `Sales Channels → Storefront (or your active channel) → Domains`. Add `http://127.0.0.1:8000` as an additional domain for that sales channel, then save your changes.

When running Shopware locally (e.g., via Docker), ensure the environment is in development mode for better error visibility. The default variable is `APP_ENV=dev`.

If running the command `docker compose exec web printenv APP_ENV` does not return `dev`, create or update the variable in the `.env.local` file. Then restart the container with `make up` (this step is required).

## Step 2: Get an Admin API access token

The Admin API uses OAuth with integration credentials.

First, create an integration in the Administration under **Settings → System → Integrations**. Ensure that the toggle is set to "Administrator" to enable integration permissions.

After creating the integration, copy these values:

* **Access key ID**: maps to the OAuth field `client_id`
* **Secret access key**: maps to the OAuth field `client_secret`

Use them to request an OAuth access token from your local Shopware instance:

```bash
curl -s "http://127.0.0.1:8000/api/oauth/token" \
 -H "Content-Type: application/json" \
  -d '{
 "grant_type": "client_credentials",
 "client_id": "YOUR_ACCESS_KEY_ID",
 "client_secret": "YOUR_SECRET_ACCESS_KEY"
 }'
```

A successful response returns JSON containing an `access_token` for authenticated Admin API requests. The payload will look like this:

```json
{
  "token_type": "Bearer",
  "expires_in": 3600,
  "access_token": "..."
}
```

Copy that value and use it as the Bearer token in Step 3. If the response does not appear immediately in your terminal, exit any nested shell session and retry in your normal shell.

If you only want to verify that the token request works, use `127.0.0.1:8000` consistently in your API examples, because it is often already configured by default in local setups.

## Step 3: Make an authenticated API request

After obtaining an access token, test your setup with a protected Admin API endpoint.

Replace `YOUR_ACCESS_TOKEN` with the fresh `access_token` returned in Step 2.

```bash
curl -X POST "http://127.0.0.1:8000/api/search/product" \
 -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
 -d '{}'
```

A successful response returns JSON with the search result. If your instance does not contain any products yet, the `data` array may be empty.

Use `127.0.0.1:8000` consistently in local API examples if that is the URL already configured in your local setup.

If the JSON response includes keys such as `data`, `meta`, and `aggregations`, your request was successful. If `data` is empty, the request still succeeded, but your instance does not yet contain any matching products.

## Step 4: Access the Store API

The [Store API](../../../concepts/api/store-api.md) uses a sales channel access key. Use this key to authenticate Store API requests - for example, when fetching product or category data from an external app, headless storefront, or API client.

Open the Administration and go to **Sales Channels → Storefront (or your active sales channel)**. In the **API access** section, copy the **API access key** for that sales channel.

If needed, you can generate a new API key there. Be aware that generating a new key invalidates the old one.

Use the access key in the `sw-access-key` header when calling the Store API:

```bash
curl -s "http://127.0.0.1:8000/store-api/product" \
 -H "sw-access-key: YOUR_ACCESS_KEY"
```

If the API returns JSON, the request was successful. An empty `elements` array means the request worked, but no products were found yet.

## Step 5: Work with data

Both APIs share the same core concepts:

* Search criteria such as filtering, sorting, and pagination
* Context-aware responses based on permissions or sales channel state

These concepts define how data is filtered, structured, and returned.

For architectural background, see the [API overview](./../../../concepts/api/index.md).

## Result

At this point, you should be able to:

* Authenticate with the Admin API
* Make authenticated API requests
* Access data from your Shopware instance

## Next step

Continue with your first real integration: [Authentication and API Requests](./auth-api-requests.md)

---

---
url: /docs/guides/plugins/apps/app-base-guide.md
---

# App Base Guide

## Overview

This guide covers the common foundation that every Shopware app starts with, then shows you where the implementation diverges. For general context, read the [App concept](../../../concepts/extensions/apps-concept.md).

There are multiple ways to begin building a Shopware app, but not all of them fit every use case. This guide focuses on the shared foundation that applies to all apps:

* create an app folder in `custom/apps`
* add a valid `manifest.xml`
* refresh the app registry
* install and activate the app

From there, continue with the path that matches your goal:

* **Apps requiring a backend:** apps that need registration, authenticated server-to-server communication, webhooks, signing, Admin API credentials and permissions, payment methods, tax providers, or other backend-driven features. See [App registration & backend setup](../apps/lifecycle/app-registration-setup.md) after you have a valid manifest.
* **Admin UI apps:** apps whose immediate goal is to add an Administration UI and iterate locally first with Vite and [Admin Extension SDK](https://www.npmjs.com/package/@shopware-ag/admin-extension-sdk). No app backend is required to see a module in the Administration. Continue with [Build an Admin UI app](create-admin-extension.md).

## Prerequisites

* Shopware running locally.
* Access to the Administration: `http://localhost:8000/admin`.
* Shell access to the PHP container for `bin/console`.

A Shopware app is defined by a `manifest.xml`, discovered from `custom/apps`, and managed through the CLI and the Administration.

## Name your app

Choose a technical name in UpperCamelCase, for example `MyExampleApp`, that reflects what the app does, for example `PaymentGatewayApp`.

## File structure

Apps live in `custom/apps` inside your Shopware project. Each app lives in its own folder and includes a manifest file. Example:

```text
└── custom
    ├── apps
    │   └── MyExampleApp
    │       └── manifest.xml
    └── plugins
```

## Manifest file

::: warning
The folder name and the `<meta><name>` in `manifest.xml` must match.
:::

The manifest is the contract between Shopware and your app. See [Manifest reference](../../../resources/references/app-reference/manifest-reference.md) for more details.

A typical meta block:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        <name>MyExampleApp</name>
        <label>Label</label>
        <label lang="de-DE">Name</label>
        <description>A description</description>
        <description lang="de-DE">Eine Beschreibung</description>
        <author>Your Company Ltd.</author>
        <copyright>(c) by Your Company Ltd.</copyright>
        <version>1.0.0</version>
        <icon>Resources/config/plugin.png</icon>
        <license>MIT</license>
    </meta>
</manifest>
```

::: warning
`<author>` and `<copyright>` are required. If they are missing or empty, `bin/console app:refresh` fails.
:::

## Install and refresh (CLI)

Run commands from the project root inside the PHP container, for example `/var/www/html`.

For any app you create manually under `custom/apps/<Name>/`, refresh the registry first:

```bash
bin/console app:refresh
```

If `app:refresh` reports validation errors, fix them and run the command again.

Install the app using its technical name (`<meta><name>`), not a filesystem path:

```bash
bin/console app:install --activate MyExampleApp
```

If the app does not appear as expected, check the current app list:

```bash
bin/console app:list
```

::: info
Without the `--activate` flag, the app is installed inactive. Activate it in the Administration (**Extensions → My Extensions → Apps**) or run `bin/console app:activate MyExampleApp`.
:::

## Cache

After activating an app, you might need to clear the cache for the changes to take effect:

```bash
bin/console cache:clear
```

If needed, also run `bin/console cache:clear:http` or `bin/console cache:clear:all`.

Apps are [validated](./lifecycle/app-registration-setup.md#validation) during installation. To skip validation only while debugging, use `--no-validate` with `app:install`. Run `bin/console app:validate` to identify configuration issues.

---

---
url: /docs/v6.5/guides/plugins/apps/app-base-guide.md
---

# App Base Guide

## Overview

This guide will walk you through the process of adding your own app to Shopware and configuring it to be able to communicate with your external backend server.

## Prerequisites

If you are not familiar with the app system, take a look at the [App concept](../../../concepts/extensions/apps-concept) first.

## Name your app

Choose a technical name for your application that accurately reflects its plugin functionality. Specify the name using UpperCamelCase. For instance: "PaymentGatewayApp".

However, through out this section "MyExampleApp" is used as it serves as an illustrative example of the plugin.

## File structure

To get started with your app, create an `apps` folder inside the `custom` folder of your Shopware dev installation. In there, create another folder for your application and provide a manifest file in it.

```text
└── custom
    ├── apps
    │   └── MyExampleApp
    │       └── manifest.xml
    └── plugins
```

## Manifest file

The manifest file is the central point of your app. It defines the interface between your app and the Shopware instance. It provides all the information concerning your app, as seen in the minimal version below:

```xml
// manifest.xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        <name>MyExampleApp</name>
        <label>Label</label>
        <label lang="de-DE">Name</label>
        <description>A description</description>
        <description lang="de-DE">Eine Beschreibung</description>
        <author>Your Company Ltd.</author>
        <copyright>(c) by Your Company Ltd.</copyright>
        <version>1.0.0</version>
        <icon>Resources/config/plugin.png</icon>
        <license>MIT</license>
    </meta>
</manifest>
```

::: warning
The name of your app that you provide in the manifest file needs to match the folder name of your app.
:::

The app can now be installed and activated by running the following command:

```bash
bin/console app:install --activate MyExampleApp
```

By default, your app files will be [validated](app-base-guide#validation) before installation. To skip the validation, you may use the `--no-validate` flag.

::: info
Without the `--activate` flag the Apps get installed as inactive. By executing the `app:activate` command after installation this can be activated, too.
:::

For a complete reference of the structure of the manifest file, take a look at the [Manifest reference](../../../resources/references/app-reference/manifest-reference).

## Setup (optional)

::: info
Only if your app backend server and Shopware need to communicate, it is necessary that registration is performed during the installation of your app. This process is called setup.
:::

During the setup, it is verified that Shopware connects to the right backend server and keys are exchanged to secure all further communications.
During the setup process, your app backend will obtain credentials that can be used to authenticate against the Shopware API.
Additionally, your app will provide a secret that Shopware will use to sign all further requests it makes to your app backend, allowing you to verify that the incoming requests originate from authenticated Shopware installations.

The setup workflow is shown in the following schema. Each step will be explained in detail.

![Setup request workflow](../../../assets/plugins-apps-appBaseGuide.svg)

::: info
The timeout for the requests against the app server is 5 seconds.
:::

## SDK Integration

Integrating apps into your application can be a daunting task, but with our PHP SDK, the process becomes much easier. Our SDK simplifies the registration flow and other typical tasks.

* [Official PHP SDK](app-sdks/php/01-getting_started)
* [Official Symfony Bundle](app-sdks/symfony-bundle/index)

If there is no SDK available for your language, you can implement the registration process by yourself.

### Registration request

The registration request is made as a `GET` request against a URL you provide in your app's manifest file.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        ...
    </meta>
    <setup>
        <!-- The URL which will be used for the registration -->
        <registrationUrl>https://my.example.com/registration</registrationUrl>
        <!-- Dev only, the secret that is used to sign the registration request -->
        <secret>mysecret</secret>
    </setup>
</manifest>

```

The following query parameters will be sent with the request:

* `shop-id`: The unique identifier of the shop the app was installed.
* `shop-url`: The URL of the shop, this can later be used to access the Shopware API.
* `timestamp`: The Unix timestamp when the request was created.

Additionally, the request has the following headers:

* `shopware-app-signature`: The signature of the query string
* `sw-version`: The Shopware version of the shop *(since 6.4.1.0)*

An example request looks like this:

```txt
GET https://my.example.com/registration?shop-id=KIPf0Fz6BUkN&shop-url=http%3A%2F%2Fmy.shop.com&timestamp=159239728
shopware-app-signature: a8830aface4ac4a21be94844426e62c77078ca9a10f694737b75ca156b950a2d
sw-version: 6.4.5.0
```

Additionally, the `shopware-app-signature` header will be provided, which contains a cryptographic signature of the query string.\
The secret used to generate this signature is the `app secret`, which is unique per app and will be provided by the Shopware Account if you upload your app to the store. This secret won't leave the Shopware Account, so it won't even be leaked to the shops installing your app.

::: danger
You and the Shopware Account are the only parties that should know your `app-secret`. Therefore, make sure you never accidentally publish your `app-secret`.
:::

::: warning
For **local development**, you can specify a `<secret>` in the manifest file that is used for signing the registration request. However, if an app uses a hard-coded secret in the manifest, it can't be uploaded to the store.

If you are developing a **private app** not published in the Shopware Store, you **must** provide the `<secret>` in case of an external app server.
:::

To verify that the registration can only be triggered by authenticated Shopware shops, you need to recalculate the signature and check that the signatures match. Thus, you have verified that the sender of the request possesses the `app secret`.

The following code snippet can be used to recalculate the signature:

```php
use Psr\Http\Message\RequestInterface;

/** @var RequestInterface $request */
$queryString = $request->getUri()->getQuery();
$signature = hash_hmac('sha256', $queryString, $appSecret);
```

```php
$verifier = new \Shopware\App\SDK\Authentication\RequestVerifier();
$verifier->authenticateRegistrationRequest($request, new AppConfiguration('AppName', 'AppSecret', 'confirm-url'));
```

The Symfony Bundle handles all verification automatically.

### Registration response

There may be valid cases where the app installation fails because the domain is blocked or some other prerequisite in that shop is not met, in which case you can return the message error as follows:

```json
{
  "error": "The shop URL is invalid"
}
```

When the registration is successful.
To verify that you are also in possession of the `app secret`, you need to provide proof that it is signed with the `app secret` too. The proof consists of the sha256 hmac of the concatenated `shopId`, `shopUrl`, and your app's name.

The following code snippet can be used to calculate the proof:

```php
use Psr\Http\Message\RequestInterface;

/** @var RequestInterface $request */
$queryString = $request->getUri()->getQuery();
parse_str($queryString, $queryValues);
$proof = \hash_hmac(
    'sha256',
    $queryValues['shop-id'] . $queryValues['shop-url'] . $appname,
    $appSecret
);
```

```php
$signer = new ResponseSigner();
$signer->getRegistrationSignature(new AppConfiguration('AppName', 'AppSecret', 'confirm-url'), $shop);
```

Besides the proof, your app needs to provide a randomly generated secret that should be used to sign every further request from this shop. Make sure to save the `shopId`, `shopUrl`, and generated secret so that you can associate and use this information later.

::: info
This secret will be called \`shop-secret\` to distinguish it from the \`app-secret\`. The \`app-secret\` is unique to your app and is used to sign the registration request of every shop that installs your app. The \`shop-secret\` will be provided by your app during the registration and should be unique for every shop and have a minimum length of 64 characters and maximum length of 255 characters.
:::

The last thing needed in the registration response is a URL to which the confirmation request will be sent.

A sample registration response looks like this:

```json
{
  "proof": "94b42d39280141de84bd6fc8e538946ccdd182e4558f1e690eabb94f924e7bc7",
  "secret": "random secret string",
  "confirmation_url": "https://my.example.com/registration/confirm"
}
```

### Confirmation request

If the proof you provided in the [registration response](app-base-guide#registration-response) matches the one generated on the shop side, the registration is completed. As a result, your app will receive a `POST` request against the URL specified as the `confirmation_url` of the registration with the following parameters send in the request body:

* `apiKey`: The API key used to authenticate against the Shopware Admin API.
* `secretKey`: The secret key used to authenticate against the Shopware Admin API.
* `timestamp`: The Unix timestamp when the request was created.
* `shopUrl`: The URL of the shop.
* `shopId`: The unique identifier of the shop.

The payload of that request may look like this:

```json
{
  "apiKey":"SWIARXBSDJRWEMJONFK2OHBNWA",
  "secretKey":"Q1QyaUg3ZHpnZURPeDV3ZkpncXdSRzJpNjdBeWM1WWhWYWd0NE0",
  "timestamp":"1592398983",
  "shopUrl":"http:\/\/my.shop.com",
  "shopId":"sqX6cqHi6hbj"
}
```

Make sure that you save the API credentials for that `shopId`. You can use the `apiKey` and the `secretKey` as `client_id` and `client_secret`, respectively, when you request an OAuth token
from the Admin API.

You can find out more about how to use these credentials in our Admin API authentication guide:

::: info
Starting from Shopware version 6.4.1.0, the current Shopware version will be sent as a `sw-version` header.
Starting from Shopware version 6.4.5.0, the current language id of the Shopware context will be sent as a  `sw-context-language` header, and the locale of the user or locale of the context language is available under the `sw-user-language` header.
:::

The request is signed with the `shop-secret` that your app provided in the [registration response](app-base-guide#registration-response) and the signature can be found in the `shopware-shop-signature` header.\
You need to recalculate that signature and check that it matches the provided one to make sure that the request is really sent from the shop with that shopId.

You can use the following code snippet to generate the signature:

```php
use Psr\Http\Message\RequestInterface;

/** @var RequestInterface $request */
$hmac = \hash_hmac('sha256', $request->getBody()->getContents(), $shopSecret);
```

## Permissions

Shopware comes with the possibility to create fine-grained [Access Control Lists](../plugins/administration/add-acl-rules) (ACLs). It means you need to request permissions if your app needs to read or write data over the API or wants to receive webhooks. The permissions your app needs are defined in the manifest file and are composed of the privilege (`read`, `create`, `update`, `delete`) and the entity.
Since version 6.4.12.0, your app can also request additional non-CRUD privileges with the `<permission>` element.

Sample permissions to read, create and update products, delete orders, as well as reading the cache configuration look like this:

```xml
// manifest.xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        ...
    </meta>
    <permissions>
        <read>product</read>
        <create>product</create>
        <update>product</update>

        <delete>order</delete>

        <!-- Since version 6.4.12.0 your app can request additional non-CRUD privileges-->
        <permission>system:cache:info</permission>
    </permissions>
</manifest>
```

The permissions you request need to be accepted by the user during the installation of your app. After that, these permissions are granted for your app and your API access through the credentials from the [confirmation request](app-base-guide#confirmation-request) of the [setup workflow](app-base-guide#setup) are limited to those permissions.

::: warning
Keep in mind that read permissions also extend to the data contained in the requests, so your app needs read permissions for the entities contained in the subscribed [webhooks](./webhook).
:::

### App notification

Starting from Shopware version 6.4.7.0, if you want to send notifications to the admin to inform the user about some actions that happened on the app side, the app should send a `POST` request to the `api/notification` endpoint with a valid body and the header `Authorization` token.
Your app can request 10 times before being delayed by the system.

After 10 attempts, you need to wait 10 seconds before trying to make requests again.
After 15 attempts, it's 30 seconds.
After 20 attempts, it's 60 seconds.
After 24 hours without a failed request, the limit is reset.

Examples request body:
You need to pass the `status` property, the content of the notification as `message` property and you can restrict users who can read the notification by passing `requiredPrivileges` property and `adminOnly` property inside the payload.
When `adminOnly` is true, only admins can read this notification. If you don't send the `adminOnly` or `adminOnly` is false, you can pass the `requiredPrivileges` property so that users with specific permissions can read the notification. Otherwise, it will be displayed to every user.

```txt
POST /api/notification

{
    "status": "success",
    "message": "This is a successful message",
    "adminOnly": "true",
    "requiredPrivileges": []
}
```

* `status`: Notification status - `success`, `error`, `info`, `warning`.
* `message`: The content of the notification.
* `adminOnly`: Only admins can read this notification if this value is true.
* `requiredPrivileges`: The required privileges that users need to have to read the notification.

Remember that your app needs the `notification:create` permission to access this API.

### App lifecycle events

Apps can also register to lifecycle events of their own lifecycle, namely their installation, updates, and deletion. For example, they may be used to delete user relevant data from your data stores once somebody removes your app from their shop.

| Event             | Description                              |
|:------------------|:-----------------------------------------|
| `app.installed`   | Triggers once the app is installed       |
| `app.updated`     | Triggers if the app is updated           |
| `app.deleted`     | Triggers once the app is removed         |
| `app.activated`   | Triggers if an inactive app is activated |
| `app.deactivated` | Triggers if an active app is deactivated |

Example request body:

```json
{
  "data": {
    "payload": [],
    "event": "app_deleted"
  },
  "source": {
    "url": "http:\/\/localhost:8000",
    "appVersion": "0.0.1",
    "shopId": "wPNrYZgArBTL"
  }
}
```

```php
use Shopware\App\SDK\Shop\ShopResolver;
use Shopware\App\SDK\Context\ContextResolver;
use Shopware\App\SDK\Response\PaymentResponse;

function webhookController(RequestInterface $request): ResponseInterface
{
    // injected or build by yourself
    $shopResolver = new ShopResolver($repository);
    $contextResolver = new ContextResolver();
    
    $shop = $shopResolver->resolveShop($serverRequest);
    $webhook = $contextResolver->assembleWebhook($serverRequest, $shop);
    
    // do something with the parsed webhook
}
```

#### App lifecycle events for app scripts

Since Shopware 6.4.9.0, it is also possible to create [App scripts](./app-scripts/) that are executed during the lifecycle of your app.
You get access to the database and can change or create some data, e.g., when your app is activated, without needing an external server.

For a full list of the available hook points and the available services, refer to the [reference documentation](../../../resources/references/app-reference/script-reference/script-hooks-reference#app-lifecycle).

## Validation

You can run the `app:validate` command to validate the configuration of your app. It will check for common errors, like:

* non-matching app names
* missing translations
* unknown events registered as webhooks
* missing permissions for webhooks
* errors in the config.xml file, if it exists

To validate all apps in your `custom/apps` folder run:

```bash
bin/console app:validate
```

Additionally, you can specify which app should be validated by providing the app name as an argument;

```bash
bin/console app:validate MyExampleApp
```

## Handling the migration of shops

In the real world, it may happen that shops are migrated to new servers and are available under a new URL. In the same regard, it is possible that a running production shop is duplicated and treated as a staging environment.
These cases are challenging for app developers. In the first case, you may have to make a request against the shop, but the URL you saved during the registration process may not be valid anymore, and the shop cannot be reached over this URL.
In the second case, you may receive webhooks from both shops (prod & staging) that look like they came from the same shop (as the whole database was duplicated). Thus it may corrupt the data associated with the original production shop.
The main reason that this is problematic is that two Shopware installations in two different locations (on two different URLs) are associated with the same shopId, because the whole database was replicated.

That is why we implemented a safeguard mechanism that detects such situations, stops communication with the apps to prevent data corruption, and then ultimately lets the user decide how to solve the situation.

::: info
This mechanism relies on the fact that the `APP_URL` environment variable will be set to the correct URL for the shop. It is especially assumed that the environment variable will be changed when a shop is migrated to a new domain or a staging shop is created as a duplicate of a production shop.
:::

Remember that this is only relevant for apps that have their own backends and where communication between app backends and shopware is necessary. That is why simple themes are not affected by shop migrations, and they will continue to work.

### Detecting APP\_URL changes

Every time a request should be made against an app backend, Shopware will check whether the current APP\_URL differs from the one used when Shopware generated an ID for this shop.
If the APP\_URL differs, Shopware will stop sending any requests to the installed apps to prevent data corruption on the side of the apps.
Now the user has the possibility to resolve the solution by using one of the following strategies.
The user can either run a strategy with the `bin/console app:url-change:resolve` command, or with a modal that pops up when the Administration is opened.

### APP\_URL change resolver

* **MoveShopPermanently**: This strategy should be used if the live production shop is migrated from one URL to another one. This strategy will ultimately notify all apps about the change of the APP\_URL and the apps will continue working like before, including all the data the apps may already have associated with the given shop. It is important to notice that in this case, the apps in the old installation on the old URL (if it is still running) will stop working.

Technically, this is achieved by rerunning the registration process for all apps. During the registration, the same shopId is used as before, but now with a different shop-url and a different key pair used to communicate over the Shopware API. Also, you must generate a new communication secret during this registration process that is subsequently used to communicate between Shopware and the app backend.

This way, it is ensured that the apps are notified about the new URL and the integration with the old installation stops working because a new communication secret is associated with the given shopId that the old installation does not know.

* **ReinstallApps**: This strategy makes sense to use in the case of the staging shop. By running this strategy, all installed apps will be reinstalled. This means that this installation will get a new shopId, that is used during registration.

As the new installation will get a new shopId, the installed apps will continue working on the old installation as before, but as a consequence, the data on the app's side that was associated with the old shopId cannot be accessed on the new installation.

* **UninstallApps**: This strategy will simply uninstall all apps on the new installation, thus keeping the old installation working like before.

## API Docs

### Registration

`GET https://my.example.com`

#### Parameters

| Parameter               | Type    | Description                                                                               |
|-------------------------|---------|-------------------------------------------------------------------------------------------|
| **Query**               |         |                                                                                           |
| timestamp\*              | integer | The current Unix timestamp when the request was created                                   |
| shop-url\*               | string  | The URL of the shop where the app was installed can be used to access to the Shopware API |
| shop-id\*                | string  | The unique identifier of the shop, where the app was installed                            |
| **Header**              |         |                                                                                           |
| shopware-app-signature\* | string  | The hmac-signature of the query string, signed with the app secret                        |

#### Responses

`200`

```json
{
  "error": "The shop URL is invalid"
}
```

```json
{
  "proof": "94b42d39280141de84bd6fc8e538946ccdd182e4558f1e690eabb94f924e7bc7",
  "secret": "random secret string",
  "confirmation_url": "https://my.example.com/registration/confirm"
}
```

### Confirmation

`POST https://my.example.com`

#### Parameters

| Parameter                | Type    | Description                                                                                                                                                                                                                                                                                                                                                        |
|--------------------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Header**               |         |                                                                                                                                                                                                                                                                                                                                                                    |
| shopware-shop-signature\* | string  | The hmac-signature of the body content, signed with the shop secret returned from the registration request                                                                                                                                                                                                                                                         |
| sw-version\*              | string  | Starting from Shopware version 6.4.1.0, the current Shopware version will be sent as a `sw-version` header. Starting from Shopware version 6.4.5.0, the current language id of the Shopware context will be sent as a `sw-context-language` header, and the locale of the user or locale of the context language is available under the `sw-user-language` header. |
| **Body**                 |         |                                                                                                                                                                                                                                                                                                                                                                    |
| shopId\*                  | string  | The unique identifier of the shop                                                                                                                                                                                                                                                                                                                                  |
| shopUrl\*                 | string  | The URL of the shop                                                                                                                                                                                                                                                                                                                                                |
| timestamp\*               | integer | The current nix timestamp when the request was created                                                                                                                                                                                                                                                                                                             |
| secretKey\*               | string  | SecretKey used to authenticate against the Shopware API                                                                                                                                                                                                                                                                                                            |
| apiKey\*                  | string  | ApiKey used to authenticate against the Shopware API                                                                                                                                                                                                                                                                                                               |

#### Responses

`200`

---

---
url: /docs/v6.6/guides/plugins/apps/app-base-guide.md
---

# App Base Guide

## Overview

This guide will walk you through the process of adding your own app to Shopware and configuring it to be able to communicate with your external backend server.

## Prerequisites

If you are not familiar with the app system, take a look at the [App concept](../../../concepts/extensions/apps-concept) first.

## Name your app

Choose a technical name for your application that accurately reflects its plugin functionality.
Specify the name using UpperCamelCase. For instance: "PaymentGatewayApp".

However, throughout this section "MyExampleApp" is used as it serves as an illustrative example of the plugin.

## File structure

To get started with your app, create an `apps` folder inside the `custom` folder of your Shopware dev installation.
In there, create another folder for your application and provide a manifest file in it.

```text
└── custom
    ├── apps
    │   └── MyExampleApp
    │       └── manifest.xml
    └── plugins
```

## Manifest file

The manifest file is the central point of your app.
It defines the interface between your app and the Shopware instance.
It provides all the information concerning your app, as seen in the minimal version below:

::: code-group

```xml [manifest.xml]
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        <name>MyExampleApp</name>
        <label>Label</label>
        <label lang="de-DE">Name</label>
        <description>A description</description>
        <description lang="de-DE">Eine Beschreibung</description>
        <author>Your Company Ltd.</author>
        <copyright>(c) by Your Company Ltd.</copyright>
        <version>1.0.0</version>
        <icon>Resources/config/plugin.png</icon>
        <license>MIT</license>
    </meta>
</manifest>
```

:::

::: warning
The name of your app that you provide in the manifest file needs to match the folder name of your app.
:::

The app can now be installed and activated by running the following command:

```bash
bin/console app:install --activate MyExampleApp
```

After activating an app, you might need to clear the cache for the changes to take effect. First try:

```bash
bin/console cache:clear
```

If the changes are still not visible, try:

```bash
bin/console cache:clear:http
```

or

```bash
bin/console cache:clear:all
```

By default, your app files will be [validated](app-base-guide#validation) before installation.
To skip the validation, you may use the `--no-validate` flag.

::: info
Without the `--activate` flag the Apps get installed as inactive.
By executing the `app:activate` command after installation this can be activated, too.
:::

For a complete reference of the manifest file structure, take a look at the [Manifest reference](../../../resources/references/app-reference/manifest-reference).

## Setup (optional)

::: info
Only if your app backend server and Shopware need to communicate, it is necessary that registration is performed during the installation of your app.
This process is called setup.
:::

::: warning
Suppose your app makes use of the Admin Module, Payment Method, Tax providers or Webhook app system features.
In that case, you need to implement the registration, to exchange a secret key; that is later used to authenticate the shops.
:::

During the setup, it is verified that Shopware connects to the right backend server and keys are exchanged to secure all further communications.
During the setup process, your app backend will get credentials that can be used to authenticate against the Shopware API.
Additionally, your app will provide a secret that Shopware will use to sign all further requests it makes to your app backend, allowing you to verify that the incoming requests originate from authenticated Shopware installations.

The setup workflow is shown in the following schema.
Each step will be explained in detail.

![Setup request workflow](../../../assets/plugins-apps-appBaseGuide.svg)

::: info
The timeout for the requests against the app server is 5 seconds.
:::

### SDK Integration

Integrating apps into your application can be a daunting task, but with our PHP SDK, the process becomes much easier.
Our SDK simplifies the registration flow and other typical tasks.

* [Official PHP SDK](app-sdks/php/01-getting_started)
* [Official Symfony Bundle](app-sdks/symfony-bundle/index)

If there is no SDK available for your language, you can implement the registration process by yourself.

### Registration request

The registration request is made as a `GET` request against a URL you provide in your app's manifest file.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        ...
    </meta>
    <setup>
        <!-- The URL which will be used for the registration -->
        <registrationUrl>https://my.example.com/registration</registrationUrl>
        <!-- Dev only, the secret that is used to sign the registration request -->
        <secret>mysecret</secret>
    </setup>
</manifest>

```

The following query parameters will be sent with the request:

* `shop-id`: The unique identifier of the shop the app was installed.
* `shop-url`: The URL of the shop, this can later be used to access the Shopware API.
* `timestamp`: The Unix timestamp when the request was created.

Additionally, the request has the following headers:

* `shopware-app-signature`: The signature of the query string
* `sw-version`: The Shopware version of the shop *(since 6.4.1.0)*

An example request looks like this:

```txt
GET https://my.example.com/registration?shop-id=KIPf0Fz6BUkN&shop-url=http%3A%2F%2Fmy.shop.com&timestamp=159239728
shopware-app-signature: a8830aface4ac4a21be94844426e62c77078ca9a10f694737b75ca156b950a2d
sw-version: 6.4.5.0
```

Additionally, the `shopware-app-signature` header will be provided, which contains a cryptographic signature of the query string.\
The secret used to generate this signature is the `app secret`, which is unique per app and will be provided by the Shopware Account if you upload your app to the store.
This secret won't leave the Shopware Account, so it won't even be leaked to the shops installing your app.

::: danger
You and the Shopware Account are the only parties that should know your `app-secret`.
Therefore, make sure you never accidentally publish your `app-secret`.
:::

::: warning
For **local development**, you can specify a `<secret>` in the manifest file that is used for signing the registration request.
However, if an app uses a hard-coded secret in the manifest, it can't be uploaded to the store.

If you are developing a **private app** not published in the Shopware Store, you **must** provide the `<secret>` in case of an external app server.
:::

To verify that the registration can only be triggered by authenticated Shopware shops, you need to recalculate the signature and check that the signatures match.
Thus, you have verified that the sender of the request possesses the `app secret`.

The following code snippet can be used to recalculate the signature:

```php
use Psr\Http\Message\RequestInterface;

/** @var RequestInterface $request */
$queryString = $request->getUri()->getQuery();
$signature = hash_hmac('sha256', $queryString, $appSecret);
```

```php
$verifier = new \Shopware\App\SDK\Authentication\RequestVerifier();
$verifier->authenticateRegistrationRequest($request, new AppConfiguration('AppName', 'AppSecret', 'confirm-url'));
```

The Symfony Bundle handles all verification automatically.

### Registration response

There may be valid cases where the app installation fails because the domain is blocked or some other prerequisite in that shop is not met, in which case you can return the message error as follows:

```json
{
  "error": "The shop URL is invalid"
}
```

When the registration is successful.
To verify that you are also in possession of the `app secret`, you need to provide proof that it is signed with the `app secret` too.
The proof consists of the sha256 hmac of the concatenated `shopId`, `shopUrl`, and your app's name.

The following code snippet can be used to calculate the proof:

```php
use Psr\Http\Message\RequestInterface;

/** @var RequestInterface $request */
$queryString = $request->getUri()->getQuery();
parse_str($queryString, $queryValues);
$proof = \hash_hmac(
    'sha256',
    $queryValues['shop-id'] . $queryValues['shop-url'] . $appname,
    $appSecret
);
```

```php
$signer = new ResponseSigner();
$signer->getRegistrationSignature(new AppConfiguration('AppName', 'AppSecret', 'confirm-url'), $shop);
```

For detailed instructions on signing requests and responses, refer to the app signing guide.

Besides the proof, your app needs to provide a randomly generated secret that should be used to sign every further request from this shop.
Make sure to save the `shopId`, `shopUrl`, and generated secret so that you can associate and use this information later.

::: info
This secret will be called \`shop-secret\` to distinguish it from the \`app-secret\`.
The \`app-secret\` is unique to your app and is used to sign the registration request of every shop that installs your app.
The \`shop-secret\` will be provided by your app during the registration and should be unique for every shop and have a minimum length of 64 characters and maximum length of 255 characters.
:::

The last thing needed in the registration response is a URL to which the confirmation request will be sent.

A sample registration response looks like this:

```json
{
  "proof": "94b42d39280141de84bd6fc8e538946ccdd182e4558f1e690eabb94f924e7bc7",
  "secret": "random secret string",
  "confirmation_url": "https://my.example.com/registration/confirm"
}
```

### Confirmation request

If the proof you provided in the [registration response](app-base-guide#registration-response) matches the one generated on the shop side, the registration is completed.
As a result, your app will receive a `POST` request against the URL specified as the `confirmation_url` of the registration with the following parameters send in the request body:

* `apiKey`: The API key used to authenticate against the Shopware Admin API.
* `secretKey`: The secret key used to authenticate against the Shopware Admin API.
* `timestamp`: The Unix timestamp when the request was created.
* `shopUrl`: The URL of the shop.
* `shopId`: The unique identifier of the shop.

The payload of that request may look like this:

```json
{
  "apiKey":"SWIARXBSDJRWEMJONFK2OHBNWA",
  "secretKey":"Q1QyaUg3ZHpnZURPeDV3ZkpncXdSRzJpNjdBeWM1WWhWYWd0NE0",
  "timestamp":"1592398983",
  "shopUrl":"http:\/\/my.shop.com",
  "shopId":"sqX6cqHi6hbj"
}
```

Make sure that you save the API credentials for that `shopId`.
You can use the `apiKey` and the `secretKey` as `client_id` and `client_secret`, respectively, when you request an OAuth token from the Admin API.

You can find out more about how to use these credentials in our Admin API authentication guide:

::: info
Starting from Shopware version 6.4.1.0, the current Shopware version will be sent as a `sw-version` header.
Starting from Shopware version 6.4.5.0, the current language id of the Shopware context will be sent as a  `sw-context-language` header, and the locale of the user or locale of the context language is available under the `sw-user-language` header.
:::

The request is signed with the `shop-secret` that your app provided in the [registration response](app-base-guide#registration-response) and the signature can be found in the `shopware-shop-signature` header.\
You need to recalculate that signature and check that it matches the provided one to make sure that the request is really sent from the shop with that shopId.

You can use the following code snippet to generate the signature:

```php
use Psr\Http\Message\RequestInterface;

/** @var RequestInterface $request */
$hmac = \hash_hmac('sha256', $request->getBody()->getContents(), $shopSecret);
```

## Permissions

Shopware comes with the possibility to create fine-grained [Access Control Lists](../plugins/administration/add-acl-rules) (ACLs).
It means you need to request permissions if your app needs to read or write data over the API or wants to receive webhooks.
The permissions your app needs are defined in the manifest file and are composed of the privilege (`read`, `create`, `update`, `delete`) and the entity.
Since version 6.4.12.0, your app can also request additional non-CRUD privileges with the `<permission>` element.

Sample permissions to read, create and update products, delete orders, as well as reading the cache configuration look like this:

::: code-group

```xml [manifest.xml]
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        ...
    </meta>
    <permissions>
        <read>product</read>
        <create>product</create>
        <update>product</update>

        <delete>order</delete>

        <!-- Since version 6.4.12.0 your app can request additional non-CRUD privileges-->
        <permission>system:cache:info</permission>
    </permissions>
</manifest>
```

:::

The permissions you request need to be accepted by the user during the installation of your app.
After that, these permissions are granted for your app and your API access through the credentials from the [confirmation request](app-base-guide#confirmation-request) of the [setup workflow](app-base-guide#setup) are limited to those permissions.

::: warning
Keep in mind that read permissions also extend to the data contained in the requests, so your app needs read permissions for the entities contained in the subscribed [webhooks](./webhook).
:::

### App notification

Starting from Shopware version 6.4.7.0, if you want to send notifications to the admin to inform the user about some actions that happened on the app side,
the app should send a `POST` request to the `api/notification` endpoint with a valid body and the header `Authorization` token.
Your app can request 10 times before being delayed by the system.

After 10 attempts, you need to wait 10 seconds before trying to make requests again.
After 15 attempts, it's 30 seconds.
After 20 attempts, it's 60 seconds.
After 24 hours without a failed request, the limit is reset.

Examples request body:
You need to pass the `status` property, the content of the notification as `message` property,
and you can restrict users who can read the notification by passing `requiredPrivileges` property and `adminOnly` property inside the payload.
When `adminOnly` is true, only admins can read this notification.
If you don't send the `adminOnly` or `adminOnly` is false, you can pass the `requiredPrivileges` property so that users with specific permissions can read the notification.
Otherwise, it will be displayed to every user.

```txt
POST /api/notification

{
    "status": "success",
    "message": "This is a successful message",
    "adminOnly": "true",
    "requiredPrivileges": []
}
```

* `status`: Notification status - `success`, `error`, `info`, `warning`.
* `message`: The content of the notification.
* `adminOnly`: Only admins can read this notification if this value is true.
* `requiredPrivileges`: The required privileges that users need to have to read the notification.

Remember that your app needs the `notification:create` permission to access this API.

### App lifecycle events

Apps can also register to lifecycle events of their own lifecycle, namely their installation, updates, and deletion.
For example, they may be used to delete user relevant data from your data stores once somebody removes your app from their shop.

| Event             | Description                              |
|:------------------|:-----------------------------------------|
| `app.installed`   | Triggers once the app is installed       |
| `app.updated`     | Triggers if the app is updated           |
| `app.deleted`     | Triggers once the app is removed         |
| `app.activated`   | Triggers if an inactive app is activated |
| `app.deactivated` | Triggers if an active app is deactivated |

Example request body:

```json
{
  "data": {
    "payload": [],
    "event": "app_deleted"
  },
  "source": {
    "url": "http:\/\/localhost:8000",
    "appVersion": "0.0.1",
    "shopId": "wPNrYZgArBTL"
  }
}
```

```php
use Shopware\App\SDK\Shop\ShopResolver;
use Shopware\App\SDK\Context\ContextResolver;
use Shopware\App\SDK\Response\PaymentResponse;

function webhookController(RequestInterface $request): ResponseInterface
{
    // injected or build by yourself
    $shopResolver = new ShopResolver($repository);
    $contextResolver = new ContextResolver();

    $shop = $shopResolver->resolveShop($serverRequest);
    $webhook = $contextResolver->assembleWebhook($serverRequest, $shop);

    // do something with the parsed webhook
}
```

#### App lifecycle events for app scripts

Since Shopware 6.4.9.0, it is also possible to create [App scripts](./app-scripts/) that are executed during the lifecycle of your app.
You get access to the database and can change or create some data, e.g., when your app is activated, without needing an external server.

For a full list of the available hook points and the available services, refer to the [reference documentation](../../../resources/references/app-reference/script-reference/script-hooks-reference#app-lifecycle).

## Validation

You can run the `app:validate` command to validate the configuration of your app. It will check for common errors, like:

* non-matching app names
* missing translations
* unknown events registered as webhooks
* missing permissions for webhooks
* errors in the config.xml file, if it exists

To validate all apps in your `custom/apps` folder run:

```bash
bin/console app:validate
```

Additionally, you can specify which app should be validated by providing the app name as an argument;

```bash
bin/console app:validate MyExampleApp
```

## Handling the migration of shops

In the real world, it may happen that shops are migrated to new servers and are available under a new URL.
In the same regard, it is possible that a running production shop is duplicated and treated as a staging environment.
These cases are challenging for app developers.
In the first case, you may have to make a request against the shop, but the URL you saved during the registration process may not be valid anymore, and the shop cannot be reached over this URL.
In the second case, you may receive webhooks from both shops (prod & staging) that look like they came from the same shop (as the whole database was duplicated).
Thus, it may corrupt the data associated with the original production shop.
The main reason that this is problematic is that two Shopware installations in two different locations (on two different URLs) are associated with the same shopId, because the whole database was replicated.

That is why we implemented a safeguard mechanism that detects such situations, stops communication with the apps to prevent data corruption,
and then ultimately lets the user decide how to solve the situation.

::: info
This mechanism relies on the fact that the `APP_URL` environment variable will be set to the correct URL for the shop.
It is especially assumed that the environment variable will be changed when a shop is migrated to a new domain or a staging shop is created as a duplicate of a production shop.
:::

Remember that this is only relevant for apps that have their own backends and where communication between app backends and shopware is necessary.
That is why simple themes are not affected by shop migrations, and they will continue to work.

### Detecting APP\_URL changes

Every time a request should be made against an app backend, Shopware will check whether the current APP\_URL differs from the one used when Shopware generated an ID for this shop.
If the APP\_URL differs, Shopware will stop sending any requests to the installed apps to prevent data corruption on the side of the apps.
Now the user has the possibility to resolve the solution by using one of the following strategies.
The user can either run a strategy with the `bin/console app:url-change:resolve` command, or with a modal that pops up when the Administration is opened.

### APP\_URL change resolver

* **MoveShopPermanently**: This strategy should be used if the live production shop is migrated from one URL to another one.
  This strategy will ultimately notify all apps about the change of the APP\_URL and the apps will continue working like before,
  including all the data the apps may already have associated with the given shop.
  It is important to notice that in this case, the apps in the old installation on the old URL (if it is still running) will stop working.

Technically, this is achieved by rerunning the registration process for all apps.
During the registration, the same shopId is used as before, but now with a different shop-url and a different key pair used to communicate over the Shopware API.
Also, you must generate a new communication secret during this registration process that is subsequently used to communicate between Shopware and the app backend.

This way, it is ensured that the apps are notified about the new URL and the integration with the old installation stops working,
because a new communication secret is associated with the given shopId that the old installation does not know.

* **ReinstallApps**: This strategy makes sense to use in the case of the staging shop.
  By running this strategy, all installed apps will be reinstalled.
  This means that this installation will get a new shopId, that is used during registration.

As the new installation will get a new shopId, the installed apps will continue working on the old installation as before,
but as a consequence, the data on the app's side that was associated with the old shopId cannot be accessed on the new installation.

* **UninstallApps**: This strategy will simply uninstall all apps on the new installation, thus keeping the old installation working like before.

## API Docs

### Registration

`GET https://my.example.com`

#### Parameters

| Parameter               | Type    | Description                                                                               |
|-------------------------|---------|-------------------------------------------------------------------------------------------|
| **Query**               |         |                                                                                           |
| timestamp\*              | integer | The current Unix timestamp when the request was created                                   |
| shop-url\*               | string  | The URL of the shop where the app was installed can be used to access to the Shopware API |
| shop-id\*                | string  | The unique identifier of the shop, where the app was installed                            |
| **Header**              |         |                                                                                           |
| shopware-app-signature\* | string  | The hmac-signature of the query string, signed with the app secret                        |

#### Responses

`200`

```json
{
  "error": "The shop URL is invalid"
}
```

```json
{
  "proof": "94b42d39280141de84bd6fc8e538946ccdd182e4558f1e690eabb94f924e7bc7",
  "secret": "random secret string",
  "confirmation_url": "https://my.example.com/registration/confirm"
}
```

### Confirmation

`POST https://my.example.com`

#### Parameters

| Parameter                | Type    | Description                                                                                                                                                                                                                                                                                                                                                        |
|--------------------------|---------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| **Header**               |         |                                                                                                                                                                                                                                                                                                                                                                    |
| shopware-shop-signature\* | string  | The hmac-signature of the body content, signed with the shop secret returned from the registration request                                                                                                                                                                                                                                                         |
| sw-version\*              | string  | Starting from Shopware version 6.4.1.0, the current Shopware version will be sent as a `sw-version` header. Starting from Shopware version 6.4.5.0, the current language id of the Shopware context will be sent as a `sw-context-language` header, and the locale of the user or locale of the context language is available under the `sw-user-language` header. |
| **Body**                 |         |                                                                                                                                                                                                                                                                                                                                                                    |
| shopId\*                  | string  | The unique identifier of the shop                                                                                                                                                                                                                                                                                                                                  |
| shopUrl\*                 | string  | The URL of the shop                                                                                                                                                                                                                                                                                                                                                |
| timestamp\*               | integer | The current nix timestamp when the request was created                                                                                                                                                                                                                                                                                                             |
| secretKey\*               | string  | SecretKey used to authenticate against the Shopware API                                                                                                                                                                                                                                                                                                            |
| apiKey\*                  | string  | ApiKey used to authenticate against the Shopware API                                                                                                                                                                                                                                                                                                               |

#### Responses

`200`

---

---
url: /docs/v6.5/guides/plugins/apps/app-sdks/symfony-bundle.md
---

# App Bundle

App Bundle integrates the PHP App SDK for Symfony. This can be accessed at [app-bundle-symfony](https://github.com/shopware/app-bundle-symfony).

## Installation

```bash
composer require shopware/app-bundle
```

## Quick Start

### 1. Create a new Symfony Project (skip if existing)

```bash
composer create-project symfony/skeleton:"6.2.*" my-app
```

### 2. Install the App Bundle in your Symfony Project

```bash
composer require shopware/app-bundle
```

It is also recommended to install the monolog bundle to have logging:

```bash
composer require logger
```

### 3. Create a new App manifest

Here is an example app manifest

```xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        <name>TestApp</name>
        <label>TestApp</label>
        <label lang="de-DE">TestApp</label>
        <description/>
        <description lang="de-DE"/>
        <author>Your Company</author>
        <copyright>(c) by Your Company</copyright>
        <version>1.0.0</version>
        <icon>Resources/config/plugin.png</icon>
        <license>MIT</license>
    </meta>
    <setup>
        <registrationUrl>http://localhost:8000/app/lifecycle/register</registrationUrl>
        <secret>TestSecret</secret>
    </setup>
    <webhooks>
        <webhook name="appActivated" url="http://localhost:8000/app/lifecycle/activate" event="app.activated"/>
        <webhook name="appDeactivated" url="http://localhost:8000/app/lifecycle/deactivate" event="app.deactivated"/>
        <webhook name="appDeleted" url="http://localhost:8000/app/lifecycle/delete" event="app.deleted"/>
    </webhooks>
</manifest>
```

change the app name and the app secret to your needs
and also adjust the environment variables inside your `.env` file to match them.

By default, the following routes are registered:

* `/app/lifecycle/register` - Register the app
* `/app/lifecycle/activate` - Activate the app
* `/app/lifecycle/deactivate` - Deactivate the app
* `/app/lifecycle/delete` - Delete the app

You can change the prefix by editing the `config/routes/shopware_app.yaml` file.

The registration also dispatches events to react to the different lifecycle events. See APP SDK docs for it

### 4. Connecting Doctrine to a Database

The App Bundle ships with a basic Shop entity to store the shop information. You can extend this entity to store more information about your app if needed.

Symfony configures doctrine to use PostgreSQL by default. Change the `DATABASE_URL` environment variable in your `.env` file if you want to use MySQL.
You can also use SQLite by setting the `DATABASE_URL` to `sqlite:///%kernel.project_dir%/var/app.db` for development.

After choosing your database engine, you need to require two extra composer packages.

```shell
composer req symfony/maker-bundle migrations
```

And create your first migration using `bin/console make:migration` (which is using the `AbstractShop` Class) and apply it to your database with `bin/console doctrine:migrations:migrate`.

### 5. Implement first ActionButtons, Webhooks, Payment

[Check out the official app documentation to learn more about the different integration points with this SDK](/docs/guides/plugins/apps/app-base-guide.md#sdk-integration).

You can also check out the [APP SDK](https://github.com/shopware/app-php-sdk) documentation.

### Optional: Webhook as Symfony Events

The app bundle also registers a generic webhook controller, which dispatches the webhook as a Symfony event.
To use that, register your Shopware webhooks to the generic webhook, which is by default `/app/webhook`.

```xml
<webhook name="productWritten" url="http://localhost:8000/app/webhook" event="product.written"/>
```

With that, you can write a Symfony EventListener/Subscriber to listen to and react to the event.

```php
#[AsEventListener(event: 'webhook.product.written')]
class ProductUpdatedListener
{
    public function __invoke(WebhookAction $action): void
    {
        // handle the webhook
    }
}
```

---

---
url: /docs/v6.6/guides/plugins/apps/app-sdks/symfony-bundle.md
---

# App Bundle

App Bundle integrates the PHP App SDK for Symfony. This can be accessed at [app-bundle-symfony](https://github.com/shopware/app-bundle-symfony).

## Installation

### With SQL based storage (Doctrine)

```bash
composer require shopware/app-bundle doctrine/orm symfony/doctrine-bridge
```

### With NoSQL based storage (DynamoDB)

```bash
composer require shopware/app-bundle async-aws/async-aws-bundle async-aws/dynamo-db
```

## Quick Start using SQL based storage (Doctrine)

### 1. Create a new Symfony Project (skip if existing)

```bash
composer create-project symfony/skeleton:"6.2.*" my-app
```

### 2. Install the App Bundle in your Symfony Project

```bash
composer require shopware/app-bundle doctrine/orm symfony/doctrine-bridge
```

It is also recommended to install the monolog bundle to have logging:

```bash
composer require logger
```

### 3. Create a new App manifest

Here is an example app manifest

```xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        <name>TestApp</name>
        <label>TestApp</label>
        <label lang="de-DE">TestApp</label>
        <description/>
        <description lang="de-DE"/>
        <author>Your Company</author>
        <copyright>(c) by Your Company</copyright>
        <version>1.0.0</version>
        <icon>Resources/config/plugin.png</icon>
        <license>MIT</license>
    </meta>
    <setup>
        <registrationUrl>http://localhost:8000/app/lifecycle/register</registrationUrl>
        <secret>TestSecret</secret>
    </setup>
    <webhooks>
        <webhook name="appActivated" url="http://localhost:8000/app/lifecycle/activate" event="app.activated"/>
        <webhook name="appDeactivated" url="http://localhost:8000/app/lifecycle/deactivate" event="app.deactivated"/>
        <webhook name="appDeleted" url="http://localhost:8000/app/lifecycle/delete" event="app.deleted"/>
    </webhooks>
</manifest>
```

change the app name and the app secret to your needs
and also adjust the environment variables inside your `.env` file to match them.

By default, the following routes are registered:

* `/app/lifecycle/register` - Register the app
* `/app/lifecycle/activate` - Activate the app
* `/app/lifecycle/deactivate` - Deactivate the app
* `/app/lifecycle/delete` - Delete the app

You can change the prefix by editing the `config/routes/shopware_app.yaml` file.

The registration also dispatches events to react to the different lifecycle events. See APP SDK docs for it

### 4. Connecting Doctrine to a Database

The App Bundle ships with a basic Shop entity to store the shop information. You can extend this entity to store more information about your app if needed.

Symfony configures doctrine to use PostgreSQL by default. Change the `DATABASE_URL` environment variable in your `.env` file if you want to use MySQL.
You can also use SQLite by setting the `DATABASE_URL` to `sqlite:///%kernel.project_dir%/var/app.db` for development.

After choosing your database engine, you need to require two extra composer packages.

```shell
composer req symfony/maker-bundle migrations
```

And create your first migration using `bin/console make:migration` (which is using the `AbstractShop` Class) and apply it to your database with `bin/console doctrine:migrations:migrate`.

### 5. Implement first ActionButtons, Webhooks, Payment

[Check out the official app documentation to learn more about the different integration points with this SDK](/docs/guides/plugins/apps/app-base-guide.md#sdk-integration).

You can also check out the [APP SDK](https://github.com/shopware/app-php-sdk) documentation.

### Optional: Webhook as Symfony Events

The app bundle also registers a generic webhook controller, which dispatches the webhook as a Symfony event.
To use that, register your Shopware webhooks to the generic webhook, which is by default `/app/webhook`.

```xml
<webhook name="productWritten" url="http://localhost:8000/app/webhook" event="product.written"/>
```

With that, you can write a Symfony EventListener/Subscriber to listen to and react to the event.

```php
#[AsEventListener(event: 'webhook.product.written')]
class ProductUpdatedListener
{
    public function __invoke(WebhookAction $action): void
    {
        // handle the webhook
    }
}
```

---

---
url: /resources/admin-extension-sdk/getting-started/installation-apps.md
---

# App Installation Flow

Using the Meteor Admin SDK in an app requires exposing an Administration page from the app server and registering it in the app manifest.

This guide discusses two SDKs:

* Meteor Admin SDK: **frontend** layer for the administration
* App Server SDK: **backend** layer (the backend is required; only the framework you use to provide it is up to you)

## App hosting requirement

Each Shopware app must be hosted on its own domain.

It is NOT possible to host multiple apps under the same domain using different subfolders. Instead, use subdomains for each app.

Example:

* `app-one.your-company.com`
* `app-two.your-company.com`

Each app must expose its own publicly reachable URL for registration and webhook handling. This is required due to Cross-Origin security policies enforced by the browser.

:::tip
For local development, you don't need a public URL yet. You can use `localhost` or a tunneling service like ngrok.
If your Shopware instance runs inside Docker, use `host.docker.internal:PORT` instead of `localhost:PORT` for the `registrationUrl` and webhook URLs so Shopware can reach your app server from inside the container. The `base-app-url` does **not** need this — it is loaded by the browser, not by the Shopware server.
:::

## Backend requirement

Apps require a backend that handles the registration handshake and request validation.

Optional, but highly recommended for app development, is the [App Server SDK](https://github.com/shopware/app-sdk-js): a library written in TypeScript that provides a server setup to simplify the registration handshake, signature verification, webhook handling, and communication with the Shopware API.

The App Server SDK supports Node.js, Deno, Bun, and Cloudflare Workers.

Shopware also provides SDKs for other languages. See the [full list of official App SDKs](https://developer.shopware.com/docs/guides/plugins/apps/app-sdks/).

To scaffold a new app using the App Server SDK:

```bash
# scaffold the example app
npx tiged shopware/app-sdk-js/examples/node-hono demo-app
cd demo-app

# install dependencies
npm install

# install the Meteor Admin SDK and Vite for the administration frontend
npm install @shopware-ag/meteor-admin-sdk
npm install vue
npm install -D vite
```

Visit [the App Server SDK guide](https://developer.shopware.com/docs/guides/plugins/apps/app-sdks/javascript/01-getting_started.html) for detailed instructions.

### 1. Ensure the app server is running

Every app must:

* Handle the registration handshake
* Expose a publicly reachable URL
* Serve the Administration frontend

Using the [App Server SDK](https://github.com/shopware/app-sdk-js) is recommended, as it handles the registration handshake, signature verification, webhook handling, and request validation. It is also possible to implement the registration and request validation manually for advanced setups.

The `npx tiged` example gives you the backend for registration and webhook handling. The following steps add the Administration frontend with Vite under `meteor-app/`.

### 2. Create the Administration frontend in `meteor-app/`

Create the folder `demo-app/meteor-app` with an `index.html` and a `src/main.js`. This is the frontend source that Vite will serve inside the Shopware Administration.

For the underlying iframe-based architecture, see [Architecture](../concepts/architecture.md) and [Locations](../concepts/locations.md).

Create `demo-app/meteor-app/index.html`:

```html
<!doctype html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>My Example App</title>
  </head>
  <body>
    <div id="app"></div>
    <script type="module" src="/src/main.js"></script>
  </body>
</html>
```

Create `demo-app/meteor-app/src/main.js`:

```js
import { notification } from "@shopware-ag/meteor-admin-sdk";

notification.dispatch({
  title: "Meteor Admin SDK installed",
  message: "Your app is connected successfully",
});
```

### 3. Mount Vite on the app server

Instead of serving a standalone HTML file, let the Hono app server serve the Vite frontend under `/admin/`.

In the scaffolded `demo-app/index.ts`, replace the default server startup `serve(...)` with a custom HTTP server that forwards `/admin` requests to Vite and everything else to Hono:

```ts
import { readFileSync } from "node:fs";
import { createServer } from "node:http";
import { getRequestListener } from "@hono/node-server";

// Keep your existing Hono app and configureAppServer(...) setup above.

const PORT = 3000;

async function startServer() {
  const honoListener = getRequestListener(app.fetch);
  const { createServer: createViteServer } = await import("vite");

  const httpServer = createServer();

  const vite = await createViteServer({
    root: "./meteor-app",
    base: "/admin/",
    appType: "custom",
    server: {
      middlewareMode: true,
      hmr: { server: httpServer },
    },
  });

  httpServer.on("request", (req, res) => {
    if (req.url?.startsWith("/admin")) {
      vite.middlewares(req, res, async () => {
        try {
          let html = readFileSync("./meteor-app/index.html", "utf-8");
          html = await vite.transformIndexHtml(req.url, html);
          res.writeHead(200, { "Content-Type": "text/html" });
          res.end(html);
        } catch (error) {
          console.error(error);
          res.writeHead(500);
          res.end(error instanceof Error ? error.message : "Unknown error");
        }
      });
      return;
    }

    honoListener(req, res);
  });

  httpServer.listen(PORT, () => {
    console.log(`App server running at http://localhost:${PORT}`);
    console.log(`Administration frontend: http://localhost:${PORT}/admin/`);
  });
}

void startServer();
```

This setup serves the Administration entry page at `/admin/`. Because Vite runs in middleware mode on the same path, requests for JavaScript modules, CSS, `@vite/client`, and HMR also work without adding separate static routes.

### 4. Register the Administration page in `manifest.xml`

After the registration handshake is working, add the `<base-app-url>` field inside the `<admin>` section of the [manifest file](https://developer.shopware.com/docs/guides/plugins/apps/app-base-guide#manifest-file). It must point to the path where Vite serves the frontend, so in this example that is `/admin/`.

As required by Shopware's app system, the `<setup>` section must already contain the `registrationUrl` and `secret`.

:::tip Docker reminder
Remember: the `registrationUrl` must be reachable by the Shopware server. If Shopware runs in Docker, use `host.docker.internal` for that URL. The `base-app-url` is loaded by the browser, so `localhost` works fine there.
:::

Create the file at `/custom/apps/MyExampleApp/manifest.xml` in your Shopware installation. Example for a local dev setup (app server running on port 3000):

```xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/platform/trunk/src/Core/Framework/App/Manifest/Schema/manifest-1.0.xsd">
    <meta>
        <name>MyExampleApp</name>
        <label>MyExampleApp</label>
        <description>This is my first example app</description>
        <author>Developer</author>
        <copyright>(c) Developer</copyright>
        <version>1.0.0</version>
        <license>MIT</license>
    </meta>

    <setup>
        <!-- Use host.docker.internal if Shopware runs in Docker -->
        <registrationUrl>http://host.docker.internal:3000/app/register</registrationUrl>
        <secret>S3cr3tf0re$t</secret>
    </setup>

    <admin>
        <!-- base-app-url is loaded by the browser, so localhost works -->
        <base-app-url>http://localhost:3000/admin/</base-app-url>
    </admin>
</manifest>
```

The `<name>` and `<secret>` in the manifest must match the `appName` and `appSecret` in your app server. Open `demo-app/index.ts` and update the `configureAppServer` call to match:

```ts
configureAppServer(app, {
  appName: "MyExampleApp",
  appSecret: "S3cr3tf0re$t",
  shopRepository: new BetterSqlite3Repository("shop.db"),
});
```

If name or secret don't match between manifest and app server, the registration handshake will fail.

### 5. Start the dev server

```bash
npm start
```

When the server starts successfully, the Administration frontend should be reachable at `http://localhost:3000/admin/`.

### 6. Install and activate the app

```bash
# if you are using Docker, run the following commands inside the container: docker compose exec -it web /bin/bash
bin/console app:install --activate MyExampleApp
bin/console cache:clear
```

### 7. Verify installation

Log in to the Shopware Administration. The notification should appear in the top-right corner on any page (the notification is not bound to a specific module — it appears on every page load).

## Next steps

* Explore the [API Reference](../api-reference/index.md) for all available SDK features
* Learn about [Concepts](../concepts/index.md) like locations, positions, and data handling
* See the [Usage Guide](./usage.md) for more detailed examples

---

---
url: /docs/resources/references/app-reference.md
---

# App Reference

The app reference document gives you an understanding of the app structure, functions, methods, events, variables, responses, and examples for building quality apps in Shopware.

Overall, the app reference document is a valuable resource for creating feature-rich and seamless custom apps that integrate seamlessly with the Shopware platform.

---

---
url: /docs/v6.5/resources/references/app-reference.md
---

# App Reference

The app reference document gives you an understanding of the app structure, functions, methods, events, variables, responses, and examples for building quality apps in Shopware.

Overall, the app reference document is a valuable resource for creating feature-rich and seamless custom apps that integrate seamlessly with the Shopware platform.

---

---
url: /docs/v6.6/resources/references/app-reference.md
---

# App Reference

The app reference document gives you an understanding of the app structure, functions, methods, events, variables, responses, and examples for building quality apps in Shopware.

Overall, the app reference document is a valuable resource for creating feature-rich and seamless custom apps that integrate seamlessly with the Shopware platform.

---

---
url: /docs/guides/plugins/apps/lifecycle/app-registration-setup.md
---

# App Registration & Backend Setup

## Overview

This page documents app setup (registration), permissions, validation, and changes to the shop URL for apps with a backend.

## Setup

::: info
Registration is necessary only when your app backend and Shopware need to communicate. It is performed during the installation of your app.
This process is called setup.
:::

::: warning
Suppose your app uses the Admin Module, Payment Method, Tax providers, or Webhook app system features.
In that case, you need to implement the registration to exchange a secret key, which is later used to authenticate the shops.
:::

During setup, it is verified that Shopware connects to the correct backend server, and keys are exchanged to secure all subsequent communications.
During setup, your app backend will receive credentials to authenticate with the Shopware API.
Additionally, your app will provide a secret that Shopware will use to sign all further requests it makes to your app backend, allowing you to verify that the incoming requests originate from authenticated Shopware installations.

The setup workflow is shown in the following schema.
Each step will be explained in detail.

![Setup request workflow](../../../../assets/plugins-apps-appBaseGuide.svg)

::: info
The timeout for the requests against the app server is 5 seconds.
:::

### SDK Integration

Integrating apps into your application can be daunting, but our PHP SDK simplifies registration and other common tasks.

* [Official PHP SDK](../app-sdks/php/index.md)
* [Official Symfony Bundle](../app-sdks/symfony-bundle/index.md)

If no SDK is available for your language, you can implement the registration process by yourself.

### Registration request

The registration request is made via a `GET` request to the URL you provide in your app's manifest file.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        ...
    </meta>
    <setup>
        <!-- The URL which will be used for the registration -->
        <registrationUrl>https://my.example.com/registration</registrationUrl>
        <!-- Dev only, the secret that is used to sign the registration request -->
        <secret>mysecret</secret>
    </setup>
</manifest>

```

The following query parameters will be sent with the request:

* `shop-id`: The unique identifier of the shop where the app was installed.
* `shop-url`: The URL of the shop, which can later be used to access the Shopware API.
* `timestamp`: The Unix timestamp when the request was created.

Additionally, the request has the following headers:

* `shopware-app-signature`: The signature of the query string
* `sw-version`: The Shopware version of the shop *(since 6.4.1.0)*
* `shopware-shop-signature`: *(re-registration only)* The signature of the query string, signed with the shop's current `shop-secret`. Present only when a previously registered shop re-registers.

An example request looks like this:

```txt
GET https://my.example.com/registration?shop-id=KIPf0Fz6BUkN&shop-url=http%3A%2F%2Fmy.shop.com&timestamp=159239728
shopware-app-signature: a8830aface4ac4a21be94844426e62c77078ca9a10f694737b75ca156b950a2d
sw-version: 6.4.5.0
shopware-shop-signature: b5f1e2d3c4a5... (re-registration only)
```

Additionally, the provided `shopware-app-signature` header contains a cryptographic signature of the query string.
The secret used to generate this signature is the `app secret`, which is unique to each app and will be provided by the Shopware Account when you upload your app to the store.
This secret won't leave the Shopware Account so that it won't be leaked to shops installing your app.

::: danger
You and the Shopware Account are the only parties that should know your `app-secret`.
Therefore, make sure you never accidentally publish your `app-secret`.
:::

::: warning
For **local development**, you can specify a `<secret>` in the manifest file that is used for signing the registration request.
However, if an app uses a hard-coded secret in the manifest, it can't be uploaded to the store.

If you are developing a **private app** not published in the Shopware Store, you **must** provide the `<secret>` in case of an external app server.
:::

To verify that the registration can only be triggered by authenticated Shopware shops, you need to recalculate the signature and check that the signatures match.

Thus, you have verified that the request sender possesses the `app secret`.

The following code snippet can be used to recalculate the signature:

```php
use Psr\Http\Message\RequestInterface;

/** @var RequestInterface $request */
$queryString = $request->getUri()->getQuery();
$signature = hash_hmac('sha256', $queryString, $appSecret);
```

```php
$verifier = new \Shopware\App\SDK\Authentication\DualSignatureRequestVerifier();
$appConfig = new AppConfiguration('AppName', 'AppSecret', 'confirm-url');

// For new registrations, $shop can be null; for re-registrations, pass the existing shop
$verifier->authenticateRegistrationRequest($request, $appConfig, $shop);
```

The Symfony Bundle handles all verification automatically, including dual signature verification for re-registrations.

### Registration response

There may be valid cases where the app installation fails because the domain is blocked or some other prerequisite in that shop is not met, in which case you can return the message error as follows:

```json
{
  "error": "The shop URL is invalid"
}
```

When the registration is successful, you must show that you possess the `app secret` by providing proof signed with the `app secret`.
The proof consists of the SHA-256 HMAC of the concatenation of `shopId`, `shopUrl`, and your app's name.

The following code snippet can be used to calculate the proof:

```php
use Psr\Http\Message\RequestInterface;

/** @var RequestInterface $request */
$queryString = $request->getUri()->getQuery();
parse_str($queryString, $queryValues);
$proof = \hash_hmac(
    'sha256',
    $queryValues['shop-id'] . $queryValues['shop-url'] . $appname,
    $appSecret
);
```

```php
$signer = new ResponseSigner();
$proofParameters = ['shop-id' => $shopId, 'shop-url' => $shopUrl];
$signer->getRegistrationSignature(new AppConfiguration('AppName', 'AppSecret', 'confirm-url'), $proofParameters);
```

For detailed instructions on signing requests and responses, refer to the app signing guide.

Besides the proof, your app needs to provide a randomly generated secret to sign every subsequent request from this shop.
Make sure to save the `shopId`, `shopUrl`, and generated secret so that you can associate and use this information later.

::: info
This secret will be called \`shop-secret\` to distinguish it from the \`app-secret\`.
The \`app-secret\` is unique to your app and is used to sign the registration request of every shop that installs your app.
The \`shop-secret\` will be provided by your app during registration and should be unique to each shop, have a minimum length of 64 characters, and a maximum length of 255 characters.
:::

The last thing needed in the registration response is a URL to which the confirmation request will be sent.

A sample registration response looks like this:

```json
{
  "proof": "94b42d39280141de84bd6fc8e538946ccdd182e4558f1e690eabb94f924e7bc7",
  "secret": "random secret string",
  "confirmation_url": "https://my.example.com/registration/confirm"
}
```

### Confirmation request

If the proof you provided in the [registration response](app-registration-setup.md#registration-response) matches the one generated on the shop side, the registration is completed.
As a result, your app will receive a `POST` request against the URL specified as the `confirmation_url` of the registration with the following parameters sent in the request body:

* `apiKey`: The API key used to authenticate against the Shopware Admin API.
* `secretKey`: The secret key used to authenticate against the Shopware Admin API.
* `timestamp`: The Unix timestamp when the request was created.
* `shopUrl`: The URL of the shop.
* `shopId`: The unique identifier of the shop.

The payload of that request may look like this:

```json
{
  "apiKey":"SWIARXBSDJRWEMJONFK2OHBNWA",
  "secretKey":"Q1QyaUg3ZHpnZURPeDV3ZkpncXdSRzJpNjdBeWM1WWhWYWd0NE0",
  "timestamp":"1592398983",
  "shopUrl":"http:\/\/my.shop.com",
  "shopId":"sqX6cqHi6hbj"
}
```

Make sure that you save the API credentials for that `shopId`.
You can use the `apiKey` and the `secretKey` as `client_id` and `client_secret`, respectively, when you request an OAuth token from the Admin API.

You can find out more about how to use these credentials in our Admin API authentication guide:

::: info
Starting with Shopware version 6.4.1.0, the current Shopware version will be sent in the `sw-version` header.
Starting with Shopware version 6.4.5.0, the current language ID of the Shopware context is sent in the `sw-context-language` header, and the user's locale or the context language's locale is available under the `sw-user-language` header.
:::

The request is signed with the `shop-secret` your app provided in the [registration response](app-registration-setup.md#registration-response), and the signature is in the `shopware-shop-signature` header.
You need to recalculate that signature and verify that it matches the provided one to ensure the request is actually sent from the shop with that shopId.

During **re-registration**, the confirmation request includes an additional header:

* `shopware-shop-signature-previous`: The signature of the request body, signed with the shop's **previous** `shop-secret` (the secret that was active before this registration). This allows you to verify that the confirmation was initiated by the same Shopware installation that previously completed registration.

For details on handling re-registration and secret rotation, see [Secret rotation and shop-url changes](app-registration-setup.md#secret-rotation-and-shop-url-changes).

You can use the following code snippet to generate the signature:

```php
use Psr\Http\Message\RequestInterface;

/** @var RequestInterface $request */
$hmac = \hash_hmac('sha256', $request->getBody()->getContents(), $shopSecret);
```

### Secret rotation and shop-url changes

To rotate the secret or notify your app of a change to the shop's URL, the shop might re-initiate registration with a shop ID that is already registered.

In that case, the re-registration request will not only be signed with the `app-secret`, but also with the previous `shop-secret` (the signature is added as `shopware-shop-signature` header). Your app **must validate both signatures** to verify that the request is coming from the same shop that registered previously.

As this process is also used for secret rotation, your app **must generate a new secret** to authenticate all further communication from that shop. This will be validated on the shop side. The new secret you generate and a changed shop-url **should** only become effective after your app receives a valid confirmation request for that re-registration.

::: warning
To prevent failure of in-flight requests during the secret rotation, your app **should accept the old secret in parallel** with the new secret for a short period (e.g., 1 minute). After that grace period, the signatures based on the old secret **must be** considered invalid.
:::

## Requirements

Apps can declare requirements in their manifest that must be met for the app to function properly. For example, an app that communicates with the shop via the Admin API will fail if the shop is not publicly accessible — declaring that upfront avoids a registration attempt that is guaranteed to fail. Shopware validates requirements during installation and updates in `prod` environments. If a requirement is not met, the installation is rejected with a descriptive error before the app attempts registration.

Add a `<requirements>` element to your `manifest.xml`. Each requirement is an empty child element — its presence enables it:

::: code-group

```xml [manifest.xml]
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
 ...
    </meta>
    <requirements>
        <public-access/>
    </requirements>
</manifest>
```

:::

::: info
Requirements are available since Shopware 6.7.10.0. For the full list of available requirements, see the [manifest reference](../../../../resources/references/app-reference/manifest-reference.md#requirements).
The requirement feature is extensible. We encourage you to contribute new requirements to the Shopware core to allow all app developers to use them.
:::

::: warning
Validation is skipped in `dev` and `test` environments so that local development and CI are not blocked by infrastructure checks.
:::

## Permissions

Shopware comes with the possibility to create fine-grained [Access Control Lists](../administration/../../plugins/administration/permissions-error-handling/add-acl-rules.md) (ACLs).
This means you need to request permissions if your app needs to read or write data via the API or receive webhooks.
The permissions your app needs are defined in the manifest file and combine a privilege (`read`, `create`, `update`, or `delete`) with an entity.
Since version 6.4.12.0, your app can also request additional non-CRUD privileges with the `<permission>` element.

For entities that need all CRUD operations (create, read, update, delete), you can use the `<crud>` shortcut element instead of declaring each permission individually:

* `<crud>product</crud>` automatically grants `read`, `create`, `update`, and `delete` permissions for the product entity

:::info
The `<crud>` shortcut element is available since version 6.7.3.0. If your app needs to support earlier Shopware versions, use the individual permission elements (`read`, `create`, `update`, `delete`) instead.
:::

Sample permissions using the CRUD shortcut for products, individual permissions for orders, as well as reading the cache configuration, look like this:

::: code-group

```xml [manifest.xml]
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
 ...
    </meta>
    <permissions>
        <read>product</read>
        <create>product</create>
        <update>product</update>

        <delete>order</delete>

        <!-- Since version 6.4.12.0, your app can request additional non-CRUD privileges-->
        <permission>system:cache:info</permission>
    </permissions>
</manifest>
```

:::

The permissions you request need to be accepted by the user during the installation of your app.
After that, the permissions granted to your app and your API access via the credentials from the [confirmation request](app-registration-setup.md#confirmation-request) of the [setup workflow](app-registration-setup.md#setup) are limited to those permissions.

::: warning
Keep in mind that read permissions also extend to the data contained in the requests, so your app needs read permissions for the entities contained in the subscribed [webhooks](../lifecycle/webhook.md).
:::

### App notification

Starting with Shopware version 6.4.7.0, if you want to notify the Administration about actions that occurred in your app, send a `POST` request to the `api/notification` endpoint with a valid body and an `Authorization` header.
Your app can make up to 10 requests before the system starts throttling.

* After 10 attempts, you need to wait 10 seconds before trying to make requests again.
* After 15 attempts, it's 30 seconds.
* After 20 attempts, it's 60 seconds.
* After 24 hours without a failed request, the limit is reset.

Example request body:

You must pass the `status` property and the notification text as the `message` property.
You can restrict who can read the notification with the `requiredPrivileges` and `adminOnly` properties in the payload.
When `adminOnly` is true, only admins can read the notification.
If you omit `adminOnly` or set it to false, you can use `requiredPrivileges` so that only users with specific permissions see the notification.
Otherwise, the notification is shown to every user.

```txt
POST /api/notification

{
 "status": "success",
 "message": "This is a successful message",
 "adminOnly": "true",
 "requiredPrivileges": []
}
```

* `status`: Notification status - `success`, `error`, `info`, `warning`.
* `message`: The content of the notification.
* `adminOnly`: Only admins can read this notification if this value is true.
* `requiredPrivileges`: The required privileges that users need to have to read the notification.

Remember that your app needs the `notification:create` permission to access this API.

### App lifecycle events

Apps can also register for lifecycle events of their own, namely installation, updates, and deletion.
For example, they may be used to delete user-relevant data from your data stores once somebody removes your app from their shop.

| Event             | Description                              |
|:------------------|:-----------------------------------------|
| `app.installed` | Triggers once the app is installed       |
| `app.updated` | Triggers if the app is updated           |
| `app.deleted` | Triggers once the app is removed         |
| `app.activated` | Triggers if an inactive app is activated |
| `app.deactivated` | Triggers if an active app is deactivated |

Example request body:

```json
{
  "data": {
    "payload": [],
    "event": "app_deleted"
 },
  "source": {
    "url": "http:\/\/localhost:8000",
    "appVersion": "0.0.1",
    "shopId": "wPNrYZgArBTL"
 }
}
```

```php
use Shopware\App\SDK\Shop\ShopResolver;
use Shopware\App\SDK\Context\ContextResolver;
use Shopware\App\SDK\Response\PaymentResponse;

function webhookController(RequestInterface $request): ResponseInterface
{
    // injected or built by yourself
    $shopResolver = new ShopResolver($repository);
    $contextResolver = new ContextResolver();

    $shop = $shopResolver->resolveShop($serverRequest);
    $webhook = $contextResolver->assembleWebhook($serverRequest, $shop);

    // do something with the parsed webhook
}
```

#### App lifecycle events for app scripts

Since Shopware 6.4.9.0, it is also possible to create [App scripts](../app-scripts/index.md) that are executed during the lifecycle of your app.
You get access to the database and can change or create some data, e.g., when your app is activated, without needing an external server.

For a full list of the available hook points and the available services, refer to the [reference documentation](../../../../resources/references/app-reference/script-reference/script-hooks-reference.md#app-lifecycle).

## Validation

You can run the `app:validate` command to validate the configuration of your app. It will check for common errors, like:

* non-matching app names
* missing translations
* unknown events registered as webhooks
* missing permissions for webhooks
* errors in the config.xml file, if it exists

To validate all apps in your `custom/apps` folder, run:

```bash
bin/console app:validate
```

Additionally, you can specify which app should be validated by providing the app name as an argument.

```bash
bin/console app:validate MyExampleApp
```

## Handling the migration of shops

In the real world, shops may be migrated to new servers and become available under a new URL.
In the same regard, it is possible that a running production shop is duplicated and treated as a staging environment.
These cases are challenging for app developers.
In the first case, you may need to file a complaint against the shop, but the URL you saved during registration may no longer be valid, and the shop cannot be reached via that URL.
In the second case, you may receive webhooks from both shops (prod & staging) that look like they came from the same shop (as the whole database was duplicated).
Thus, it may corrupt the data associated with the original production shop.
The main reason this is problematic is that two Shopware installations in different locations (on different URLs) are associated with the same shopId because the entire database was replicated.

That is why we implemented a safeguard mechanism that detects such situations, stops communication with the apps to prevent data corruption,
and then ultimately lets the user decide how to solve the situation.

::: info
This mechanism relies on the fact that the `APP_URL` environment variable will be set to the correct URL for the shop.
It is especially assumed that the environment variable will change when a shop is migrated to a new domain or when a staging shop is created as a duplicate of a production shop.
:::

Remember that this is only relevant for apps that have their own backends and where communication between app backends and shopware is necessary.
That is why simple themes are not affected by shop migrations, and they will continue to work.

### Detecting APP\_URL changes

Every time a request is made against an app backend, Shopware checks whether the current APP\_URL differs from the one used when Shopware generated an ID for this shop.
If the APP\_URL differs, Shopware will stop sending requests to the installed apps to prevent data corruption on the apps' side.
Now the user can resolve the issue using one of the following strategies.
The user can either run a strategy with the `bin/console app:url-change:resolve` command, or with a modal that pops up when the Administration is opened.

### APP\_URL change resolver

* **MoveShopPermanently**: This strategy should be used if the live production shop is migrated from one URL to another.
  This strategy notifies all apps about the APP\_URL change, and the apps keep working as before, including any data already associated with that shop.
  It is important to note that in this case, apps in the old installation on the old URL (if it is still running) will stop working.

Technically, this is achieved by rerunning the registration process for all apps.
During registration, the same shopId is used as before, but with a different shop-url and a different key pair for communicating with the Shopware API.
Also, you must generate a new communication secret during this registration process that is subsequently used to communicate between Shopware and the app backend.

This way, it is ensured that the apps are notified of the new URL and that the integration with the old installation stops working.
because a new communication secret is associated with the given shopId that the old installation does not know.

* **ReinstallApps**: This strategy makes sense to use in the case of the staging shop.
  By running this strategy, all installed apps will be reinstalled.
  This means that this installation will get a new shopId, which is used during registration.

As the new installation will get a new shopId, the installed apps will continue working on the old installation as before, but, as a consequence, the data on the app's side associated with the old shopId cannot be accessed on the new installation.

* **UninstallApps**: This strategy will simply uninstall all apps on the new installation, thus keeping the old installation working like before.

---

---
url: /docs/resources/references/adr/2025-09-05-app-requirements-validation.md
---

# App requirements validation

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2025-09-05-app-requirements-validation.md)
:::

## Context

The Shopware app system allows third-party applications to extend platform functionality. However, certain apps may require specific environment conditions or infrastructure capabilities to function properly. Without proper validation of these requirements, apps might fail at runtime or behave unpredictably, leading to poor user experience and difficult troubleshooting.

Examples of such requirements include:

* Public accessibility for webhook endpoints
* Secure HTTPS connections for data exchange
* Network connectivity for external service integrations
* Specific server configurations or capabilities

Currently, the app system lacks a standardized way to define and validate these requirements before app installation or updates, which can lead to:

* Silent failures in production environments
* Difficult debugging when apps don't work as expected
* Poor developer experience when requirements are not clearly communicated
* Security vulnerabilities when apps are installed in inappropriate environments

## Decision

We will implement a best-effort app requirements validation system that allows apps to declare their requirements in the manifest and validates these requirements during installation and update processes.

### Key Components

**1. Manifest Requirements Declaration**
Apps can declare requirements using a new `<requirements>` element in their manifest XML by adding empty child elements. Presence means the requirement is enabled:

```xml
<requirements>
    <public-access/>
    <!-- add further requirements as empty elements -->
    <!-- <another-requirement/> -->
    
</requirements>
```

**2. Requirement Interface**
All requirement validators implement a common `Requirement` interface with methods:

* `validate(Manifest $manifest): ?UnmetRequirement` - Validates the requirement and returns an `UnmetRequirement` on failure, or `null` on success
* `required(Manifest $manifest): bool` - Checks if this requirement applies to the app
* `name(): string` - Returns the requirement identifier

**3. Validator Architecture**

* `AppRequirementsValidator` orchestrates validation across all registered requirement validators
* Individual requirement classes (e.g., `PublicAccess`) handle specific validation logic
* Dependency injection allows easy extension with new requirement types

**4. Integration Points**
Requirements validation is integrated into:

* App installation process (`AppLifecycle::install()`)
* App update process (`AppLifecycle::update()`)
* Clear error reporting through `AppException::requirementsNotMet()`

**5. Initial Implementation**
The first requirement validator `PublicAccess` validates that:

* The `APP_URL` environment variable is configured
* The URL uses HTTPS scheme
* The URL is not a localhost or IP address
* The Shopware health check endpoint is publicly accessible

### Error Handling

When requirements are not met, a descriptive `AppException` is thrown with:

* Specific error code: `FRAMEWORK__APP_REQUIREMENTS_NOT_MET`
* Detailed violation descriptions including app name, requirement name, and actionable resolution
* HTTP 400 Bad Request status to indicate client-side configuration issue

### Extensibility

The system is designed for easy extension:

* New requirement validators can be added by implementing the `Requirement` interface
* Service container tag `app.requirements_validator` auto-registers new validators
* Abstract base class `AbstractRequirement` provides common functionality

## Consequences

**Positive Consequences:**

* **Improved Reliability**: Apps will fail fast before attempting to register with app backends, with clear error messages rather than failing silently at runtime
* **Better Developer Experience**: Clear requirement declarations and actionable error messages help developers understand environment needs
* **Enhanced Security**: Validation prevents apps from being installed in inappropriate environments (e.g., apps requiring public access being installed on localhost)
* **Easier Troubleshooting**: Standardized requirement validation provides consistent error reporting

**Potential Challenges:**

* **Additional Complexity**: Developers must understand and declare their app requirements
* **Validation Overhead**: Network checks (like public accessibility) add latency to installation process
* **False Positives**: Overly strict validation might prevent legitimate installations in edge cases
* **Backward Compatibility**: Existing apps without requirement declarations continue to work unchanged
* **Custom Requirements**: Shopware update is required to add new requirement types.

**Migration Strategy:**

* The feature is opt-in through manifest declarations
* Existing apps continue to function without modification
* New apps can gradually adopt requirement declarations as needed
* The `PublicAccess` validator includes caching to minimize performance impact

This implementation establishes a foundation for reliable app deployment while maintaining backward compatibility and providing clear guidance for both app developers and platform administrators.

---

---
url: /docs/resources/references/adr/2023-02-01-app-script-product-pricing.md
---

# App script product pricing

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2023-02-01-app-script-product-pricing.md)
:::

## Context

We want to provide the opportunity to manipulate the price of a product inside the cart and within the store.
For the cart manipulation we already have a hook integrated which allows accessing and manipulating the cart.
Right now we are not allowing to manipulate prices directly but just creating discounts or new price objects and add them as new line items into the cart.

However, there are different business cases which require a direct price manipulation like `get a sample of the product for free`

The following code can be used for manipulating the prices in the product-pricing hook:

```php

{% foreach hook.products as product %}
    {# allow resetting product prices #}
    {% do product.calculatedCheapestPrice.reset %}
    {% do product.calculatedPrices.reset %}
    {# not allowed to RESET the default price otherwise it is not more valid
    
    {# get control of the default price calculation #}
    {% set price = services.prices.create({
       'default': { 'gross': 20, 'net': 20 },
       'USD': { 'gross': 15, 'net': 15 },
       'EUR': { 'gross': 10, 'net': 10 }
    }) %}
    
    {# directly changes the price to a fix value #}
    {% do product.calculatedPrice.change(price) %}
    
    {# manipulate the price and subtract the provided price object #}
    {% do product.calculatedPrice.minus(price) %}
    
    {# manipulate the price and add the provided price object #}
    {% do product.calculatedPrice.plus(price) %}
    
    {# the following examples show how to deal with percentage manipulation #}
    {% do product.calculatedPrice.discount(10) %}
    {% do product.calculatedPrice.surcharge(10) %}
    
    {# get control of graduated prices #}
    {% do product.calculatedPrices.reset %}
    {% do product.calculatedPrices.change([
        { to: 20, price: services.prices.create({ 'default': { 'gross': 15, 'net': 15} }) },
        { to: 30, price: services.prices.create({ 'default': { 'gross': 10, 'net': 10} }) },
        { to: null, price: services.prices.create({ 'default': { 'gross': 5, 'net': 5} }) },
    ]) %}
    
    {# after hook => walk through prices and fix "from/to" values #}
    
    {% do product.calculatedCheapestPrice.change(price) %}
    {% do product.calculatedCheapestPrice.minus(price) %}
    {% do product.calculatedCheapestPrice.plus(price) %}
    {% do product.calculatedCheapestPrice.discount(10) %}
    {% do product.calculatedCheapestPrice.surcharge(10) %}

{% endforeach %}
```

The following code can be used to manipulate the prices of a product inside the cart:

```php
{# manipulate price of a product inside the cart #}
{% set product = services.cart.get('my-product-id') %}

{% set price = services.prices.create({
   'default': { 'gross': 20, 'net': 20 }
}) %}

{% do product.price.change(price) %}

{% do product.price.discount(10) %}
{% do product.price.surcharge(10) %}
```

---

---
url: /docs/v6.5/resources/references/adr/2023-02-01-app-script-product-pricing.md
---

# App script product pricing

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2023-02-01-app-script-product-pricing.md)
:::

## Context

We want to provide the opportunity to manipulate the price of a product inside the cart and within the store.
For the cart manipulation we already have a hook integrated which allows accessing and manipulating the cart.
Right now we are not allowing to manipulate prices directly but just creating discounts or new price objects and add them as new line items into the cart.

However, there are different business cases which require a direct price manipulation like `get a sample of the product for free`

The following code can be used for manipulating the prices in the product-pricing hook:

```php

{% foreach hook.products as product %}
    {# allow resetting product prices #}
    {% do product.calculatedCheapestPrice.reset %}
    {% do product.calculatedPrices.reset %}
    {# not allowed to RESET the default price otherwise it is not more valid
    
    {# get control of the default price calculation #}
    {% set price = services.prices.create({
       'default': { 'gross': 20, 'net': 20 },
       'USD': { 'gross': 15, 'net': 15 },
       'EUR': { 'gross': 10, 'net': 10 }
    }) %}
    
    {# directly changes the price to a fix value #}
    {% do product.calculatedPrice.change(price) %}
    
    {# manipulate the price and subtract the provided price object #}
    {% do product.calculatedPrice.minus(price) %}
    
    {# manipulate the price and add the provided price object #}
    {% do product.calculatedPrice.plus(price) %}
    
    {# the following examples show how to deal with percentage manipulation #}
    {% do product.calculatedPrice.discount(10) %}
    {% do product.calculatedPrice.surcharge(10) %}
    
    {# get control of graduated prices #}
    {% do product.calculatedPrices.reset %}
    {% do product.calculatedPrices.change([
        { to: 20, price: services.prices.create({ 'default': { 'gross': 15, 'net': 15} }) },
        { to: 30, price: services.prices.create({ 'default': { 'gross': 10, 'net': 10} }) },
        { to: null, price: services.prices.create({ 'default': { 'gross': 5, 'net': 5} }) },
    ]) %}
    
    {# after hook => walk through prices and fix "from/to" values #}
    
    {% do product.calculatedCheapestPrice.change(price) %}
    {% do product.calculatedCheapestPrice.minus(price) %}
    {% do product.calculatedCheapestPrice.plus(price) %}
    {% do product.calculatedCheapestPrice.discount(10) %}
    {% do product.calculatedCheapestPrice.surcharge(10) %}

{% endforeach %}
```

The following code can be used to manipulate the prices of a product inside the cart:

```php
{# manipulate price of a product inside the cart #}
{% set product = services.cart.get('my-product-id') %}

{% set price = services.prices.create({
   'default': { 'gross': 20, 'net': 20 }
}) %}

{% do product.price.change(price) %}

{% do product.price.discount(10) %}
{% do product.price.surcharge(10) %}
```

---

---
url: /docs/v6.6/resources/references/adr/2023-02-01-app-script-product-pricing.md
---

# App script product pricing

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2023-02-01-app-script-product-pricing.md)
:::

## Context

We want to provide the opportunity to manipulate the price of a product inside the cart and within the store.
For the cart manipulation we already have a hook integrated which allows accessing and manipulating the cart.
Right now we are not allowing to manipulate prices directly but just creating discounts or new price objects and add them as new line items into the cart.

However, there are different business cases which require a direct price manipulation like `get a sample of the product for free`

The following code can be used for manipulating the prices in the product-pricing hook:

```php

{% foreach hook.products as product %}
    {# allow resetting product prices #}
    {% do product.calculatedCheapestPrice.reset %}
    {% do product.calculatedPrices.reset %}
    {# not allowed to RESET the default price otherwise it is not more valid
    
    {# get control of the default price calculation #}
    {% set price = services.prices.create({
       'default': { 'gross': 20, 'net': 20 },
       'USD': { 'gross': 15, 'net': 15 },
       'EUR': { 'gross': 10, 'net': 10 }
    }) %}
    
    {# directly changes the price to a fix value #}
    {% do product.calculatedPrice.change(price) %}
    
    {# manipulate the price and subtract the provided price object #}
    {% do product.calculatedPrice.minus(price) %}
    
    {# manipulate the price and add the provided price object #}
    {% do product.calculatedPrice.plus(price) %}
    
    {# the following examples show how to deal with percentage manipulation #}
    {% do product.calculatedPrice.discount(10) %}
    {% do product.calculatedPrice.surcharge(10) %}
    
    {# get control of graduated prices #}
    {% do product.calculatedPrices.reset %}
    {% do product.calculatedPrices.change([
        { to: 20, price: services.prices.create({ 'default': { 'gross': 15, 'net': 15} }) },
        { to: 30, price: services.prices.create({ 'default': { 'gross': 10, 'net': 10} }) },
        { to: null, price: services.prices.create({ 'default': { 'gross': 5, 'net': 5} }) },
    ]) %}
    
    {# after hook => walk through prices and fix "from/to" values #}
    
    {% do product.calculatedCheapestPrice.change(price) %}
    {% do product.calculatedCheapestPrice.minus(price) %}
    {% do product.calculatedCheapestPrice.plus(price) %}
    {% do product.calculatedCheapestPrice.discount(10) %}
    {% do product.calculatedCheapestPrice.surcharge(10) %}

{% endforeach %}
```

The following code can be used to manipulate the prices of a product inside the cart:

```php
{# manipulate price of a product inside the cart #}
{% set product = services.cart.get('my-product-id') %}

{% set price = services.prices.create({
   'default': { 'gross': 20, 'net': 20 }
}) %}

{% do product.price.change(price) %}

{% do product.price.discount(10) %}
{% do product.price.surcharge(10) %}
```

---

---
url: /docs/resources/references/adr/2021-10-21-app-scripting.md
---

# App scripts

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2021-10-21-app-scripting.md)
:::

## Context

To improve the abilities of Apps, they should be able to execute code synchronously and hook into familiar places like:

* rules
* cart
* storefront page loading
* shipping method calculation
* flow builder extensions

The app system requires that this code is in some way sandboxed, with no direct access to the database or filesystem, and the code is not saved on the server.

Additionally, such a Scripting feature generally improves the capabilities of the AppSystem, this feature is not bound to the AppSystem exclusively, it should be possible to add standalone scripts.

## Decision

We use Twig as it brings a secure PHP sandbox and allows interacting directly with objects. The scripts will be saved in the database and mapped to a specific scripting event.
Scripting events are placed in many sections in Shopware to be able to adjust them. Apps can subscribe to the scripting events by placing their scripts into the correspondingly named folders.

### Scripting Events

The data passed to the scripts always has to be an object so that the manipulation from Twig can affect the given value.
Given objects must be wrapped into custom objects for app scripting to provide easier access to certain functionality and limit the scripting scope.
The twig environment will provide additional functions like `dal_search` globally to all events to fetch other data in a consequent way

#### Which objects can be injected into the hooks and which have to be wrapped

In general, it ok to inject `Struct` classes directly into the hooks, as long as those are rather "dumb" data containers (e.g. our DAL entity classes or the storefront page classes).
A notable Exception to this rule are `Struct` classes that provide business logic, besides simple getters and setters (e.g. the Cart struct).
Those `Structs` and all other `Services` that provide business logic or function that can lead to side effects (DB access, etc.) need to be wrapped into a facade.
This will allow us to closely control the interface we want to provide inside the app scripts, to firstly improve developer experience by tailoring the API to the needs of app developers and secondly to ensure that we don't introduce any security issues with the app scripts.

### Scripting execution

Each script has its twig environments to improve execution stability. In failure cases, we will throw our exception.
The twig environment is reduced to the only set of functionality that is needed; features like block and many template features are disabled.
Script loading can happen in multiple implementations, the default implementation will use the object cache to load the scripts and if missing loading it from the database.
The compiled scripts will be cached on the filesystem in a separate folder per app and per appVersion.
For development purposes, the scripts can be loaded from the filesystem to allow easier development. The default Twig cache will be used for faster code execution.

### Example pseudo-code of the ScriptEventRegistry

```php
class ScriptEventRegistry
{
    public const EVENT_PRODUCT_PAGE_LOADED = 'product-page-loaded';

    private $scripts = [];
    private LoggerInterface $logger;
    
    public function execute(string $hook, array $context)
    {
        $scripts = $this->scripts[$hook] ?? [];
        foreach ($scripts as $script) {
            $this->executeScript($script, $context);
        }
    }
    
    private function executeScript(array $script, array $context) 
    {
        $twig = $this->initEnv($script);

        try {
            $twig->render($script['name'], $context);
        } catch (\Throwable $e) {
            throw new ScriptExecutionFailed('Script execution failed', $e);
            $this->logger->error('Execution of script failed', ['context' => $context, 'error' => $e]));
        }
    }
    
    private function initEnv(array $script) 
    {
        $cache = new ConfigurableFilesystemCache($this->cachePath . '/twig/scripts');
        $cache->setConfigHash($script['appName'] . $script['appVersion']);
        
        $twig = new Environment(
            new ScriptLoader([$script['name'] => $script['source']]),
            [
                'cache' => $cache,
            ]
        );
        
        // Setup some custom twig functions
        
        return $twig;
    }
}
```

### Example pseudo-code

#### Getting discount for high value order

```twig
{% if cart.price.totalPrice > 500 %}
    {# get discount for high value orders #}
    {% do cart.discount('percentage', 10, 'my_discount_snippet', cart.lineItems) %}
{% endif %}
```

#### Block cart

```twig
{% if cart.price.totalPrice < 500 %}
    {# allow only carts with high values #}
    {% do cart.block('you have to pay at least 500€ for this cart') %}
{% endif %}
```

### Data Loading

To allow apps to fetch additional data for the storefront, we will introduce PageLoaded-Hooks.
Those hooks will orient themself on the Page and PageLoadedEvents already present in the storefront. So for each PageType and PageLoadedEvent we will create a separate Hook class.
We will create separate HookClasses and not just one generic class, so we are able to type hint all the dynamic data that is available for that hook. That will improve the developer experience as it allows for autocompletion in the scripts and allows us to generate documentation for the hooks.
The hooks will be instantiated and passed to the HookExecutor from the Controllers where the pages are loaded, so we are able to pass additional data if it is needed or makes sense.
Additionally, we explicitly decided to not provide CriteriaEvent-Hooks, as that idea is contrary to the direction we may want to go with a separate and specialized data view for the storefront.

### Documentation

To ensure app developers can use the full potential of the app scripts, we need to ensure that we document the features of app scripts extensively and make sure that the documentation is always up-to-date.
For this reason we decided to generate as much of the documentation as possible, so it never gets outdated, and it's easier to generate full reference (e.g. all hook points that exist with the associated data and available services).

## Consequences

* Added script events with the passed arguments need to be supported for a long time
* We will create a new domain-specific way to interact with shopware core domain logic. This means we have to think of and develop a higher-level description of our core domain logic and represent it through new
  functions that perform domain-specific tasks. For example, the block cart function in the example above. Those domain objects represent the API of the AppScripts, therefore, breaking changes need to be considered carefully and should definitely follow our general breaking change policy.
  Additionally, the domain-specific layer may allow us to not break the public interface, when the implementation in the underlying services may break, so we can try to ensure even longer compatibility in the domain layer.
  However, to make evolvability possible at all, we need to inject the shopware version into the context of the app scripts, so that in the app scripts the version can be detected and new features used accordingly.

---

---
url: /docs/v6.5/resources/references/adr/2021-10-21-app-scripting.md
---

# App scripts

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2021-10-21-app-scripting.md)
:::

## Context

To improve the abilities of Apps, they should be able to execute code synchronously and hook into familiar places like:

* rules
* cart
* storefront page loading
* shipping method calculation
* flow builder extensions

The app system requires that this code is in some way sandboxed, with no direct access to the database or filesystem, and the code is not saved on the server.

Additionally, such a Scripting feature generally improves the capabilities of the AppSystem, this feature is not bound to the AppSystem exclusively, it should be possible to add standalone scripts.

## Decision

We use Twig as it brings a secure PHP sandbox and allows interacting directly with objects. The scripts will be saved in the database and mapped to a specific scripting event.
Scripting events are placed in many sections in Shopware to be able to adjust them. Apps can subscribe to the scripting events by placing their scripts into the correspondingly named folders.

### Scripting Events

The data passed to the scripts always has to be an object so that the manipulation from Twig can affect the given value.
Given objects must be wrapped into custom objects for app scripting to provide easier access to certain functionality and limit the scripting scope.
The twig environment will provide additional functions like `dal_search` globally to all events to fetch other data in a consequent way

#### Which objects can be injected into the hooks and which have to be wrapped

In general, it ok to inject `Struct` classes directly into the hooks, as long as those are rather "dumb" data containers (e.g. our DAL entity classes or the storefront page classes).
A notable Exception to this rule are `Struct` classes that provide business logic, besides simple getters and setters (e.g. the Cart struct).
Those `Structs` and all other `Services` that provide business logic or function that can lead to side effects (DB access, etc.) need to be wrapped into a facade.
This will allow us to closely control the interface we want to provide inside the app scripts, to firstly improve developer experience by tailoring the API to the needs of app developers and secondly to ensure that we don't introduce any security issues with the app scripts.

### Scripting execution

Each script has its twig environments to improve execution stability. In failure cases, we will throw our exception.
The twig environment is reduced to the only set of functionality that is needed; features like block and many template features are disabled.
Script loading can happen in multiple implementations, the default implementation will use the object cache to load the scripts and if missing loading it from the database.
The compiled scripts will be cached on the filesystem in a separate folder per app and per appVersion.
For development purposes, the scripts can be loaded from the filesystem to allow easier development. The default Twig cache will be used for faster code execution.

### Example pseudo-code of the ScriptEventRegistry

```php
class ScriptEventRegistry
{
    public const EVENT_PRODUCT_PAGE_LOADED = 'product-page-loaded';

    private $scripts = [];
    private LoggerInterface $logger;
    
    public function execute(string $hook, array $context)
    {
        $scripts = $this->scripts[$hook] ?? [];
        foreach ($scripts as $script) {
            $this->executeScript($script, $context);
        }
    }
    
    private function executeScript(array $script, array $context) 
    {
        $twig = $this->initEnv($script);

        try {
            $twig->render($script['name'], $context);
        } catch (\Throwable $e) {
            throw new ScriptExecutionFailed('Script execution failed', $e);
            $this->logger->error('Execution of script failed', ['context' => $context, 'error' => $e]));
        }
    }
    
    private function initEnv(array $script) 
    {
        $cache = new ConfigurableFilesystemCache($this->cachePath . '/twig/scripts');
        $cache->setConfigHash($script['appName'] . $script['appVersion']);
        
        $twig = new Environment(
            new ScriptLoader([$script['name'] => $script['source']]),
            [
                'cache' => $cache,
            ]
        );
        
        // Setup some custom twig functions
        
        return $twig;
    }
}
```

### Example pseudo-code

#### Getting discount for high value order

```twig
{% if cart.price.totalPrice > 500 %}
    {# get discount for high value orders #}
    {% do cart.discount('percentage', 10, 'my_discount_snippet', cart.lineItems) %}
{% endif %}
```

#### Block cart

```twig
{% if cart.price.totalPrice < 500 %}
    {# allow only carts with high values #}
    {% do cart.block('you have to pay at least 500€ for this cart') %}
{% endif %}
```

### Data Loading

To allow apps to fetch additional data for the storefront, we will introduce PageLoaded-Hooks.
Those hooks will orient themself on the Page and PageLoadedEvents already present in the storefront. So for each PageType and PageLoadedEvent we will create a separate Hook class.
We will create separate HookClasses and not just one generic class, so we are able to type hint all the dynamic data that is available for that hook. That will improve the developer experience as it allows for autocompletion in the scripts and allows us to generate documentation for the hooks.
The hooks will be instantiated and passed to the HookExecutor from the Controllers where the pages are loaded, so we are able to pass additional data if it is needed or makes sense.
Additionally, we explicitly decided to not provide CriteriaEvent-Hooks, as that idea is contrary to the direction we may want to go with a separate and specialized data view for the storefront.

### Documentation

To ensure app developers can use the full potential of the app scripts, we need to ensure that we document the features of app scripts extensively and make sure that the documentation is always up-to-date.
For this reason we decided to generate as much of the documentation as possible, so it never gets outdated, and it's easier to generate full reference (e.g. all hook points that exist with the associated data and available services).

## Consequences

* Added script events with the passed arguments need to be supported for a long time
* We will create a new domain-specific way to interact with shopware core domain logic. This means we have to think of and develop a higher-level description of our core domain logic and represent it through new
  functions that perform domain-specific tasks. For example, the block cart function in the example above. Those domain objects represent the API of the AppScripts, therefore, breaking changes need to be considered carefully and should definitely follow our general breaking change policy.
  Additionally, the domain-specific layer may allow us to not break the public interface, when the implementation in the underlying services may break, so we can try to ensure even longer compatibility in the domain layer.
  However, to make evolvability possible at all, we need to inject the shopware version into the context of the app scripts, so that in the app scripts the version can be detected and new features used accordingly.

---

---
url: /docs/v6.6/resources/references/adr/2021-10-21-app-scripting.md
---

# App scripts

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2021-10-21-app-scripting.md)
:::

## Context

To improve the abilities of Apps, they should be able to execute code synchronously and hook into familiar places like:

* rules
* cart
* storefront page loading
* shipping method calculation
* flow builder extensions

The app system requires that this code is in some way sandboxed, with no direct access to the database or filesystem, and the code is not saved on the server.

Additionally, such a Scripting feature generally improves the capabilities of the AppSystem, this feature is not bound to the AppSystem exclusively, it should be possible to add standalone scripts.

## Decision

We use Twig as it brings a secure PHP sandbox and allows interacting directly with objects. The scripts will be saved in the database and mapped to a specific scripting event.
Scripting events are placed in many sections in Shopware to be able to adjust them. Apps can subscribe to the scripting events by placing their scripts into the correspondingly named folders.

### Scripting Events

The data passed to the scripts always has to be an object so that the manipulation from Twig can affect the given value.
Given objects must be wrapped into custom objects for app scripting to provide easier access to certain functionality and limit the scripting scope.
The twig environment will provide additional functions like `dal_search` globally to all events to fetch other data in a consequent way

#### Which objects can be injected into the hooks and which have to be wrapped

In general, it ok to inject `Struct` classes directly into the hooks, as long as those are rather "dumb" data containers (e.g. our DAL entity classes or the storefront page classes).
A notable Exception to this rule are `Struct` classes that provide business logic, besides simple getters and setters (e.g. the Cart struct).
Those `Structs` and all other `Services` that provide business logic or function that can lead to side effects (DB access, etc.) need to be wrapped into a facade.
This will allow us to closely control the interface we want to provide inside the app scripts, to firstly improve developer experience by tailoring the API to the needs of app developers and secondly to ensure that we don't introduce any security issues with the app scripts.

### Scripting execution

Each script has its twig environments to improve execution stability. In failure cases, we will throw our exception.
The twig environment is reduced to the only set of functionality that is needed; features like block and many template features are disabled.
Script loading can happen in multiple implementations, the default implementation will use the object cache to load the scripts and if missing loading it from the database.
The compiled scripts will be cached on the filesystem in a separate folder per app and per appVersion.
For development purposes, the scripts can be loaded from the filesystem to allow easier development. The default Twig cache will be used for faster code execution.

### Example pseudo-code of the ScriptEventRegistry

```php
class ScriptEventRegistry
{
    public const EVENT_PRODUCT_PAGE_LOADED = 'product-page-loaded';

    private $scripts = [];
    private LoggerInterface $logger;
    
    public function execute(string $hook, array $context)
    {
        $scripts = $this->scripts[$hook] ?? [];
        foreach ($scripts as $script) {
            $this->executeScript($script, $context);
        }
    }
    
    private function executeScript(array $script, array $context) 
    {
        $twig = $this->initEnv($script);

        try {
            $twig->render($script['name'], $context);
        } catch (\Throwable $e) {
            throw new ScriptExecutionFailed('Script execution failed', $e);
            $this->logger->error('Execution of script failed', ['context' => $context, 'error' => $e]));
        }
    }
    
    private function initEnv(array $script) 
    {
        $cache = new ConfigurableFilesystemCache($this->cachePath . '/twig/scripts');
        $cache->setConfigHash($script['appName'] . $script['appVersion']);
        
        $twig = new Environment(
            new ScriptLoader([$script['name'] => $script['source']]),
            [
                'cache' => $cache,
            ]
        );
        
        // Setup some custom twig functions
        
        return $twig;
    }
}
```

### Example pseudo-code

#### Getting discount for high value order

```twig
{% if cart.price.totalPrice > 500 %}
    {# get discount for high value orders #}
    {% do cart.discount('percentage', 10, 'my_discount_snippet', cart.lineItems) %}
{% endif %}
```

#### Block cart

```twig
{% if cart.price.totalPrice < 500 %}
    {# allow only carts with high values #}
    {% do cart.block('you have to pay at least 500€ for this cart') %}
{% endif %}
```

### Data Loading

To allow apps to fetch additional data for the storefront, we will introduce PageLoaded-Hooks.
Those hooks will orient themself on the Page and PageLoadedEvents already present in the storefront. So for each PageType and PageLoadedEvent we will create a separate Hook class.
We will create separate HookClasses and not just one generic class, so we are able to type hint all the dynamic data that is available for that hook. That will improve the developer experience as it allows for autocompletion in the scripts and allows us to generate documentation for the hooks.
The hooks will be instantiated and passed to the HookExecutor from the Controllers where the pages are loaded, so we are able to pass additional data if it is needed or makes sense.
Additionally, we explicitly decided to not provide CriteriaEvent-Hooks, as that idea is contrary to the direction we may want to go with a separate and specialized data view for the storefront.

### Documentation

To ensure app developers can use the full potential of the app scripts, we need to ensure that we document the features of app scripts extensively and make sure that the documentation is always up-to-date.
For this reason we decided to generate as much of the documentation as possible, so it never gets outdated, and it's easier to generate full reference (e.g. all hook points that exist with the associated data and available services).

## Consequences

* Added script events with the passed arguments need to be supported for a long time
* We will create a new domain-specific way to interact with shopware core domain logic. This means we have to think of and develop a higher-level description of our core domain logic and represent it through new
  functions that perform domain-specific tasks. For example, the block cart function in the example above. Those domain objects represent the API of the AppScripts, therefore, breaking changes need to be considered carefully and should definitely follow our general breaking change policy.
  Additionally, the domain-specific layer may allow us to not break the public interface, when the implementation in the underlying services may break, so we can try to ensure even longer compatibility in the domain layer.
  However, to make evolvability possible at all, we need to inject the shopware version into the context of the app scripts, so that in the app scripts the version can be detected and new features used accordingly.

---

---
url: /docs/guides/plugins/apps/app-scripts.md
---

# App Scripts

App scripts allow your app to include logic that is executed inside the Shopware execution stack. They allow you to build richer extensions that integrate more deeply with Shopware.

::: info
Note that app scripts were introduced in Shopware 6.4.8.0 and are not supported in previous versions.
:::

## Script hooks

The entry point for each script is the so-called "Hooks". You can register one or more scripts inside your app that should be executed whenever a specific hook is triggered.

Through the hook, your script gets access to the data of the current execution context and can react to or manipulate the data in some way.

See the [Hooks reference](../../../../resources/references/app-reference/script-reference/script-hooks-reference) for a complete list of all available.

## Scripts

At the core, app scripts are [Twig files](https://twig.symfony.com/) executed in a sandboxed environment. Based on which hook the script is registered to, the script has access to the data of that hook and pre-defined services that can be used to execute your custom logic.

Apps scripts are placed in the `Resources/scripts` directory of your app. For each hook, you want to execute a script on, create a new subdirectory. The name of the subdirectory needs to match the name of the hook.

You can place one or more `.twig` files inside each of these subdirectories, which will be executed when the hook gets triggered.

The file structure of your apps should look like this:

```text
└── DemoApp
    ├── Resources
    │   └── scripts                         // all scripts are stored in this folder
    │       ├── product-page-loaded         // each script in this folder will be executed when the `product-page-loaded` hook is triggered
    │       │   └── my-first-script.twig
    │       ├── cart
    │       │   ├── first-cart-script.twig
    │       │   └── second-cart-script.twig // you can execute multiple scripts per hook
    │       └── ...
    └── manifest.xml
```

### Including scripts

Sometimes scripts can become more complex or you want to extract common functionality. Thus it is handy to split your scripts into smaller parts that can later be included in other scripts.

In order to do that you can compose your reusable scripts into [Twig macros](https://twig.symfony.com/doc/3.x/tags/macro.html), put them inside a dedicated `include` folder and then import them using the [twig import functionality](https://twig.symfony.com/doc/3.x/tags/import.html).

```text
└── DemoApp
    ├── Resources
    │   └── scripts                         
    │       ├── include    
    │       │   └── media-repository.twig         // this script may be included into the other scripts
    │       ├── cart
    │       │   ├── first-cart-script.twig
    │       └── ...
    └── manifest.xml
```

Note that app scripts can use the `return` keyword to return values to the caller.

A basic example may look like this:

```twig
// Resources/scripts/include/media-repository.twig
{% macro getById(mediaId) %}
    {% set criteria = {
        'ids': [ mediaId ]
    } %}
    
     {% return services.repository.search('media', criteria).first %}
{% endmacro %}
```

```twig
// Resources/scripts/cart/first-cart-script.twig
{% import "include/media-repository.twig" as mediaRepository %}

{% set mediaEntity = mediaRepository.getById(myMediaId) %}
```

### Interface Hooks

Some "Hooks" describe interfaces this means that your scripts for that hook need to implement one or more functions.
E.g., the `store-api-hook` defines a `cache_key` and a `response` function. Those functions are closely related but are executed separately.
To implement the different functions, you use different twig blocks with the name of the function:

```twig
{% block cache_key %}
    // provide a cacheKey for the incoming request
{% endblock %}

{% block response %}
    // produce the response for the request
{% endblock %}
```

Some functions are optional, whereas others are required. In the above example the `cache_key` function is optional.
That means you can omit that block in your script without an error (but caching for the endpoint won't work in that case).
The `response` function is required, which means that if your script does not provide a `response` block, it will lead to an error.

Note that for each function, you get access to different input data or services, so in the `cache_key` block, you don't necessarily have access to the same data and services as in the `response` block.
The available data and services are described for each hook (or each function in InterfaceHooks) in the [reference documentation](../../../../resources/references/app-reference/script-reference/script-hooks-reference).

### Translation

Inside the app script, you have access to the [Storefront translation mechanism](../../plugins/storefront/styling/add-translations.md) by using the `|trans`-filter.

```twig
{% set translated = 'my.snippet.key'|trans %}

{% do call.something('my.snippet.key'|trans) %}
```

### Extended syntax

In addition to the default twig syntax, app scripts can also use a more PHP-flavoured syntax.

#### Equals check with `===`

Instead of using the rather verbose `{% if var is same as(1) %}`, you can use the more dense `===` equality checks.

```twig
{% if var === 1 %}
    ...
{% endif %}
```

Additionally, you can also use the `!==` not equals operator as well.

```twig
{% if var !== 1 %}
    ...
{% endif %}
```

#### Loops with `foreach`

Instead of the `for...in` syntax for loops, you can also use a `foreach` tag.

```twig
{% foreach list as entry %}
    {{ entry }}
    {% break %}
{% endforeach %}
```

#### Instance of checks with `is`

You can use a `is` check to check the type of a variable.

```twig
{% if var is string %}
    ...
{% endif %}
```

The following types are supported:

* `true`
* `false`
* `boolean` / `bool`
* `string`
* `scalar`
* `object`
* `integer` / `int`
* `float`
* `callable`
* `array`

#### Type casts with `intval`

You can cast variables into different types with the `intval` filter.

```twig
{% if '5'|intval === 5 %}
    {# always evaluates to true #}
{% endif %}
```

The following type casts are supported:

* `intval`
* `strval`
* `boolval`
* `floatval`

#### conditions with `&&` and `||`

Instead of using `AND` or `OR` in if-conditions, you can use the `&&` or `||` shorthands.

```twig
{% if condition === true && condition2 === true %}
    ...
{% endif %}
```

#### `return` tag

You can use the `return` tag to return values from inside macros.

```twig
{% macro foo() %}
     {% return 'bar' %}
{% endmacro %}
```

## Available services

Depending on the hook that triggered the execution of your script, you get access to different services you can use inside your scripts, e.g. to access data inside Shopware or to manipulate the cart.
Take a look at the [Hook reference](../../../../resources/references/app-reference/script-reference/script-hooks-reference) to get a complete list of all available services per hook.

Additionally, we added a `ServiceStubs`class that can be used as typehint in your script, so you get auto-completion features of your IDE.

```twig
{# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

{% set configValue = services.config.app('my-app-config') %}
```

::: info
The stub class contains all services, but not all of them are available depending on the hook.
:::

## Example Script - loading media entities

Assuming your app adds a [custom field set](../custom-data/custom-fields) for the product entity with a custom media entity select field.

When you want to display the file of the media entity in the [Storefront](../storefront/), it is not easily possible because, in the template's data, you only get the id of the media entity, but not the URL of the media file itself.

For this case, you can add an app script on the `product-page-loaded`
hook, which loads the media entity by id and adds it to the page object so the data is available in templates.

```twig
// Resources/scripts/product-page-loaded/add-custom-media.twig
{# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

{% set page = hook.page %}
{# @var page \Shopware\Storefront\Page\Product\ProductPage #}

{% if page.product.customFields.myCustomMediaField is not defined %}
    {% return %}
{% endif %}

{% set criteria = {
    'ids': [ page.product.customFields.myCustomMediaField ]
} %}

{% set media = services.repository.search('media', criteria).first %}

{% do page.addExtension('swagMyCustomMediaField', media) %}
```

For a more detailed example of how to load additional data, refer to the [data loading guide](./data-loading).

Alternatively, take a look at the [cart manipulation guide](./cart-manipulation) to get an in-depth explanation of how to manipulate the cart with scripts.

## Developing/debugging scripts

You can get information about what scripts were triggered on a specific Storefront page inside the [Symfony debug toolbar](https://symfony.com/doc/current/the-fast-track/en/5-debug.html#discovering-the-symfony-debugging-tools).

::: info
The debug toolbar is only visible if your Shopware installation is in `APP_ENV = dev`. Ensure to set the correct env, e.g., in your `.env` file, when developing app scripts.
:::

You can find all hooks that are triggered and the scripts that are executed for each by clicking on the `script` icon.

![Symfony Debug Toolbar](../../../../assets/script-debug-toolbar.png)

That will open the Symfony profiler in the script detail view, where you can see all triggered hooks and the count of the scripts executed for each script at the top.

![Script Debug Toolbar](../../../../assets/script-debug-detail.png)

Additionally, you can use the `debug.dump()` function inside your scripts to dump data to the debug view.
A script like this:

```twig
{% do debug.dump(hook.page) %}
```

Will dump the page object to the debug view.

![Output of debug.dump()](../../../../assets/script-debug-dump.png)

---

---
url: /docs/v6.5/guides/plugins/apps/app-scripts.md
---

# App Scripts

App Scripts allow your app to include logic that is executed inside the Shopware execution stack. It allows you to build richer extensions that integrate more deeply with Shopware.

::: info
Note that app scripts were introduced in Shopware 6.4.8.0 and are not supported in previous versions.
:::

## Script hooks

The entry point for each script is the so-called "Hooks". You can register one or more scripts inside your app that should be executed whenever a specific hook is triggered.
Through the hook, your script gets access to the data of the current execution context and can react to or manipulate the data in some way.

See the [Hooks reference](../../../../resources/references/app-reference/script-reference/script-hooks-reference) for a complete list of all available.

## Scripts

At the core, app scripts are [twig files](https://twig.symfony.com/) executed in a sandboxed environment. Based on which hook the script is registered to, the script has access to the data of that hook and pre-defined services that can be used to execute your custom logic.

Apps scripts are placed in the `Resources/scripts` directory of your app. For each hook, you want to execute a script on, create a new subdirectory. The name of the subdirectory needs to match the name of the hook.

You can place one or more `.twig` files inside each of these subdirectories, which will be executed when the hook gets triggered.

The file structure of your apps should look like this:

```text
└── DemoApp
    ├── Resources
    │   └── scripts                         // all scripts are stored in this folder
    │       ├── product-page-loaded         // each script in this folder will be executed when the `product-page-loaded` hook is triggered
    │       │   └── my-first-script.twig
    │       ├── cart
    │       │   ├── first-cart-script.twig
    │       │   └── second-cart-script.twig // you can execute multiple scripts per hook
    │       └── ...
    └── manifest.xml
```

### Including scripts

Sometimes scripts can become more complex or you want to extract common functionality. Thus it is handy to split your scripts into smaller parts that can later be included in other scripts.

In order to do that you can compose your reusable scripts into [twig macros](https://twig.symfony.com/doc/3.x/tags/macro.html), put them inside a dedicated `include` folder and then import them using the [twig import functionality](https://twig.symfony.com/doc/3.x/tags/import.html).

```text
└── DemoApp
    ├── Resources
    │   └── scripts                         
    │       ├── include    
    │       │   └── media-repository.twig         // this script may be included into the other scripts
    │       ├── cart
    │       │   ├── first-cart-script.twig
    │       └── ...
    └── manifest.xml
```

Note that app scripts can use the `return` keyword to return values to the caller.

A basic example may look like this:

```twig
// Resources/scripts/include/media-repository.twig
{% macro getById(mediaId) %}
    {% set criteria = {
        'ids': [ mediaId ]
    } %}
    
     {% return services.repository.search('media', criteria).first %}
{% endmacro %}
```

```twig
// Resources/scripts/cart/first-cart-script.twig
{% import "include/media-repository.twig" as mediaRepository %}

{% set mediaEntity = mediaRepository.getById(myMediaId) %}
```

### Interface Hooks

Some "Hooks" describe interfaces this means that your scripts for that hook need to implement one or more functions.
E.g., the `store-api-hook` defines a `cache_key` and a `response` function. Those functions are closely related but are executed separately.
To implement the different functions, you use different twig blocks with the name of the function:

```twig
{% block cache_key %}
    // provide a cacheKey for the incoming request
{% endblock %}

{% block response %}
    // produce the response for the request
{% endblock %}
```

Some functions are optional, whereas others are required. In the above example the `cache_key` function is optional.
That means you can omit that block in your script without an error (but caching for the endpoint won't work in that case).
The `response` function is required, which means that if your script does not provide a `response` block, it will lead to an error.

Note that for each function, you get access to different input data or services, so in the `cache_key` block, you don't necessarily have access to the same data and services as in the `response` block.
The available data and services are described for each hook (or each function in InterfaceHooks) in the [reference documentation](../../../../resources/references/app-reference/script-reference/script-hooks-reference).

### Translation

Inside the app script, you have access to the [Storefront translation mechanism](../../plugins/storefront/add-translations) by using the `|trans`-filter.

```twig
{% set translated = 'my.snippet.key'|trans %}

{% do call.something('my.snippet.key'|trans) %}
```

### Extended syntax

In addition to the default twig syntax, app scripts can also use a more PHP-flavoured syntax.

#### Equals check with `===`

Instead of using the rather verbose `{% if var is same as(1) %}`, you can use the more dense `===` equality checks.

```twig
{% if var === 1 %}
    ...
{% endif %}
```

Additionally, you can also use the `!==` not equals operator as well.

```twig
{% if var !== 1 %}
    ...
{% endif %}
```

#### Loops with `foreach`

Instead of the `for...in` syntax for loops, you can also use a `foreach` tag.

```twig
{% foreach list as entry %}
    {{ entry }}
    {% break %}
{% endforeach %}
```

#### Instance of checks with `is`

You can use a `is` check to check the type of a variable.

```twig
{% if var is string %}
    ...
{% endif %}
```

The following types are supported:

* `true`
* `false`
* `boolean` / `bool`
* `string`
* `scalar`
* `object`
* `integer` / `int`
* `float`
* `callable`
* `array`

#### Type casts with `intval`

You can cast variables into different types with the `intval` filter.

```twig
{% if '5'|intval === 5 %}
    {# always evaluates to true #}
{% endif %}
```

The following type casts are supported:

* `intval`
* `strval`
* `boolval`
* `floatval`

#### conditions with `&&` and `||`

Instead of using `AND` or `OR` in if-conditions, you can use the `&&` or `||` shorthands.

```twig
{% if condition === true && condition2 === true %}
    ...
{% endif %}
```

#### `return` tag

You can use the `return` tag to return values from inside macros.

```twig
{% macro foo() %} 
     {% return 'bar' %}
{% endmacro %}
```

## Available services

Depending on the hook that triggered the execution of your script, you get access to different services you can use inside your scripts, e.g. to access data inside Shopware or to manipulate the cart.
Take a look at the [Hook reference](../../../../resources/references/app-reference/script-reference/script-hooks-reference) to get a complete list of all available services per hook.

Additionally, we added a `ServiceStubs`class that can be used as typehint in your script, so you get auto-completion features of your IDE.

```twig
{# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

{% set configValue = services.config.app('my-app-config') %}
```

::: info
The stub class contains all services, but not all of them are available depending on the hook.
:::

## Example Script - loading media entities

Assuming your app adds a [custom field set](../custom-data/custom-fields) for the product entity with a custom media entity select field.

When you want to display the file of the media entity in the [Storefront](../storefront/), it is not easily possible because, in the template's data, you only get the id of the media entity, but not the URL of the media file itself.

For this case, you can add an app script on the `product-page-loaded`
hook, which loads the media entity by id and adds it to the page object so the data is available in templates.

```twig
// Resources/scripts/product-page-loaded/add-custom-media.twig
{# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

{% set page = hook.page %}
{# @var page \Shopware\Storefront\Page\Product\ProductPage #}

{% if page.product.customFields.myCustomMediaField is not defined %}
    {% return %}
{% endif %}

{% set criteria = {
    'ids': [ page.product.customFields.myCustomMediaField ]
} %}

{% set media = services.repository.search('media', criteria).first %}

{% do page.addExtension('swagMyCustomMediaField', media) %}
```

For a more detailed example of how to load additional data, refer to the [data loading guide](./data-loading).

Alternatively, take a look at the [cart manipulation guide](./cart-manipulation) to get an in-depth explanation of how to manipulate the cart with scripts.

## Developing/debugging scripts

You can get information about what scripts were triggered on a specific Storefront page inside the [Symfony debug toolbar](https://symfony.com/doc/current/the-fast-track/en/5-debug.html#discovering-the-symfony-debugging-tools).

::: info
The debug toolbar is only visible if your Shopware installation is in `APP_ENV = dev`. Ensure to set the correct env, e.g., in your `.env` file, when developing app scripts.
:::

You can find all hooks that are triggered and the scripts that are executed for each by clicking on the `script` icon.

![Symfony Debug Toolbar](../../../../assets/script-debug-toolbar.png)

That will open the Symfony profiler in the script detail view, where you can see all triggered hooks and the count of the scripts executed for each script at the top.

![Script Debug Toolbar](../../../../assets/script-debug-detail.png)

Additionally, you can use the `debug.dump()` function inside your scripts to dump data to the debug view.
A script like this:

```twig
{% do debug.dump(hook.page) %}
```

Will dump the page object to the debug view.

![Output of debug.dump()](../../../../assets/script-debug-dump.png)

---

---
url: /docs/v6.6/guides/plugins/apps/app-scripts.md
---

# App Scripts

App Scripts allow your app to include logic that is executed inside the Shopware execution stack. It allows you to build richer extensions that integrate more deeply with Shopware.

::: info
Note that app scripts were introduced in Shopware 6.4.8.0 and are not supported in previous versions.
:::

## Script hooks

The entry point for each script is the so-called "Hooks". You can register one or more scripts inside your app that should be executed whenever a specific hook is triggered.
Through the hook, your script gets access to the data of the current execution context and can react to or manipulate the data in some way.

See the [Hooks reference](../../../../resources/references/app-reference/script-reference/script-hooks-reference) for a complete list of all available.

## Scripts

At the core, app scripts are [twig files](https://twig.symfony.com/) executed in a sandboxed environment. Based on which hook the script is registered to, the script has access to the data of that hook and pre-defined services that can be used to execute your custom logic.

Apps scripts are placed in the `Resources/scripts` directory of your app. For each hook, you want to execute a script on, create a new subdirectory. The name of the subdirectory needs to match the name of the hook.

You can place one or more `.twig` files inside each of these subdirectories, which will be executed when the hook gets triggered.

The file structure of your apps should look like this:

```text
└── DemoApp
    ├── Resources
    │   └── scripts                         // all scripts are stored in this folder
    │       ├── product-page-loaded         // each script in this folder will be executed when the `product-page-loaded` hook is triggered
    │       │   └── my-first-script.twig
    │       ├── cart
    │       │   ├── first-cart-script.twig
    │       │   └── second-cart-script.twig // you can execute multiple scripts per hook
    │       └── ...
    └── manifest.xml
```

### Including scripts

Sometimes scripts can become more complex or you want to extract common functionality. Thus it is handy to split your scripts into smaller parts that can later be included in other scripts.

In order to do that you can compose your reusable scripts into [twig macros](https://twig.symfony.com/doc/3.x/tags/macro.html), put them inside a dedicated `include` folder and then import them using the [twig import functionality](https://twig.symfony.com/doc/3.x/tags/import.html).

```text
└── DemoApp
    ├── Resources
    │   └── scripts                         
    │       ├── include    
    │       │   └── media-repository.twig         // this script may be included into the other scripts
    │       ├── cart
    │       │   ├── first-cart-script.twig
    │       └── ...
    └── manifest.xml
```

Note that app scripts can use the `return` keyword to return values to the caller.

A basic example may look like this:

```twig
// Resources/scripts/include/media-repository.twig
{% macro getById(mediaId) %}
    {% set criteria = {
        'ids': [ mediaId ]
    } %}
    
     {% return services.repository.search('media', criteria).first %}
{% endmacro %}
```

```twig
// Resources/scripts/cart/first-cart-script.twig
{% import "include/media-repository.twig" as mediaRepository %}

{% set mediaEntity = mediaRepository.getById(myMediaId) %}
```

### Interface Hooks

Some "Hooks" describe interfaces this means that your scripts for that hook need to implement one or more functions.
E.g., the `store-api-hook` defines a `cache_key` and a `response` function. Those functions are closely related but are executed separately.
To implement the different functions, you use different twig blocks with the name of the function:

```twig
{% block cache_key %}
    // provide a cacheKey for the incoming request
{% endblock %}

{% block response %}
    // produce the response for the request
{% endblock %}
```

Some functions are optional, whereas others are required. In the above example the `cache_key` function is optional.
That means you can omit that block in your script without an error (but caching for the endpoint won't work in that case).
The `response` function is required, which means that if your script does not provide a `response` block, it will lead to an error.

Note that for each function, you get access to different input data or services, so in the `cache_key` block, you don't necessarily have access to the same data and services as in the `response` block.
The available data and services are described for each hook (or each function in InterfaceHooks) in the [reference documentation](../../../../resources/references/app-reference/script-reference/script-hooks-reference).

### Translation

Inside the app script, you have access to the [Storefront translation mechanism](../../plugins/storefront/add-translations) by using the `|trans`-filter.

```twig
{% set translated = 'my.snippet.key'|trans %}

{% do call.something('my.snippet.key'|trans) %}
```

### Extended syntax

In addition to the default twig syntax, app scripts can also use a more PHP-flavoured syntax.

#### Equals check with `===`

Instead of using the rather verbose `{% if var is same as(1) %}`, you can use the more dense `===` equality checks.

```twig
{% if var === 1 %}
    ...
{% endif %}
```

Additionally, you can also use the `!==` not equals operator as well.

```twig
{% if var !== 1 %}
    ...
{% endif %}
```

#### Loops with `foreach`

Instead of the `for...in` syntax for loops, you can also use a `foreach` tag.

```twig
{% foreach list as entry %}
    {{ entry }}
    {% break %}
{% endforeach %}
```

#### Instance of checks with `is`

You can use a `is` check to check the type of a variable.

```twig
{% if var is string %}
    ...
{% endif %}
```

The following types are supported:

* `true`
* `false`
* `boolean` / `bool`
* `string`
* `scalar`
* `object`
* `integer` / `int`
* `float`
* `callable`
* `array`

#### Type casts with `intval`

You can cast variables into different types with the `intval` filter.

```twig
{% if '5'|intval === 5 %}
    {# always evaluates to true #}
{% endif %}
```

The following type casts are supported:

* `intval`
* `strval`
* `boolval`
* `floatval`

#### conditions with `&&` and `||`

Instead of using `AND` or `OR` in if-conditions, you can use the `&&` or `||` shorthands.

```twig
{% if condition === true && condition2 === true %}
    ...
{% endif %}
```

#### `return` tag

You can use the `return` tag to return values from inside macros.

```twig
{% macro foo() %} 
     {% return 'bar' %}
{% endmacro %}
```

## Available services

Depending on the hook that triggered the execution of your script, you get access to different services you can use inside your scripts, e.g. to access data inside Shopware or to manipulate the cart.
Take a look at the [Hook reference](../../../../resources/references/app-reference/script-reference/script-hooks-reference) to get a complete list of all available services per hook.

Additionally, we added a `ServiceStubs`class that can be used as typehint in your script, so you get auto-completion features of your IDE.

```twig
{# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

{% set configValue = services.config.app('my-app-config') %}
```

::: info
The stub class contains all services, but not all of them are available depending on the hook.
:::

## Example Script - loading media entities

Assuming your app adds a [custom field set](../custom-data/custom-fields) for the product entity with a custom media entity select field.

When you want to display the file of the media entity in the [Storefront](../storefront/), it is not easily possible because, in the template's data, you only get the id of the media entity, but not the URL of the media file itself.

For this case, you can add an app script on the `product-page-loaded`
hook, which loads the media entity by id and adds it to the page object so the data is available in templates.

```twig
// Resources/scripts/product-page-loaded/add-custom-media.twig
{# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

{% set page = hook.page %}
{# @var page \Shopware\Storefront\Page\Product\ProductPage #}

{% if page.product.customFields.myCustomMediaField is not defined %}
    {% return %}
{% endif %}

{% set criteria = {
    'ids': [ page.product.customFields.myCustomMediaField ]
} %}

{% set media = services.repository.search('media', criteria).first %}

{% do page.addExtension('swagMyCustomMediaField', media) %}
```

For a more detailed example of how to load additional data, refer to the [data loading guide](./data-loading).

Alternatively, take a look at the [cart manipulation guide](./cart-manipulation) to get an in-depth explanation of how to manipulate the cart with scripts.

## Developing/debugging scripts

You can get information about what scripts were triggered on a specific Storefront page inside the [Symfony debug toolbar](https://symfony.com/doc/current/the-fast-track/en/5-debug.html#discovering-the-symfony-debugging-tools).

::: info
The debug toolbar is only visible if your Shopware installation is in `APP_ENV = dev`. Ensure to set the correct env, e.g., in your `.env` file, when developing app scripts.
:::

You can find all hooks that are triggered and the scripts that are executed for each by clicking on the `script` icon.

![Symfony Debug Toolbar](../../../../assets/script-debug-toolbar.png)

That will open the Symfony profiler in the script detail view, where you can see all triggered hooks and the count of the scripts executed for each script at the top.

![Script Debug Toolbar](../../../../assets/script-debug-detail.png)

Additionally, you can use the `debug.dump()` function inside your scripts to dump data to the debug view.
A script like this:

```twig
{% do debug.dump(hook.page) %}
```

Will dump the page object to the debug view.

![Output of debug.dump()](../../../../assets/script-debug-dump.png)

---

---
url: /docs/guides/plugins/apps/app-sdks.md
---

# App SDKs

The Shopware app SDK enables you to build applications and plugins that extend the functionality of the Shopware e-commerce platform. It provides the necessary resources and tools to simplify the development process and integrate custom logic into the Shopware environment.

| **Layer** | **Type** | **Core strengths** | **Security / ops** | **What it lacks** | **Registration flow** | **Lifecycle handling** | **Webhook handling** | **Authenticated HTTP client** | **Storage / persistence** | **Storage backends** | **Structured errors** | **Framework integration** | **Agnostic core** |
| --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- | --- |
| [Meteor Admin SDK](../administration/meteor-admin-sdk.md) | Frontend | Admin UI extensions for apps and plugins | Extends the Shopware Admin UI; notifications, context/location access, UI/data integration; TypeScript; dependency-free; tree-shakable | Not relevant as a backend/ops SDK | No backend capabilities such as registration, webhook verification, lifecycle handling, or shop persistence | No | No| No | No | No | None | No | N/A | Yes, as a frontend TS SDK |
| [App SDK for PHP](../app-sdks/php/index.md) | Backend | PHP / Symfony-style app backends | Strong core backend coverage: registration, lifecycle, action parsing into structs, events, signing, context handling, HTTP client; PSR-based; Symfony Bundle available | Solid fundamentals | Less explicit support for replay protection, storage backends, response builders, structured errors, and middleware/extensibility | Yes | Yes | Yes | Yes | Some abstraction, but not a major feature | Not prominently surfaced | Not prominently surfaced | Symfony Bundle | Yes |
| [App Server SDK in TypeScript](../app-sdks/javascript/index.md) | Backend | TS/JS backends, Node, Deno, Cloudflare Workers, serverless / edge | Runtime portability; strong story around registration, signing/verification, preconfigured API client, complete registration handshake | Good portability | Less explicit coverage for lifecycle handling, webhook ergonomics, storage/persistence, structured errors, and response helpers | Yes | Not strongly surfaced | Not strongly surfaced | Yes | Not clearly surfaced | Not prominently surfaced | Not prominently surfaced | Example-led, less framework-focused | Yes, across Node, Deno, Workers, and similar runtimes |

---

---
url: /docs/v6.5/guides/plugins/apps/app-sdks.md
---

# App SDKs

The Shopware app SDK enables you to build applications and plugins that extend the functionality of the Shopware e-commerce platform. It provides the necessary resources and tools to simplify the development process and integrate custom logic into the Shopware environment.

---

---
url: /docs/v6.6/guides/plugins/apps/app-sdks.md
---

# App SDKs

The Shopware app SDK enables you to build applications and plugins that extend the functionality of the Shopware e-commerce platform. It provides the necessary resources and tools to simplify the development process and integrate custom logic into the Shopware environment.

---

---
url: /docs/v6.5/guides/plugins/apps/starter.md
---

# App Starter Guides

The app starter guide provides a comprehensive approach to extending the platform's functionality. The following section guides you on creating custom API endpoints with App scripts, reading and writing data to/from Shopware, and creating custom admin extensions.

---

---
url: /docs/v6.6/guides/plugins/apps/starter.md
---

# App Starter Guides

The app starter guide provides a comprehensive approach to extending the platform's functionality. The following section guides you on creating custom API endpoints with App scripts, reading and writing data to/from Shopware, and creating custom admin extensions.

---

---
url: /docs/v6.6/products/sales-agent/appearance.md
---

# Appearance

To change the appearance of your Sales Agent, you can customize the theme, colors, and logo.

## Regarding SCSS

Currently SCSS (or Sass) is included as a dev dependency in our project (see `package.json`). This is a dependency needed as a peer dependency of the meteor component library. However, we discourage you from using SCSS, as we will likely remove it from Sales Agent in the future. The reason for this is that we already provide a powerful framework for styling your frontend (UnoCSS), which is also integrated into the Shopware Frontends framework.

## Config, favicon and logo

You can customize your sales agent by editing the app and configuring it in your `config.ts` file. Additionally, favicon and logo can be easily replaced in the following paths. Please consider using square dimensions for the image file if possible:

* Favicon: `./public/favicon.ico`
* Logo: `./public/logo.svg`

---

---
url: /docs/products/paas/shopware/fundamentals/application-yaml.md
---

# Application YAML Configuration

The `application.yaml` file is the central configuration file for your Shopware PaaS Native application. It is placed at the root of your project repository and defines the PHP version, environment variables, and services for your application.

When you update the `application.yaml` and push the changes to your repository, apply them by running:

```sh
sw-paas application update
```

## Structure

The file consists of two main sections:

| Section    | Description                                                        |
|------------|--------------------------------------------------------------------|
| `app`      | Application settings such as PHP version and environment variables |
| `services` | Infrastructure services like MySQL and OpenSearch                  |

## Minimal example

```yaml
app:
  php:
    version: "8.3"
    extensions: []
  environment_variables: []
services:
  mysql:
    version: "8.0"
  opensearch:
    enabled: false
```

## Full example

```yaml
app:
  php:
    version: "8.3"
    extensions:
      - imagick
  environment_variables:
    - name: INSTALL_LOCALE
      value: fr-FR
      scope: RUN
    - name: MY_BUILDTIME_VARIABLE
      value: bar
      scope: BUILD
services:
  mysql:
    version: "8.0"
  opensearch:
    enabled: true
```

## Reference

### `app.php.version`

The PHP version used by the application.

```yaml
app:
  php:
    version: "8.3"
```

### `app.php.extensions`

The PHP extensions to install during build time. We use [this](https://github.com/mlocati/docker-php-extension-installer) installer to install extensions.

```yaml
app:
  php:
    extensions:
      - extension1
      - extension2
```

### `app.environment_variables`

A list of environment variables is passed to the application. Each entry requires:

| Field   | Description                          | Values         |
|---------|--------------------------------------|----------------|
| `name`  | The variable name                    | Any string     |
| `scope` | When the variable is available       | `RUN`, `BUILD` |
| `value` | The variable value                   | Any string     |

* **`RUN`** -- available at runtime (passed to the Shopware application).
* **`BUILD`** -- available during the build step.

You can define the same variable name with different scopes to use different values at build-time and runtime.

```yaml
app:
  environment_variables:
    - name: MY_VARIABLE
      value: runtime-value
      scope: RUN
    - name: MY_VARIABLE
      value: build-value
      scope: BUILD
```

For sensitive values, use [secrets](./secrets.md) instead of environment variables.

For more details, see the [Environment variables](./environment-variables.md) page.

### `services.mysql`

Configures the managed MySQL database. Shopware PaaS Native supports MySQL versions `8.0` and `8.4`.

```yaml
services:
  mysql:
    version: "8.4"
```

Once MySQL `8.4` has been configured, downgrading to MySQL `8.0` is not possible.

### `services.opensearch`

Enables or disables the managed OpenSearch service.

```yaml
services:
  opensearch:
    enabled: true
```

After enabling OpenSearch, update your application and reindex your data. See [How to set up OpenSearch](../guides/opensearch.md) for the full steps.

---

---
url: /docs/products/paas/shopware/fundamentals/applications.md
---

# Applications

Shopware PaaS Native supports multiple applications within a project, such as environments for production, staging, or temporary feature testing.

Each application has its own compute resources, infrastructure, and deployment configuration, so you can tailor each environment to its specific needs.

For instance, you might allocate smaller, hibernating compute instances for staging while reserving larger, always-on resources for production.

The number of projects and applications available to an organization depends on the booked plan.

## Default resource profile and scaling

Applications are provisioned with a default resource profile for the main Shopware workloads:

| Component    | Default replicas | CPU request | Memory request | Memory limit |
|--------------|------------------|-------------|----------------|--------------|
| `storefront` | `2`              | `50m`       | `256Mi`        | `2Gi`        |
| `admin`      | `1`              | `25m`       | `128Mi`        | `2Gi`        |
| `worker`     | `1`              | `50m`       | `256Mi`        | `1Gi`        |

Horizontal scaling is the primary scaling mechanism in Shopware PaaS Native.

Resource limits above the default profile depend on the booked plan, with some flexibility for scaling within that scope.

## Creating an Application

Create a new application to a project:

```sh
sw-paas application create
```

## Build your application

To trigger a new build for the application via CLI, use the following command:

```sh
sw-paas application build start
```

This command initiates the build process, packaging your application and preparing it for deployment. While the build is running, you can monitor its progress and view real-time output by following the logs:

```sh
sw-paas application build logs
```

Builds run as regular Docker builds. External network requests are allowed during the build when your project requires them, for example to reach configured Composer repositories or other external package sources.

If your build needs credentials or other sensitive values, provide them through [Vault secrets](./secrets.md) using `buildenv` or by using `BUILD`-scoped environment variables where appropriate.

## Update your application

To update your application, you need to run the following command and provide the commit SHA:

```sh
sw-paas application update
```

This command initiates the build process, waits until it's done, and runs the deployment for you.

## Deployment behavior

Deployments are designed to be zero downtime and use Kubernetes rolling updates.

During deployment, database migrations run first. After that, the remaining deployment flow is handled by the [deployment helper](../../../../guides/hosting/installation-updates/deployments/deployment-helper#execution-flow).

This works well for regular Shopware deployments because breaking database changes are expected only during major Shopware upgrades. When upgrading across major versions, make sure your deployment remains backward compatible throughout the rollout.

Pre-deployment and post-deployment hooks are supported through the [deployment helper configuration](../../../../guides/hosting/installation-updates/deployments/deployment-helper#configuration).

Automated deployments from CI/CD are supported. The CLI can run in non-interactive mode and supports machine-to-machine authentication with tokens.

You can inspect runtime logs with:

```sh
sw-paas application logs
```

Deployment setup and migration logs are available with:

```sh
sw-paas application deploy logs
```

Both commands print a Grafana Explore URL at the end so you can continue investigating the same logs in Grafana. For more log filtering options, see [Logs](../monitoring/logs).

## Deploy a specific build of your application

To create a deployment with a specific build, use the following command:

```sh
sw-paas application deploy create
```

It will let you choose which build you want to deploy.
This is very handy, since you can choose any successful build to deploy: the latest one to bring your change live, or a previous one to fix an issue that arose.

## Deployments management

To list all past deployments:

```sh
sw-paas application deploy list
```

To get details about a given deployment:

```sh
sw-paas application deploy get
```

To back up and restore application assets and database data, see [Snapshots](./snapshots.md).

## Plugin Management

Plugin management is done [via Composer](../../../../guides/hosting/installation-updates/extension-management#installing-extensions-with-composer) because the platform runs in a high-availability and clustered environment.

In such setups, local changes aren't feasible, as all instances must remain identical and stateless. This ensures consistency across all deployments.

### Using Privately Hosted Packages

To pull privately hosted Composer packages, you need to provide authentication credentials. Create a `COMPOSER_AUTH` secret using the CLI:

```sh
sw-paas vault create
```

Follow the prompts to enter your Composer authentication JSON as a `buildenv`. This secret will be used during builds to access private repositories.

## Executing Commands

Shopware PaaS Native provides two primary ways to run commands in your application environments via CLI: `exec` and `command`.

### `exec` Command

The `exec` command allows you to execute commands in a remote terminal session for your applications. This is useful for running commands directly on your application's environment, such as debugging, maintenance, or running one-off commands interactively.

```sh
sw-paas exec --new
```

This opens an interactive shell session inside your application's container.

#### Note

Please check the [known issues](../known-issues.md) regarding network considerations when running this command.

### `command` Command

The `command` command lets you create and manage commands that are executed in dedicated containers. This is particularly useful for CI/CD environments, asynchronous command execution, automated processes, or situations where you don't need to wait for command completion.

Unlike `exec`, which provides an interactive shell, `command` runs your specified command in a new, isolated container and does not require you to wait for its completion.

The default execution directory is `/var/www/html` and the container has a time-to-live (TTL) of 1 hour, so your command must complete within that timeframe.

```sh
sw-paas command create
```

For a complete list of available commands, refer to the [Shopware console commands documentation](https://docs.shopware.com/en/shopware-6-en/tutorials-and-faq/shopware-cli).

## Domain Management

### Shopware Domain

When you deploy an application for the first time, it automatically receives a complimentary `shopware.shop` domain. This allows you to access and test your application right away, even before setting up a custom domain.

The assigned domain is generated based on your application's name and unique identifier.

### Custom Domain

You can configure custom domains for your applications using the `sw-paas` CLI domain command. This allows you to attach multiple domains to a single application and route traffic through the Fastly CDN for optimal performance.

#### Creating Custom Domains

To create a custom domain for your application:

```sh
sw-paas domain create
```

Follow the prompts to specify your domain name and application. You can attach multiple domains to a single application.

#### DNS Configuration

After creating a custom domain, you must configure your DNS settings to point to the PaaS CDN endpoint:

**Configure your custom domain's DNS to point to:**

```dns
cdn.shopware.shop
```

This configuration ensures that all traffic to your custom domain is routed through the Fastly CDN for optimal performance and caching.

#### Application Deployment

Following domain creation, you must redeploy your application. You can do it by using:

```sh
sw-paas application deploy create
```

#### Shopware Configuration

Subsequently, you can configure the domain within Shopware and associate it with a storefront. Status update functionality is currently under development and should be considered a beta feature.

For more detailed information about CDN configuration and best practices, refer to the [CDN documentation](../cdn/index.md).

---

---
url: /docs/v6.6/products/paas/shopware/CLI/applications.md
---

# Applications

The `application` command manages deployments in Shopware PaaS Native. Each application represents a deployment of your codebase within a project. Projects can contain multiple applications (e.g., for staging, production).

## Usage

```sh
sw-paas application [command]
```

## Commands

### Creating an Application

Deploy a new application to a project.

**Usage:**

```sh
sw-paas application create [flags]
```

**Flags:**

* `--project-id`: ID of the target project. If not provided, the CLI will try to fetch it from the repository.
* `--name`: Name of the application. If not provided, the CLI will prompt for it.
* `--commit-sha`: Commit SHA to deploy. If not provided, the CLI will prompt for it.
* `--help`: Display help for the command.

**Example:**

```sh
sw-paas application create --project-id "proj-1" --name "my-app" --commit-sha "abcdef123456"
```

### Updating an Application

Update an existing application with a new commit SHA.

**Usage:**

```sh
sw-paas application update [flags]
```

**Flags:**

* `--project-id`: ID of the project.
* `--application-id`: ID of the application.
* `--commit-sha`: Commit SHA to deploy.
* `--help`: Display help for the command.

**Example:**

```sh
sw-paas application update --project-id "proj-1" --application-id "app-1" --commit-sha "abcdef123456"
```

### Listing Applications

List all applications associated with a specific project.

**Usage:**

```sh
sw-paas application list [flags]
```

**Flags:**

* `--project-id`: ID of the project.
* `--help`: Display help for the command.

**Example:**

```sh
sw-paas application list --project-id "proj-1"
```

### Checking Applications

Check the status of applications.

**Usage:**

```sh
sw-paas application check [flags]
```

**Flags:**

* `--project-id`: ID of the project.
* `--application-id`: ID of the application.
* `--help`: Display help for the command.

## Build Commands

### Listing Builds

List all builds for a specific application.

**Usage:**

```sh
sw-paas application build list [flags]
```

**Flags:**

* `--application-id`: ID of the application.
* `--organization-id`: ID of the organization.
* `--project-id`: ID of the project.
* `--help`: Display help for the command.

**Example:**

```sh
sw-paas application build list --organization-id "org-1" --project-id "proj-1" --application-id "app-1"
```

### Viewing Build Logs

Display logs of a specific build.

**Usage:**

```sh
sw-paas application build logs [flags]
```

**Flags:**

* `--application-id`: ID of the application.
* `--application-build-id`: ID of the build.
* `--organization-id`: ID of the organization.
* `--project-id`: ID of the project.
* `--help`: Display help for the command.

**Example:**

```sh
sw-paas application build logs --organization-id "org-1" --project-id "proj-1" --application-id "app-1" --application-build-id "build-1"
```

### Starting a Build

Trigger a new build for the specified application.

**Usage:**

```sh
sw-paas application build start [flags]
```

**Flags:**

* `--application-id`: ID of the application.
* `--organization-id`: ID of the organization.
* `--project-id`: ID of the project.
* `--help`: Display help for the command.

**Example:**

```sh
sw-paas application build start --organization-id "org-1" --project-id "proj-1" --application-id "app-1"
```

### Deleting an Application

Delete an existing application from a project.

**Usage:**

```sh
sw-paas application delete [flags]
```

**Flags:**

* `--application-id`: ID of the application to be deleted (required).
* `--project-id`: ID of the project (optional, fetched if omitted).
* `--help`: Display help for the command.

**Example:**

```sh
sw-paas application delete --application-id "app-1" --project-id "proj-1"
```

---

---
url: /docs/resources/references/adr/2026-01-28-apply-opensearch-in-admin-api.md
---

# Apply OpenSearch globally for admin-api

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2026-01-28-apply-opensearch-in-admin-api.md)
:::

# Apply OpenSearch globally

## Context

The administration already indexes entities in OpenSearch to power the global search, yet detail listings, filters, and component-level lookups (e.g. `sw-search-bar`, `sw-entity-single-select`, `sw-data-grid`) still rely on classic MySQL queries. When a merchant clicks "Show all matching results" the experience drops back to slow SQL queries because the current implementation does not support the listing, defeating the purpose of keeping an admin index up to date.
As catalog sizes continue to grow, this discrepancy adds latency, produces inconsistent search quality, and increases load on the primary database even though the data is already available in OpenSearch.

We therefore need an approach that allows administration modules/Admin API searches to reuse the OpenSearch index wherever supported while still keeping a safe fallback path for definitions that are not indexed.

## Decision

* Introduce `Shopware\Elasticsearch\Admin\AdminElasticsearchEntitySearcher` to decorate the DAL `EntitySearcherInterface`. Whenever the `AdminSearchRegistry` signals that an entity supports OpenSearch and the request context opts in, the decorator forwards the criteria to OpenSearch instead of querying MySQL. Unsupported entities continue to use the previous MySQL behaviour automatically.

### Currently supported entities

The following Admin API entities already expose admin OpenSearch indexers and therefore benefit from the new searcher when the feature flag is active:

* Category (`category`)
* Customer (`customer`)
* Landing page (`landing_page`)
* Manufacturer (`product_manufacturer`)
* Media (`media`)
* Newsletter recipient (`newsletter_recipient`)
* Order (`order`)
* Product (`product`)
* Promotion (`promotion`)
* Property group (`property_group`)

They are selected because they represent the most commonly searched/filter entities in the administration and usually contain a large number of records that benefit from OpenSearch performance.

### Conditions to forward a search request to opensearch

```php
  function allowAdminEsSearch(EntityDefinition $definition, Context $context, Criteria $criteria): bool
  {
      if (!Feature::isActive('ENABLE_OPENSEARCH_FOR_ADMIN_API')) {
        return false; // the feature flag is turned off
      }

      if (!$this->helper->isEnabled()) {
        return false; // admin es search is turned off
      }

      if (!$context->getSource() instanceof AdminApiSource) {
          return false; // only Admin API requests can use admin ES
      }

      if (!$criteria->getIds() === []) {
          return false; // explicit ID filters stay on SQL
      }

      if (!$this->registry->hasIndexer($definition->getEntityName())) {
          return false;
      }
      
      // if no filters, aggregations, queries etc, we can use es
      if ($criteria->getTerm() && $criteria->getAllFields() === []) {
          return true;
      }

      $indexer = $this->registry->getIndexer($definition->getEntityName());

      // no field is marked for ES index, skip it
      if ($indexer->mapping([]) === []) {
          return false;
      }

      // use opensearch if all querying fields are supported
      return array_diff(
          $criteria->getAllFields(),
          $indexer->getSupportedSearchFields()
      ) === [];
  }
```

In practice, any Admin API search without explicit ID or term filters whose filters or sorts exist in the indexer's supported field list automatically hits OpenSearch (e.g. product listings filtering by `active`, `manufacturerId`, or `stock`), while every other query falls back to the decorated MySQL searcher.

* Keep the functionality behind the explicit feature flag `ENABLE_OPENSEARCH_FOR_ADMIN_API`. Only when the feature flag is active and admin OpenSearch itself is configured/enabled do we forward DAL searches to OpenSearch. This lets us roll out the change gradually, collect feedback, and still unblock projects that need the old behaviour.
* Extend the admin indexes with the fields that are actually used for searching or filtering via standard Shopware criteria. To keep index size and performance in check we only add the commonly used admin fields and store them as keyword fields. Projects that require additional fields must extend the mapping and indexing on their own.

For example, `src/Elasticsearch/Admin/Indexer/ProductAdminSearchIndexer.php` defines the following mapping overrides:

```php
  public function mapping(array $mapping): array
  {
      $override = [
          'parentId' => AbstractElasticsearchDefinition::KEYWORD_FIELD,
          'available' => AbstractElasticsearchDefinition::BOOLEAN_FIELD,
          'releaseDate' => ElasticsearchFieldBuilder::datetime(),
          'categories' => ElasticsearchFieldBuilder::nested([
              'id' => AbstractElasticsearchDefinition::KEYWORD_FIELD,
          ]),
          // ...
      ];

      $mapping['properties'] ??= [];
      $mapping['properties'] = array_merge($mapping['properties'], $override);

      return $mapping;
  }
```

The same indexer exposes the corresponding fetch logic that selects the fields from MySQL and structures them before they are sent to OpenSearch:

```php
  public function fetch(array $ids): array
  {
      $baseSql = <<<'SQL'
          SELECT LOWER(HEX(product.id)) as id,
             GROUP_CONCAT(DISTINCT translation.name SEPARATOR " ") as name,
             product.product_number as productNumber,
             product.stock as stock,
             IFNULL(product.release_date, parent.release_date) AS releaseDate,
             #visibilities#
          FROM product
            LEFT JOIN product parent ON (product.parent_id = parent.id AND parent.version_id = :versionId)
            LEFT JOIN product_visibility ON (...)
          WHERE product.id IN (:ids)
          GROUP BY product.id
      SQL;

      // hydrate rows into the structure expected by AdminSearcher
  }
```

External extensions that require more fields should decorate the concrete indexer service (e.g. `Shopware\\Elasticsearch\\Admin\\Indexer\\ProductAdminSearchIndexer`) and append their own mapping/fetch logic:

```php
  class CustomProductAdminSearchIndexer extends AbstractAdminIndexer
  {
      public function __construct(private readonly ProductAdminSearchIndexer $inner) {}

      public function mapping(array $mapping): array
      {
          $mapping = $this->inner->mapping($mapping);
          $mapping['properties']['fooField'] = AbstractElasticsearchDefinition::KEYWORD_FIELD;

          return $mapping;
      }

      public function fetch(array $ids): array
      {
          $fooFieldsData = $this->loadFooFields($ids)
          $data = $this->inner->fetch($ids);
          foreach ($data as &$row) {
              $row['fooField'] = $fooFieldsData[$row['id'])];
          }

          return $data;
      }
  }
```

The decorator is then registered via Symfony service decoration so that it wraps the core indexer without modifying Shopware code.

```xml
<service id="Foo\Your\Custom\ProductAdminSearchIndexerDecorator" decorates="Shopware\Elasticsearch\Admin\Indexer\ProductAdminSearchIndexer" on-invalid="null">
  <argument type="service" id=".inner"/>
</service>
```

**It's important to define the decorator with `on-invalid="ignore"` in case the Elasticsearch bundle is not registered in the project.**

For a custom entity that you want to add to the list of supported entities, it's important to register the service with tag `shopware.elastic.admin-searcher-index` like following

```xml
<tag name="shopware.elastic.admin-searcher-index" key="<your_entity_name>"/>
```

### Troubleshooting

* The search result from `\Shopware\Elasticsearch\Admin\AdminElasticsearchEntitySearcher::search` is tagged with the state `loaded-by-opensearch`. When the Admin API returns JSON, this state is exposed inside the response `meta.states`, e.g.

  ```json
  {
      "data": [ /* entities */ ],
      "meta": {
          "states": [
            "loaded-by-opensearch"
          ],
          "total": 200
      }
  }
  ```

With this metadata we can immediately see if a slow request bypassed OpenSearch (flag state missing) and focus our diagnostics accordingly.

## Consequences

* When `ENABLE_OPENSEARCH_FOR_ADMIN_API` is on, DAL searches inside supported admin modules reuse the OpenSearch index, which reduces MySQL pressure and significantly boosts the performance of listings/filtering/searching for large catalogs.
* Developers must ensure that any new filters or admin modules declare their requirements in `AdminSearchRegistry` and index the needed fields, otherwise they will still fall back to SQL and lose the performance improvements.
* After enable the flag, shoppers have to reindex the admin ES indexes to make the changes applied by running: `bin/console es:admin:index`, the same applied when you modified a field's mapping or adding/removing more fields
* Index size of the admin indexes will be increased because more data is stored, so hostings need to monitor the admin ES index size.
* Indexing time of admin indexes will also increase due to the same reason, so we want to minimize the fields we want to index to keep the index lean and fast not for read performance but also for write performance in administration

---

---
url: /docs/concepts/extensions/apps-concept.md
---

# Apps

The app system allows you to extend and modify the functionality and appearance of Shopware. It leverages well-defined extension points you can hook into to implement your specific use case.

The app system is designed to be decoupled from Shopware itself. This has two great advantages:

1. **Freedom of choice:** You need to understand only the interface between Shopware and your app to get started with developing your own app. You don't need special knowledge of the inner workings and internal structure of Shopware itself. Additionally, you have the freedom to choose a programming language or framework of your choice to implement your app. This is achieved by decoupling the deployment of Shopware itself and your app and by using the Admin API and webhooks to communicate between Shopware and your app instead of using programming language constructs directly.
2. **Fully cloud compatible:** By decoupling Shopware and your app, your app is automatically compatible with multi-tenant cloud systems. Therefore, your app can be used within self-hosted shops and shops on [Shopware SaaS](../../products/saas.md).

The central interface between your app and Shopware is defined by a dedicated manifest file. The manifest is what glues Shopware and your app together. It defines your app's features and how Shopware can connect to it. You can find more information about how to use the manifest file in the [App base Guide](../../guides/plugins/apps/app-base-guide.md).

## Communication between Shopware and your app

Shopware communicates with your app exclusively via HTTP requests. Therefore, you are free to choose a tech stack for your app, as long as you can serve HTTP requests. Shopware will notify you of events happening in the shop that your app is interested in by posting to HTTP endpoints that you define in the manifest file. While processing these events, your app can use the Shopware API to get additional data that your app needs. A schematic overview of the communication may look like this:

![Communication between Shopware and your app](../../assets/extensions-apps-shopwareCommunication.svg)

To secure this communication, a registration handshake is performed during the installation of your app. During this registration, it is verified that Shopware talks to the right app backend server, and your app gets credentials used to authenticate against the API. See [App registration & backend setup](../../guides/plugins/apps/lifecycle/app-registration-setup.md).

::: info
Note that this is optional if Shopware and your app don't need to communicate, e.g., because your app provides a [Theme](../../guides/plugins/themes/index.md).
:::

## Modify the appearance of the Storefront

Your app can modify the Storefront's appearance by shipping your Storefront assets (template files, JavaScript sources, SCSS sources, snippet files) alongside your manifest file. You don't need to serve those assets from your external server, as Shopware will rebuild the Storefront upon the installation of your app and will consider your modifications in that process. Find out more about modifying the appearance of the Storefront in the [App Storefront guide](../../guides/plugins/apps/storefront/index.md).

## Integrate payment providers

::: info
This functionality is available starting with Shopware 6.4.1.0.
:::

Shopware provides functionality that allows your app to integrate payment providers. You can use synchronous payments with providers that do not require user interaction; in that case, approval can be requested with a simple background request. You can use asynchronous payments if you want to redirect the user to a payment provider. Your app then provides a URL for redirection. After the user returns to the shop, Shopware will verify the payment status with your app. Find out more about providing payment endpoints in the [App payment guide](../../guides/plugins/apps/checkout/payment.md).

## Execute business logic inside Shopware with App Scripts

::: info
This functionality is available starting with Shopware 6.4.8.0.
:::

[App scripts](../../guides/plugins/apps/app-scripts/index.md) allow your app to execute custom business logic inside the Shopware execution stack. This allows for new use cases, e.g., if you need to load additional data that should be rendered in the Storefront or need to manipulate the cart.

## Add conditions to the Rule Builder

::: info
This functionality is available starting with Shopware 6.4.12.0.
:::

Your app may introduce custom conditions for use in the [Rule builder](../framework/rule-system/index.md). For more information, refer to [Add custom rule conditions](../../guides/plugins/apps/rule-builder/add-custom-rule-conditions.md) in the guides.

---

---
url: /docs/guides/plugins/apps.md
---

# Apps

Apps are the extension mechanism designed for Shopware’s [Cloud environment](../../../products/saas.md). Unlike [plugins](../plugins/index.md), they don't run code directly inside the shop system. Instead, they follow an event-driven, remote-extension model and communicate with external services through APIs. This makes them less intrusive while still highly flexible.

Apps are well-suited for use cases such as:

* Integrating with third-party services (e.g., ERP, CRM, marketing tools)
* Providing payment methods and forwarding to external payment providers
* Adding storefront customizations, including themes
* Handling data or processes outside the shop system (e.g., product synchronization, advanced shipping logic, analytics workflows)
* Extending or modifying core functionality such as checkout behavior, pricing and discount logic, payment flows, product catalog management, or search behavior
* Customizing the Storefront or Administration; creating custom themes, adding custom blocks or Storefront elements, or modifying the appearance and layout of the Administration panel
* Facilitating integration with external systems to allow seamless data synchronization, order and product management, and cross-platform workflows

You can develop apps using the Shopware [App SDKs](../apps/app-sdks/index.md), [App Scripts](./app-scripts/index.md), and external services with the Shopware app system and its [reference documentation](../../../resources/references/app-reference/index.md). Apps offer a modular and scalable way to extend and customize the platform according to specific business requirements.

Some app extension points use a [gateway pattern](../apps/gateways/index.md), where Shopware delegates a specific task to an external app service and continues processing based on the returned result. A prominent example is the [checkout gateway](../apps/gateways/checkout/checkout-gateway.md).

For comparison, [App Scripts](../apps/app-scripts/index.md) cover synchronous, sandboxed logic inside the app system, but come with caveats.

::: info
Apps also provide theme support, so everything you can do with a theme plugin is also possible in an app. This makes them the preferred option for customizing design in Cloud shops.
:::

To understand how apps differ from other extension types, see the [Overview table](../../plugins/index.md#which-type-to-build).

## Start here

If you are new to Shopware apps, begin with the [App Base Guide](../apps/app-base-guide.md). It covers the common foundation for all apps, including:

* creating an app in `custom/apps`
* adding a valid `manifest.xml`
* refreshing the app registry
* installing and activating the app

## Build path by use case

After the base setup, continue with the path that fits your app:

* **Administration extensions:** Use [Build an Admin UI App Locally](create-admin-extension.md) if you want to add a custom Administration UI module and develop it locally with the [Meteor Admin SDK](../apps/administration/meteor-admin-sdk.md) and [Vite](https://vite.dev/), without setting up an app backend first.

* **Apps with a backend:** Use [App Registration & Backend Setup](../apps/lifecycle/app-registration-setup.md) if your app needs registration, authenticated server-to-server communication, webhooks, signing, Admin API credentials, payment methods, tax providers, or other backend-driven features.

* **Request signing and verification:** See [Signing & Verification in the App System](../apps/lifecycle/app-signature-verification.md) for secure request validation and response signing.

* **Event-based integrations:** See [Webhook](../apps/lifecycle/webhook.md) to react to Shopware events asynchronously.

* **Feature-specific integrations:** Continue with the dedicated guides for [Payment](../apps/checkout/payment.md), [Shipping methods](../apps/checkout/shipping-methods.md), [Tax provider](../apps/checkout/tax-provider.md), or [Configuration](../apps/lifecycle/configuration.md), depending on your app’s capabilities.

* **MCP tools, prompts, and resources:** See [MCP Server extension](mcp-server.md) to expose custom AI-callable capabilities via `Resources/mcp.xml` and HMAC-signed webhooks.

---

---
url: /docs/v6.5/concepts/extensions/apps-concept.md
---

# Apps

The app system allows you to extend and modify the functionality and appearance of Shopware. It leverages well defined extension points you can hook into to implement your specific use case.

The app system is designed to be decoupled from Shopware itself. This has two great advantages:

1. **Freedom of choice:** You need to understand only the interface between Shopware and your app to get started with developing your own app. You don't need special knowledge of the inner workings and internal structure of Shopware itself. Additionally, you have the freedom to choose a programming language or framework of your choice to implement your app. This is achieved by decoupling the deployment of Shopware itself and your app and by using the Admin API and webhooks to communicate between Shopware and your app instead of using programming language constructs directly.
2. **Fully cloud compatible:** By decoupling Shopware and your app, your app is automatically compatible for use in a multi-tenant cloud system. Therefore your app can be used within self-hosted shops and shops on [Shopware SaaS](../../products/saas).

The central interface between your app and Shopware is defined by a dedicated manifest file. The manifest is what glues Shopware and your app together. It defines your app's features and how Shopware can connect to it. You can find more information about how to use the manifest file in the [App base Guide](../../guides/plugins/apps/app-base-guide).

## Communication between Shopware and your app

Shopware communicates with your app only exclusively via HTTP-Requests. Therefore you are free to choose a tech stack for your app, as long as you can serve HTTP-Requests. Shopware will notify you of events happening in the shop that your app is interested in by posting to HTTP-Endpoints that you define in the manifest file. While processing these events, your app can use the Shopware API to get additional data that your app needs. A schematic overview of the communication may look like this:

![Communication between Shopware and your app](../../assets/extensions-apps-shopwareCommunication.svg)

To secure this communication, a registration handshake is performed during the installation of your app. During this registration, it is verified that Shopware talks to the right app backend server, and your app gets credentials used to authenticate against the API. You can read more on the registration workflow in the [App base guide](../../guides/plugins/apps/app-base-guide).

::: info
Notice that this is optional if Shopware and your app don't need to communicate, e.g., because your app provides a [Theme](apps-concept).
:::

## Modify the appearance of the Storefront

Your app can modify the Storefront's appearance by shipping your Storefront assets (template files, javascript sources, SCSS sources, snippet files) alongside your manifest file. You don't need to serve those assets from your external server, as Shopware will rebuild the Storefront upon the installation of your app and will consider your modifications in that process. Find out more about modifying the appearance of the Storefront in the [App Storefront guide](../../guides/plugins/apps/storefront/)

## Integrate payment providers

::: info
This functionality is available starting with Shopware 6.4.1.0.
:::

Shopware provides functionality for your app to be able to integrate payment providers. You can use the synchronous payment to provide payment with a provider that does not require any user interaction, for which you can choose a simple request for approval in the background. You can use an asynchronous payment if you would like to redirect a user to a payment provider. Your app, therefore, provides a URL for redirection. After the user returns to the shop, Shopware will verify the payment status with your app. Find out more about providing payment endpoints in the [App payment guide](../../guides/plugins/apps/payment).

## Execute business logic inside Shopware with App Scripts

::: info
This functionality is available starting with Shopware 6.4.8.0.
:::

[App scripts](../../guides/plugins/apps/app-scripts/) allow your app to execute custom business logic inside the Shopware execution stack. This allows for new use cases, e.g., if you need to load additional data that should be rendered in the Storefront or need to manipulate the cart.

## Add conditions to the Rule Builder

::: info
This functionality is available starting with Shopware 6.4.12.0.
:::

Your app may introduce custom conditions for use in the [Rule builder](../framework/rules). For additional information refer to [Add custom rule conditions](../../guides/plugins/apps/rule-builder/add-custom-rule-conditions) from the guides.

---

---
url: /docs/v6.5/guides/plugins/apps.md
---

# Apps

In Shopware, apps are custom-developed extensions that provide additional functionality and customization options to the e-commerce platform. These apps can be created using the Shopware app SDK, plugin system, or App scripts.
Apps are built to serve various purposes.

* **Extending functionality:** Apps can add new features and capabilities to the Shopware platform. This includes creating custom payment gateways, implementing advanced shipping methods, or enhancing product catalog management.

* **Modifying existing functionality:** Apps can modify or enhance existing functionalities within Shopware. This can involve altering the checkout process, implementing custom pricing rules, customizing the customer management system, or the search functionality.

* **Customizing the user interface:** Apps can customize the Storefront and Administration panel of Shopware to provide a unique and tailored experience. This includes creating custom themes, adding custom blocks or elements to the Storefront, or modifying the appearance and layout of the Administration panel.

* **Integrating with external systems:** Apps can facilitate integration with external systems to allow seamless data synchronization, order management, and cross-platform interactions.

Shopware apps provide a flexible and modular approach to extend and customize the platform according to specific business requirements.

While plugins and themes are also extensions but they differ from apps. To better understand the differences, take a look at the [Overview](../../../../docs/guides/plugins/overview) article.

---

---
url: /docs/v6.6/concepts/extensions/apps-concept.md
---

# Apps

The app system allows you to extend and modify the functionality and appearance of Shopware. It leverages well defined extension points you can hook into to implement your specific use case.

The app system is designed to be decoupled from Shopware itself. This has two great advantages:

1. **Freedom of choice:** You need to understand only the interface between Shopware and your app to get started with developing your own app. You don't need special knowledge of the inner workings and internal structure of Shopware itself. Additionally, you have the freedom to choose a programming language or framework of your choice to implement your app. This is achieved by decoupling the deployment of Shopware itself and your app and by using the Admin API and webhooks to communicate between Shopware and your app instead of using programming language constructs directly.
2. **Fully cloud compatible:** By decoupling Shopware and your app, your app is automatically compatible for use in a multi-tenant cloud system. Therefore your app can be used within self-hosted shops and shops on [Shopware SaaS](../../products/saas).

The central interface between your app and Shopware is defined by a dedicated manifest file. The manifest is what glues Shopware and your app together. It defines your app's features and how Shopware can connect to it. You can find more information about how to use the manifest file in the [App base Guide](../../guides/plugins/apps/app-base-guide).

## Communication between Shopware and your app

Shopware communicates with your app only exclusively via HTTP-Requests. Therefore you are free to choose a tech stack for your app, as long as you can serve HTTP-Requests. Shopware will notify you of events happening in the shop that your app is interested in by posting to HTTP-Endpoints that you define in the manifest file. While processing these events, your app can use the Shopware API to get additional data that your app needs. A schematic overview of the communication may look like this:

![Communication between Shopware and your app](../../assets/extensions-apps-shopwareCommunication.svg)

To secure this communication, a registration handshake is performed during the installation of your app. During this registration, it is verified that Shopware talks to the right app backend server, and your app gets credentials used to authenticate against the API. You can read more on the registration workflow in the [App base guide](../../guides/plugins/apps/app-base-guide).

::: info
Notice that this is optional if Shopware and your app don't need to communicate, e.g., because your app provides a [Theme](apps-concept).
:::

## Modify the appearance of the Storefront

Your app can modify the Storefront's appearance by shipping your Storefront assets (template files, javascript sources, SCSS sources, snippet files) alongside your manifest file. You don't need to serve those assets from your external server, as Shopware will rebuild the Storefront upon the installation of your app and will consider your modifications in that process. Find out more about modifying the appearance of the Storefront in the [App Storefront guide](../../guides/plugins/apps/storefront/)

## Integrate payment providers

::: info
This functionality is available starting with Shopware 6.4.1.0.
:::

Shopware provides functionality for your app to be able to integrate payment providers. You can use the synchronous payment to provide payment with a provider that does not require any user interaction, for which you can choose a simple request for approval in the background. You can use an asynchronous payment if you would like to redirect a user to a payment provider. Your app, therefore, provides a URL for redirection. After the user returns to the shop, Shopware will verify the payment status with your app. Find out more about providing payment endpoints in the [App payment guide](../../guides/plugins/apps/payment).

## Execute business logic inside Shopware with App Scripts

::: info
This functionality is available starting with Shopware 6.4.8.0.
:::

[App scripts](../../guides/plugins/apps/app-scripts/) allow your app to execute custom business logic inside the Shopware execution stack. This allows for new use cases, e.g., if you need to load additional data that should be rendered in the Storefront or need to manipulate the cart.

## Add conditions to the Rule Builder

::: info
This functionality is available starting with Shopware 6.4.12.0.
:::

Your app may introduce custom conditions for use in the [Rule builder](../framework/rules). For additional information refer to [Add custom rule conditions](../../guides/plugins/apps/rule-builder/add-custom-rule-conditions) from the guides.

---

---
url: /docs/v6.6/guides/plugins/apps.md
---

# Apps

In Shopware, apps are custom-developed extensions that provide additional functionality and customization options to the e-commerce platform. These apps can be created using the Shopware app SDK, plugin system, or App scripts.
Apps are built to serve various purposes.

* **Extending functionality:** Apps can add new features and capabilities to the Shopware platform. This includes creating custom payment gateways, implementing advanced shipping methods, or enhancing product catalog management.

* **Modifying existing functionality:** Apps can modify or enhance existing functionalities within Shopware. This can involve altering the checkout process, implementing custom pricing rules, customizing the customer management system, or the search functionality.

* **Customizing the user interface:** Apps can customize the Storefront and Administration panel of Shopware to provide a unique and tailored experience. This includes creating custom themes, adding custom blocks or elements to the Storefront, or modifying the appearance and layout of the Administration panel.

* **Integrating with external systems:** Apps can facilitate integration with external systems to allow seamless data synchronization, order management, and cross-platform interactions.

Shopware apps provide a flexible and modular approach to extend and customize the platform according to specific business requirements.

While plugins and themes are also extensions but they differ from apps. To better understand the differences, take a look at the [Overview](../../../guides/plugins/overview) article.

---

---
url: /docs/v6.5/guides/plugins/apps/storefront/apps-as-themes.md
---

# Apps as themes

It is absolutely possible to ship whole [themes](../../themes/) inside an app. All you have to do is include your theme configuration (in the form of a [theme.json](../../../plugins/themes/theme-configuration) file) inside your app's Resources folder.\
So the folder structure of a theme may look like this:

```text
└── DemoTheme
      └── Resources
            └── ...
            └── theme.json
      └── manifest.xml
```

## Themes vs. "ordinary" apps

If your app provides a `theme.json` file, it is considered to be a theme. All the changes you make to the Storefront's appearance inside your theme will be visible only if your theme is assigned to the Storefront. In contrast, if you don't provide a `theme.json` file, your app is an "ordinary" app. The changes will be applied to all sales channels automatically, as long as your app is active.

## Migrating existing themes

If you have already created Shopware 6 themes via plugins, it is effortless to migrate them to the app system. Don't worry, you don't have to do all the work twice. Instead of providing a `composer.json` and plugin base class, provide a `manifest.xml` file with the metadata for your app. After you have created a new folder for your app and added the `manifest.xml`, you can copy the `YourThemePlugin/src/Resources` folder from your plugin to the `YourThemeApp/Resources` folder inside your app. It should not be necessary to change anything inside your template or Javascript code.

---

---
url: /docs/v6.6/guides/plugins/apps/storefront/apps-as-themes.md
---

# Apps as themes

It is absolutely possible to ship whole [themes](../../themes/) inside an app. All you have to do is include your theme configuration (in the form of a [theme.json](../../../plugins/themes/theme-configuration) file) inside your app's Resources folder.\
So the folder structure of a theme may look like this:

```text
└── DemoTheme
      └── Resources
            └── ...
            └── theme.json
      └── manifest.xml
```

## Themes vs. "ordinary" apps

If your app provides a `theme.json` file, it is considered to be a theme. All the changes you make to the Storefront's appearance inside your theme will be visible only if your theme is assigned to the Storefront. In contrast, if you don't provide a `theme.json` file, your app is an "ordinary" app. The changes will be applied to all sales channels automatically, as long as your app is active.

## Migrating existing themes

If you have already created Shopware 6 themes via plugins, it is effortless to migrate them to the app system. Don't worry, you don't have to do all the work twice. Instead of providing a `composer.json` and plugin base class, provide a `manifest.xml` file with the metadata for your app. After you have created a new folder for your app and added the `manifest.xml`, you can copy the `YourThemePlugin/src/Resources` folder from your plugin to the `YourThemeApp/Resources` folder inside your app. It should not be necessary to change anything inside your template or Javascript code.

---

---
url: /docs/guides/plugins/apps/storefront/apps-as-themes.md
---

# Apps as Themes

To ship whole [themes](../../themes/index.md) inside an app, just include the theme configuration as a [theme.json](../../../plugins/themes/configuration/theme-configuration.md) file inside your app's `Resources` folder. The folder structure of a theme may look like this:

```text
└── DemoTheme
      └── Resources
            └── ...
            └── theme.json
      └── manifest.xml
```

## Themes vs. "ordinary" apps

If your app provides a `theme.json` file, it is considered to be a theme. All the changes you make to the Storefront's appearance inside your theme will be visible only if your theme is assigned to the Storefront. In contrast, if you don't provide a `theme.json` file, your app is an "ordinary" app. The changes will be applied to all sales channels automatically, as long as your app is active.

## Migrating existing themes

If you have already created Shopware 6 themes via plugins, it is effortless to migrate them to the app system. Don't worry, you don't have to do all the work twice. Instead of providing a `composer.json` and plugin base class, provide a `manifest.xml` file with the metadata for your app. After you have created a new folder for your app and added the `manifest.xml`, you can copy the `YourThemePlugin/src/Resources` folder from your plugin to the `YourThemeApp/Resources` folder inside your app. It should not be necessary to change anything inside your template or Javascript code.

---

---
url: /docs/v6.5/concepts/framework/architecture.md
---

# Architecture

On a high level, Shopware consists of multiple modules that separate the entire code base into logical units. Some modules are independent, and some depend on others.

---

---
url: /docs/v6.6/concepts/framework/architecture.md
---

# Architecture

On a high level, Shopware consists of multiple modules that separate the entire code base into logical units. Some modules are independent, and some depend on others.

---

---
url: /resources/admin-extension-sdk/concepts/architecture.md
---

# Architecture

The Meteor Admin SDK provides wrapper methods for a better development experience. It abstracts and hides the more
complex logic behind a simple API. This makes it easier for app and plugin developers to create their solutions and focus
on their business instead of caring about the technical details.

## Admin communication

Technically speaking, apps and plugins are communicating with the Administration via the [postMessage API](https://developer.mozilla.org/en-US/docs/Web/API/Window/postMessage). It is a secure communication channel between different windows. In most cases it will be used to communicate
from an iFrame to the main window or the other way around.

The Extension SDK works in the same way, but it uses a hybrid approach. Every method is callable within an iFrame and also
from the same window. This allows apps (within iFrames) and plugins (in the same window) to use the same API.

![postMessage communication](./assets/post-message-communication.png)

Normally the postMessage API is very limited and not easy to use. You merely can send string values from one window to
another. This isn't very handy during the development process. To provide a smoother experience, we wrote some helper methods that
make working with the postMessage API a breeze.

The helper methods can be found in the `channel` file. It holds different methods for easier communication. The most important ones are `send` and `handle`. They are responsible for sending and handling data.

Here is an example to give you a better understanding of how that works.

## Example workflow

Let's imagine that an app or plugin calls the `context.getLanguage` method from the Extension SDK:

```js
// from app/plugin
const language = await sw.context.getLanguage();
```

But what is happening in the background? The method is a wrapper for the `send` method in the `channel`. When you use it, it will call `send` with a predefined type:

```js
// from app/plugin
send('contextLanguage', {});
```

Each message has a unique type. The types are hidden from plugin and app developers and are only responsible for the underlying handling. Knowing the unique type we can tell what type of request there is in the Administration and what response it expects.

The `send` method is producing magic in the background now. It creates a data object with following properties:

```js
{
  _type: 'contextLanguage',
  _data: {},
  _callbackId: 'aRand0mGeneratedUniqueId'
}
```

The `_type` property is there to recognize the request type. The `_data` property is custom data that will be added by the app or plugin. E.g. the title, message or any more information available for a notification. The `_callbackId` is needed for the Administration to send back the data including an ID, so that the sender is able to recognize it and use the included data.

This object will be sent as a stringified JSON object to the Administration window via the postMessage API.

Now let's have a look at what needs to happen on the side of the Administration.

```js
// at Administration
handle('contextLanguage', () => {
    return {
        languageId: Shopware.Context.api.languageId,
        systemLanguageId: Shopware.Context.api.systemLanguageId,
    };
});
```

It uses the `handle` method, which is also a helper method of the `channel`. You see now, that the type matches the sender type. And in the second argument it provides a method that returns the data.

This method reacts to every `contextLanguage` request and sends the data values back to the source of the request. It also creates an object that includes meta information which in turn are needed for the original `send` window:

```js
{
  _type: 'contextLanguage',
  _response: { languageId: '1a2b3c...', systemLanguageId: '9f8g7h...', },
  _callbackId: 'aRand0mGeneratedUniqueId'
}
```

The source that will send the request is adding a new event listener before sending the message. This event listener listens to all incoming messages and if any of these messages matches the type and the callback ID of the message sent, it will handle the data.

In our case it will in return get a stringified object that includes the language information. These will be parsed and returned to the first method call:

```js
// from app/plugin
const language = await sw.context.getLanguage();

// language = { languageId: '1a2b3c...', systemLanguageId: '9f8g7h...', }
```

And this is basically it! The app or plugin has now got the data from the Administration. It all just looks like a simple call, but there is a lot going on in the background.

## Sending methods

In normal cases you can't add methods to JSON objects which will get stringified. But in our case we are convinced it would make the many developers' lives much easier if they can also use their own methods in the calls.

To handle these edge cases we are converting the methods to information objects like this:

```js
{
  __type__: '__function__',
  id: 'theUniqueFunctionId' // will be generated uniquely
}
```

The method will be saved in a `methodRegistry` where the unique ID can be used as an identifier.

The receiver of the object converts this object back to a method that triggers the original method. This can't be done directly, because we do not have direct access to the method. To solve this problem, we send a special postMessage call to the original source. This call contains all arguments of the method called and its unique ID:

```js
send('__function__', {
  args: args,
  id: id,
})
```

The sender gets the message back and executes the method with the matching ID and the given arguments. The return value will then be sent back to the converted method in the receiver.

This complex logic is also abstracted. To use it, just add methods to the data. They will then be converted and handled automatically.

---

---
url: /docs/products/extensions/b2b-suite/guides/core/assignment-service.md
---

# Assignment Service

## Pattern

A repeating pattern used throughout the B2B Suite is the Assignment service.
The B2B Suite ships with many new entities and therefore provides the means to connect them to each other. This is done through M:N assignments.

The diagram below shows the usually implemented objects with their outside dependencies.

![image](../../../../../assets/b2bSuite-core-assignmentService.svg)

## Repository

Again the repository is the exclusive access layer to the storage engine.
Contrary to CRUD operations, there is no object but just plain integers (the primary keys).
The default repository will have these three methods relevant for the assignment:

```php
<?php declare(strict_types=1);

namespace Shopware\B2B\RoleContact\Framework;

use Doctrine\DBAL\Connection;
use Shopware\B2B\Common\Repository\DbalHelper;

class RoleContactRepository
{
    public function removeRoleContactAssignment(int $roleId, int $contactId)
    {
        [...]
    }

    public function assignRoleContact(int $roleId, int $contactId)
    {
        [...]
    }

    public function isMatchingDebtorForBothEntities(int $roleId, int $contactId): bool
    {
        [...]
    }
```

## Service

Services are even smaller. They contain the two relevant methods for assignment.
Internally they will check if the assignment is even allowed and throw exceptions if not.

```php
<?php declare(strict_types=1);

namespace Shopware\B2B\RoleContact\Framework;

/**
 * Assigns roles to contacts M:N
 */
class RoleContactAssignmentService
{
    public function assign(int $roleId, int $contactId)
    {
        [...]
    }

    public function removeAssignment(int $roleId, int $contactId)
    {
        [...]
    }
}
```

---

---
url: /docs/v6.5/products/extensions/b2b-suite/guides/core/assignment-service.md
---

# Assignment Service

## Pattern

A repeating pattern used throughout the B2B Suite is the Assignment service.
The B2B Suite ships with many new entities and therefore provides the means to connect them to each other. This is done through M:N assignments.

The diagram below shows the usually implemented objects with their outside dependencies.

![image](../../../../../assets/b2bSuite-core-assignmentService.svg)

## Repository

Again the repository is the exclusive access layer to the storage engine.
Contrary to CRUD operations, there is no object but just plain integers (the primary keys).
The default repository will have these three methods relevant for the assignment:

```php
<?php declare(strict_types=1);

namespace Shopware\B2B\RoleContact\Framework;

use Doctrine\DBAL\Connection;
use Shopware\B2B\Common\Repository\DbalHelper;

class RoleContactRepository
{
    public function removeRoleContactAssignment(int $roleId, int $contactId)
    {
        [...]
    }

    public function assignRoleContact(int $roleId, int $contactId)
    {
        [...]
    }

    public function isMatchingDebtorForBothEntities(int $roleId, int $contactId): bool
    {
        [...]
    }
```

## Service

Services are even smaller. They contain the two relevant methods for assignment.
Internally they will check if the assignment is even allowed and throw exceptions if not.

```php
<?php declare(strict_types=1);

namespace Shopware\B2B\RoleContact\Framework;

/**
 * Assigns roles to contacts M:N
 */
class RoleContactAssignmentService
{
    public function assign(int $roleId, int $contactId)
    {
        [...]
    }

    public function removeAssignment(int $roleId, int $contactId)
    {
        [...]
    }
}
```

---

---
url: /docs/v6.6/products/extensions/b2b-suite/guides/core/assignment-service.md
---

# Assignment Service

## Pattern

A repeating pattern used throughout the B2B Suite is the Assignment service.
The B2B Suite ships with many new entities and therefore provides the means to connect them to each other. This is done through M:N assignments.

The diagram below shows the usually implemented objects with their outside dependencies.

![image](../../../../../assets/b2bSuite-core-assignmentService.svg)

## Repository

Again the repository is the exclusive access layer to the storage engine.
Contrary to CRUD operations, there is no object but just plain integers (the primary keys).
The default repository will have these three methods relevant for the assignment:

```php
<?php declare(strict_types=1);

namespace Shopware\B2B\RoleContact\Framework;

use Doctrine\DBAL\Connection;
use Shopware\B2B\Common\Repository\DbalHelper;

class RoleContactRepository
{
    public function removeRoleContactAssignment(int $roleId, int $contactId)
    {
        [...]
    }

    public function assignRoleContact(int $roleId, int $contactId)
    {
        [...]
    }

    public function isMatchingDebtorForBothEntities(int $roleId, int $contactId): bool
    {
        [...]
    }
```

## Service

Services are even smaller. They contain the two relevant methods for assignment.
Internally they will check if the assignment is even allowed and throw exceptions if not.

```php
<?php declare(strict_types=1);

namespace Shopware\B2B\RoleContact\Framework;

/**
 * Assigns roles to contacts M:N
 */
class RoleContactAssignmentService
{
    public function assign(int $roleId, int $contactId)
    {
        [...]
    }

    public function removeAssignment(int $roleId, int $contactId)
    {
        [...]
    }
}
```

---

---
url: /frontends/introduction/templates/astro-template.md
---
# Astro Blank Template

The blank Astro bootstrap application with pre-installed dependencies, so you can start working on your project right away.

**Now you can use `composables` and `api-client` libraries in every Vue component created in an Astro project.**

## Setup & run

Alternatively, set up the astro-blank template manually by running the following commands in a new directory:

```bash
npx tiged shopware/frontends/templates/astro astro-blank && cd astro-blank
npm i && npm run dev
```

## Configure

The blank template is pre-configured to connect to a public Shopware backend, so you can follow our [building guides](../) right away.

In order to connect it to your own store backend, you need to edit the `env.development`:

```bash
# .env.development
API_URL="https://demo-frontends.shopware.store"
API_ACCESS_TOKEN="SWSCBHFSNTVMAWNZDNFKSHLAYW"
```

:::info Production
For production build it's good to prepare a separate `.env.production` file containing other credentials if needed.
:::

If the customization isn't enough, visit `src/entrypoints/_shopware.ts` file and customize it on your own. Like, change cookie manager, or add some other configuration for API client instance.

## What next?

---

---
url: /docs/resources/references/adr/2023-01-10-atomic-theme-compilation.md
---

# Atomic theme compilation

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2023-01-10-atomic-theme-compilation.md)
:::

## Context

The theme compilation could result in a broken storefront, when there is some error during theme compilation (e.g. because of wrongly configured values in the theme configuration by the customer).
The reason is that the theme is always compiled into the same physical folder/location and at the start of the compilation this folder will be deleted and recreated, but when the compilation crashes due to errors, not all needed files are present in the theme folder and the storefront UI is broken.

Another issue was that there were edge cases when you hit a shop where the theme compilation was in progress, the storefront also may look broken as not all required compiled files are present in the theme folder (yet).

## Decision

Instead of compiling the theme always in the same folder we will compile the theme always in a new folder with a generated seed.
Until the theme compilation is completed and successful the old theme will be used in the storefront UI, only when the theme compilation is finished we will use the new theme folder in the storefront.

This will also open up the possibility for further new features where the customer may manually rollback to previous theme compiled version.
But for now we will delete the old theme folder one hour (see [caching](#caching)) after the theme was compiled successfully to the new location and we use the theme from the new location in the storefront.

### Discarded Alternatives

An alternative solution would be to always use the same folder location for the live version of the theme, but the theme compile process will not directly write into this folder, but in a temporary folder.
When the theme compilation finished we then copy the whole temp folder over to the live folder.

This approach works well under the assumptions that moving a whole folder is a fast and a atomic operation, which it is on most local filesystems.
But the theme assets can also be stored on external storage (e.g. S3, Google Cloud storage), especially for more dedicated setups it is common to store the asset files on a external filesystem/CDN.
And we can't assume that copying a whole folder is an atomic operation there, and in fact for S3 and Google Cloud Storage moving a folder means that we need to manually empty the target folder and move each file individually as both storages don't really support the concept of `folders`.
Even though this alternative fixed the issue when theme compilation errored, it does not fix the edge case when you hit a store where the current theme asset folder does not contain all needed folders yet. And as the files have to be copied one by one it would probably exaggerate that problem further.

Additionally, from a cost perspective the solution has some downsides, as on some (especially S3) external storages you not only pay for the storage itself, but also for file operations.
And using a temporary folder and then moving the folders will result in a lot more file operations, compared to directly compiling into the new folder.

Because of the aforementioned issues we decided to discard this approach.

## Consequences

We will expand the abstract class `AbstractThemePathBuilder` to allow for a `seeding` mechanism that allows to change the active theme folder path based on a randomly generated seed.

We add the two following methods that should be implemented in custom implementations of the `AbstractThemePathBuilder`.

```php
    public function generateNewPath(string $salesChannelId, string $themeId, string $seed): string
    {
    }

    public function saveSeed(string $salesChannelId, string $themeId, string $seed): void
    {
    }
```

During a theme compilation the theme compiler will generate a new random seed and call the `generateNewPath()` method with that seed, to get the location of the theme folder where the compiled files of that compilation will be stored.
After the theme compilation is finished successfully the compiler will call the `saveSeed()` method with the seed that was used for the compilation, after that subsequent calls to the existing `assemblePath()` method should take into account the new seed and thus the new theme folder should be used in the storefront.

### Backwards Compatibility

Those methods will be added as concrete methods in the abstract class with a default implementation, to not break backwards compatibility.
But both new methods are marked as `@deprecated`, because they will be abstract in the 6.6 major version, so custom implementations have to implement those methods for 6.6.
The default implementation to keep backwards compatibility will ignore the seed, so the `saveSeed()` method will be a no-op, and the `generateNewPath()` will just call the existing `assemblePath()` method, thus the behaviour for existing implementations will be the same as before this change.
This means that the old implementations also don't use the seeding mechanism, so the problems with the theme compilation will still be present in those implementations, unless the custom implementations also implement the seeding mechanism, by implementing the two new methods.

### Performance

The current `seed` has to be saved somewhere where it is fast to retrieve, as the `seed` value will be needed on every storefront request.
Therefore, we will store the `seed` in `system_config` table as the system config is already heavily cached and should not be a performance issue. Additionally it already allows saving values per sales channel which we need in this case.

We also considered storing the seed in an additional column in the `theme_sales_channel` mapping table and reading it in the `RequestTransformer` and then adding it as a `request attribute` for further usage.
This idea was discarded, because the DAL does not allow additional columns in mapping definitions, and in fact it will reset values in additional columns on every write as it uses `REPLACE INTO` queries to update the mappings.

### Caching

As the url to the assets now change this means that the cache for all storefront requests needs to be invalidated.
This was already the case previously as a new theme compilation would add a cache-buster query param to the url, to prevent the serving of stale theme files cached on the browser side.

But with the theme compilation, we can't delete the old theme folder immediately after the new theme compilation finished successfully, as the cache invalidation can take some time especially if you use external CDNs like fastly.
This means that we expect for a short time that clients still will request the old theme folder, because they are served stale content from the CDN.
To ensure that the site renders normally for those clients we won't delete the old theme folder immediately, but instead dispatch a queue message with a configurable delay (default 15 min / max SQS delay) that the old theme folder should be deleted.
So the old theme files will still be accessible for one hour after a new theme was compiled.

We can expand on this deletion strategy, once we implement further features like manual rollback to previous theme versions.

### Theme Assets

Previously the theme assets were stored in the same folder as the compiled theme files, that meant, that for every saleschannel where a theme was used the theme assets were duplicated, even though the assets are always the same, regardless of the theme configuration.
This does not scale, when we create new folders for the compiled theme files on the fly on every theme compile.
So the asset files are now stored in a separate folder, that is not dependent on the sales channel or the theme configuration.
We use the `themeId` as the folder name, so the assets are still unique per theme, but they are not duplicated for every sales channel.

### PaaS / Upsun

Upsun currently does not offer to store the theme assets on an internal storage, therefore the assets need to be stored locally.
Additionally, Upsun uses `immutable deploys`, meaning that once a version is deployed the file system is read-only and no changes can be made to the local files.

The theme compile is executed on PaaS during the `build` step, where there is no DB connection, so we can't use the new default implementation of the `AbstractThemePathBuilder`, which stores the new `seed` in the DB during the theme compile.
But because of the `immutable deploys` it is not possible to recompile the theme at runtime, a new deployment is needed to recompile the theme.
So PaaS was not affected by the issues during the theme compilation, and instead of rollbacking to a backup theme folder you would rollback to the last deployment instead.

That means that PaaS does not need the seeding mechanism, so we add a implementation for the `AbstractThemePathBuilder` that ignores the seed and will always return the same path for a given theme and sales channel combination (like the old default implementation).

Once Upsun allows to store the theme assets externally we can move the theme compile from the `build` to the `deploy` step and can then use the default `seeding` implementation, as we have access to the DB in the deploy step.
Then you can also recompile the theme at runtime and PaaS will also benefit from the new theme compile mechanism.

---

---
url: /docs/v6.5/resources/references/adr/2023-01-10-atomic-theme-compilation.md
---

# Atomic theme compilation

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2023-01-10-atomic-theme-compilation.md)
:::

## Context

The theme compilation could result in a broken storefront, when there is some error during theme compilation (e.g. because of wrongly configured values in the theme configuration by the customer).
The reason is that the theme is always compiled into the same physical folder/location and at the start of the compilation this folder will be deleted and recreated, but when the compilation crashes due to errors, not all needed files are present in the theme folder and the storefront UI is broken.

Another issue was that there were edge cases when you hit a shop where the theme compilation was in progress, the storefront also may look broken as not all required compiled files are present in the theme folder (yet).

## Decision

Instead of compiling the theme always in the same folder we will compile the theme always in a new folder with a generated seed.
Until the theme compilation is completed and successful the old theme will be used in the storefront UI, only when the theme compilation is finished we will use the new theme folder in the storefront.

This will also open up the possibility for further new features where the customer may manually rollback to previous theme compiled version.
But for now we will delete the old theme folder one hour (see [caching](#caching)) after the theme was compiled successfully to the new location and we use the theme from the new location in the storefront.

### Discarded Alternatives

An alternative solution would be to always use the same folder location for the live version of the theme, but the theme compile process will not directly write into this folder, but in a temporary folder.
When the theme compilation finished we then copy the whole temp folder over to the live folder.

This approach works well under the assumptions that moving a whole folder is a fast and a atomic operation, which it is on most local filesystems.
But the theme assets can also be stored on external storage (e.g. S3, Google Cloud storage), especially for more dedicated setups it is common to store the asset files on a external filesystem/CDN.
And we can't assume that copying a whole folder is an atomic operation there, and in fact for S3 and Google Cloud Storage moving a folder means that we need to manually empty the target folder and move each file individually as both storages don't really support the concept of `folders`.
Even though this alternative fixed the issue when theme compilation errored, it does not fix the edge case when you hit a store where the current theme asset folder does not contain all needed folders yet. And as the files have to be copied one by one it would probably exaggerate that problem further.

Additionally, from a cost perspective the solution has some downsides, as on some (especially S3) external storages you not only pay for the storage itself, but also for file operations.
And using a temporary folder and then moving the folders will result in a lot more file operations, compared to directly compiling into the new folder.

Because of the aforementioned issues we decided to discard this approach.

## Consequences

We will expand the abstract class `AbstractThemePathBuilder` to allow for a `seeding` mechanism that allows to change the active theme folder path based on a randomly generated seed.

We add the two following methods that should be implemented in custom implementations of the `AbstractThemePathBuilder`.

```php
    public function generateNewPath(string $salesChannelId, string $themeId, string $seed): string
    {
    }

    public function saveSeed(string $salesChannelId, string $themeId, string $seed): void
    {
    }
```

During a theme compilation the theme compiler will generate a new random seed and call the `generateNewPath()` method with that seed, to get the location of the theme folder where the compiled files of that compilation will be stored.
After the theme compilation is finished successfully the compiler will call the `saveSeed()` method with the seed that was used for the compilation, after that subsequent calls to the existing `assemblePath()` method should take into account the new seed and thus the new theme folder should be used in the storefront.

### Backwards Compatibility

Those methods will be added as concrete methods in the abstract class with a default implementation, to not break backwards compatibility.
But both new methods are marked as `@deprecated`, because they will be abstract in the 6.6 major version, so custom implementations have to implement those methods for 6.6.
The default implementation to keep backwards compatibility will ignore the seed, so the `saveSeed()` method will be a no-op, and the `generateNewPath()` will just call the existing `assemblePath()` method, thus the behaviour for existing implementations will be the same as before this change.
This means that the old implementations also don't use the seeding mechanism, so the problems with the theme compilation will still be present in those implementations, unless the custom implementations also implement the seeding mechanism, by implementing the two new methods.

### Performance

The current `seed` has to be saved somewhere where it is fast to retrieve, as the `seed` value will be needed on every storefront request.
Therefore, we will store the `seed` in `system_config` table as the system config is already heavily cached and should not be a performance issue. Additionally it already allows saving values per sales channel which we need in this case.

We also considered storing the seed in an additional column in the `theme_sales_channel` mapping table and reading it in the `RequestTransformer` and then adding it as a `request attribute` for further usage.
This idea was discarded, because the DAL does not allow additional columns in mapping definitions, and in fact it will reset values in additional columns on every write as it uses `REPLACE INTO` queries to update the mappings.

### Caching

As the url to the assets now change this means that the cache for all storefront requests needs to be invalidated.
This was already the case previously as a new theme compilation would add a cache-buster query param to the url, to prevent the serving of stale theme files cached on the browser side.

But with the theme compilation, we can't delete the old theme folder immediately after the new theme compilation finished successfully, as the cache invalidation can take some time especially if you use external CDNs like fastly.
This means that we expect for a short time that clients still will request the old theme folder, because they are served stale content from the CDN.
To ensure that the site renders normally for those clients we won't delete the old theme folder immediately, but instead dispatch a queue message with a configurable delay (default 15 min / max SQS delay) that the old theme folder should be deleted.
So the old theme files will still be accessible for one hour after a new theme was compiled.

We can expand on this deletion strategy, once we implement further features like manual rollback to previous theme versions.

### Theme Assets

Previously the theme assets were stored in the same folder as the compiled theme files, that meant, that for every saleschannel where a theme was used the theme assets were duplicated, even though the assets are always the same, regardless of the theme configuration.
This does not scale, when we create new folders for the compiled theme files on the fly on every theme compile.
So the asset files are now stored in a separate folder, that is not dependent on the sales channel or the theme configuration.
We use the `themeId` as the folder name, so the assets are still unique per theme, but they are not duplicated for every sales channel.

### PaaS / Platform.sh

Platform.sh currently does not offer to store the theme assets on an internal storage, therefore the assets need to be stored locally.
Additionally, Platform.sh uses `immutable deploys`, meaning that once a version is deployed the file system is read-only and no changes can be made to the local files.

The theme compile is executed on PaaS during the `build` step, where there is no DB connection, so we can't use the new default implementation of the `AbstractThemePathBuilder`, which stores the new `seed` in the DB during the theme compile.
But because of the `immutable deploys` it is not possible to recompile the theme at runtime, a new deployment is needed to recompile the theme.
So PaaS was not affected by the issues during the theme compilation, and instead of rollbacking to a backup theme folder you would rollback to the last deployment instead.

That means that PaaS does not need the seeding mechanism, so we add a implementation for the `AbstractThemePathBuilder` that ignores the seed and will always return the same path for a given theme and sales channel combination (like the old default implementation).

Once Platform.sh allows to store the theme assets externally we can move the theme compile from the `build` to the `deploy` step and can then use the default `seeding` implementation, as we have access to the DB in the deploy step.
Then you can also recompile the theme at runtime and PaaS will also benefit from the new theme compile mechanism.

---

---
url: /docs/v6.6/resources/references/adr/2023-01-10-atomic-theme-compilation.md
---

# Atomic theme compilation

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2023-01-10-atomic-theme-compilation.md)
:::

## Context

The theme compilation could result in a broken storefront, when there is some error during theme compilation (e.g. because of wrongly configured values in the theme configuration by the customer).
The reason is that the theme is always compiled into the same physical folder/location and at the start of the compilation this folder will be deleted and recreated, but when the compilation crashes due to errors, not all needed files are present in the theme folder and the storefront UI is broken.

Another issue was that there were edge cases when you hit a shop where the theme compilation was in progress, the storefront also may look broken as not all required compiled files are present in the theme folder (yet).

## Decision

Instead of compiling the theme always in the same folder we will compile the theme always in a new folder with a generated seed.
Until the theme compilation is completed and successful the old theme will be used in the storefront UI, only when the theme compilation is finished we will use the new theme folder in the storefront.

This will also open up the possibility for further new features where the customer may manually rollback to previous theme compiled version.
But for now we will delete the old theme folder one hour (see [caching](#caching)) after the theme was compiled successfully to the new location and we use the theme from the new location in the storefront.

### Discarded Alternatives

An alternative solution would be to always use the same folder location for the live version of the theme, but the theme compile process will not directly write into this folder, but in a temporary folder.
When the theme compilation finished we then copy the whole temp folder over to the live folder.

This approach works well under the assumptions that moving a whole folder is a fast and a atomic operation, which it is on most local filesystems.
But the theme assets can also be stored on external storage (e.g. S3, Google Cloud storage), especially for more dedicated setups it is common to store the asset files on a external filesystem/CDN.
And we can't assume that copying a whole folder is an atomic operation there, and in fact for S3 and Google Cloud Storage moving a folder means that we need to manually empty the target folder and move each file individually as both storages don't really support the concept of `folders`.
Even though this alternative fixed the issue when theme compilation errored, it does not fix the edge case when you hit a store where the current theme asset folder does not contain all needed folders yet. And as the files have to be copied one by one it would probably exaggerate that problem further.

Additionally, from a cost perspective the solution has some downsides, as on some (especially S3) external storages you not only pay for the storage itself, but also for file operations.
And using a temporary folder and then moving the folders will result in a lot more file operations, compared to directly compiling into the new folder.

Because of the aforementioned issues we decided to discard this approach.

## Consequences

We will expand the abstract class `AbstractThemePathBuilder` to allow for a `seeding` mechanism that allows to change the active theme folder path based on a randomly generated seed.

We add the two following methods that should be implemented in custom implementations of the `AbstractThemePathBuilder`.

```php
    public function generateNewPath(string $salesChannelId, string $themeId, string $seed): string
    {
    }

    public function saveSeed(string $salesChannelId, string $themeId, string $seed): void
    {
    }
```

During a theme compilation the theme compiler will generate a new random seed and call the `generateNewPath()` method with that seed, to get the location of the theme folder where the compiled files of that compilation will be stored.
After the theme compilation is finished successfully the compiler will call the `saveSeed()` method with the seed that was used for the compilation, after that subsequent calls to the existing `assemblePath()` method should take into account the new seed and thus the new theme folder should be used in the storefront.

### Backwards Compatibility

Those methods will be added as concrete methods in the abstract class with a default implementation, to not break backwards compatibility.
But both new methods are marked as `@deprecated`, because they will be abstract in the 6.6 major version, so custom implementations have to implement those methods for 6.6.
The default implementation to keep backwards compatibility will ignore the seed, so the `saveSeed()` method will be a no-op, and the `generateNewPath()` will just call the existing `assemblePath()` method, thus the behaviour for existing implementations will be the same as before this change.
This means that the old implementations also don't use the seeding mechanism, so the problems with the theme compilation will still be present in those implementations, unless the custom implementations also implement the seeding mechanism, by implementing the two new methods.

### Performance

The current `seed` has to be saved somewhere where it is fast to retrieve, as the `seed` value will be needed on every storefront request.
Therefore, we will store the `seed` in `system_config` table as the system config is already heavily cached and should not be a performance issue. Additionally it already allows saving values per sales channel which we need in this case.

We also considered storing the seed in an additional column in the `theme_sales_channel` mapping table and reading it in the `RequestTransformer` and then adding it as a `request attribute` for further usage.
This idea was discarded, because the DAL does not allow additional columns in mapping definitions, and in fact it will reset values in additional columns on every write as it uses `REPLACE INTO` queries to update the mappings.

### Caching

As the url to the assets now change this means that the cache for all storefront requests needs to be invalidated.
This was already the case previously as a new theme compilation would add a cache-buster query param to the url, to prevent the serving of stale theme files cached on the browser side.

But with the theme compilation, we can't delete the old theme folder immediately after the new theme compilation finished successfully, as the cache invalidation can take some time especially if you use external CDNs like fastly.
This means that we expect for a short time that clients still will request the old theme folder, because they are served stale content from the CDN.
To ensure that the site renders normally for those clients we won't delete the old theme folder immediately, but instead dispatch a queue message with a configurable delay (default 15 min / max SQS delay) that the old theme folder should be deleted.
So the old theme files will still be accessible for one hour after a new theme was compiled.

We can expand on this deletion strategy, once we implement further features like manual rollback to previous theme versions.

### Theme Assets

Previously the theme assets were stored in the same folder as the compiled theme files, that meant, that for every saleschannel where a theme was used the theme assets were duplicated, even though the assets are always the same, regardless of the theme configuration.
This does not scale, when we create new folders for the compiled theme files on the fly on every theme compile.
So the asset files are now stored in a separate folder, that is not dependent on the sales channel or the theme configuration.
We use the `themeId` as the folder name, so the assets are still unique per theme, but they are not duplicated for every sales channel.

### PaaS / Platform.sh

Platform.sh currently does not offer to store the theme assets on an internal storage, therefore the assets need to be stored locally.
Additionally, Platform.sh uses `immutable deploys`, meaning that once a version is deployed the file system is read-only and no changes can be made to the local files.

The theme compile is executed on PaaS during the `build` step, where there is no DB connection, so we can't use the new default implementation of the `AbstractThemePathBuilder`, which stores the new `seed` in the DB during the theme compile.
But because of the `immutable deploys` it is not possible to recompile the theme at runtime, a new deployment is needed to recompile the theme.
So PaaS was not affected by the issues during the theme compilation, and instead of rollbacking to a backup theme folder you would rollback to the last deployment instead.

That means that PaaS does not need the seeding mechanism, so we add a implementation for the `AbstractThemePathBuilder` that ignores the seed and will always return the same path for a given theme and sales channel combination (like the old default implementation).

Once Platform.sh allows to store the theme assets externally we can move the theme compile from the `build` to the `deploy` step and can then use the default `seeding` implementation, as we have access to the DB in the deploy step.
Then you can also recompile the theme at runtime and PaaS will also benefit from the new theme compile mechanism.

---

---
url: /docs/products/extensions/b2b-suite/guides/core/audit-log.md
---

# Audit Log

[Download](../example-plugins/B2bAcl.zip) a plugin showcasing the topic.

## Description

The B2B Suite provides a general audit log that can be implemented in every component.
The audit log component can save different log types and author information like first name, last name, and email.
It provides a one-to-many association index.
The database structure is described in the graphic below:

```mermaid
classDiagram 
    b2b_audit_log_index <--o b2b_audit_log : n to 1
    b2b_audit_log o--> b2b_audit_log_author : n to 1
    class b2b_audit_log_index{
        id 
        audit_log_id 
        reference_table 
        reference_id
    }
    class b2b_audit_log{
        id 
        log_value 
        log_type 
        event_date 
        author_hash
    }
    class b2b_audit_log_author{
        hash
        salutation
        title
        firstname
        lastname
        email
    }
```

As you can see, the database structure is very flat.
In the `b2b_audit_log` table, we save a log type and a serialized *AuditLogValueEntity*.
All required author information is saved in the `b2b_audit_log_author` table.

The `b2b_audit_log_index` saves all association data between an audit log and affected entities.
For example, if you change an order position, it would be nice to show this information in the main order view.

## A simple example

In this example, we will increase the quantity of an order position.
To create an audit log, you can use the following snippet:

```php
$auditLogValue = new AuditLogValueDiffEntity();
$auditLogValue->newValue = 'newValue';
$auditLogValue->oldValue = 'oldValue';

$auditLog = new AuditLogEntity();
$auditLog->logValue = $auditLogValue->toDatabaseString();
$auditLog->logType = 'changeOrderPosition';

$orderReferenceIndex = new AuditLogIndexEntity();
$orderReferenceIndex->referenceId = 10;
$orderReferenceIndex->referenceTable = OrderContextRepository::TABLE_NAME;

$this->auditLogService->createAuditLog($auditLog, $identity, [$orderReferenceIndex]);
```

With the following snippet, you can get all available audit logs:

```php
$auditLogSearchStruct = new AuditLogSearchStruct();
$auditLogs = $this->auditLogService->fetchList(OrderContextRepository::TABLE_NAME, 10, $auditLogSearchStruct);
```

---

---
url: /docs/v6.5/products/extensions/b2b-suite/guides/core/audit-log.md
---

# Audit Log

[Download](../../../../../../products/extensions/b2b/b2b-suite/guides/example-plugins/B2bAcl.zip) a plugin showcasing the topic.

## Description

The B2B Suite provides a general audit log that can be implemented in every component.
The audit log component can save different log types and author information like first name, last name, and email. It provides a one-to-many association index. The database structure is described in the graphic below:

```mermaid
classDiagram 
    b2b_audit_log_index <--o b2b_audit_log : n to 1
    b2b_audit_log o--> b2b_audit_log_author : n to 1
    class b2b_audit_log_index{
        id 
        audit_log_id 
        reference_table 
        reference_id
    }
    class b2b_audit_log{
        id 
        log_value 
        log_type 
        event_date 
        author_hash
    }
    class b2b_audit_log_author{
        hash
        salutation
        title
        firstname
        lastname
        email
    }
```

As you can see, the database structure is very flat. In the `b2b_audit_log` table, we save a log type and a serialized *AuditLogValueEntity*.
All required author information is saved in the `b2b_audit_log_author` table.

The `b2b_audit_log_index` saves all association data between an audit log and affected entities.
For example, if you change an order position, it would be nice to show this information in the main order view.

## A simple example

In this example, we will increase the quantity of an order position.
To create an audit log, you can use the following snippet:

```php
$auditLogValue = new AuditLogValueDiffEntity();
$auditLogValue->newValue = 'newValue';
$auditLogValue->oldValue = 'oldValue';

$auditLog = new AuditLogEntity();
$auditLog->logValue = $auditLogValue->toDatabaseString();
$auditLog->logType = 'changeOrderPosition';

$orderReferenceIndex = new AuditLogIndexEntity();
$orderReferenceIndex->referenceId = 10;
$orderReferenceIndex->referenceTable = OrderContextRepository::TABLE_NAME;

$this->auditLogService->createAuditLog($auditLog, $identity, [$orderReferenceIndex]);
```

With the following snippet, you can get all available audit logs:

```php
$auditLogSearchStruct = new AuditLogSearchStruct();
$auditLogs = $this->auditLogService->fetchList(OrderContextRepository::TABLE_NAME, 10, $auditLogSearchStruct);
```

---

---
url: /docs/v6.6/products/extensions/b2b-suite/guides/core/audit-log.md
---

# Audit Log

[Download](../example-plugins/B2bAcl.zip) a plugin showcasing the topic.

## Description

The B2B Suite provides a general audit log that can be implemented in every component.
The audit log component can save different log types and author information like first name, last name, and email.
It provides a one-to-many association index.
The database structure is described in the graphic below:

```mermaid
classDiagram 
    b2b_audit_log_index <--o b2b_audit_log : n to 1
    b2b_audit_log o--> b2b_audit_log_author : n to 1
    class b2b_audit_log_index{
        id 
        audit_log_id 
        reference_table 
        reference_id
    }
    class b2b_audit_log{
        id 
        log_value 
        log_type 
        event_date 
        author_hash
    }
    class b2b_audit_log_author{
        hash
        salutation
        title
        firstname
        lastname
        email
    }
```

As you can see, the database structure is very flat.
In the `b2b_audit_log` table, we save a log type and a serialized *AuditLogValueEntity*.
All required author information is saved in the `b2b_audit_log_author` table.

The `b2b_audit_log_index` saves all association data between an audit log and affected entities.
For example, if you change an order position, it would be nice to show this information in the main order view.

## A simple example

In this example, we will increase the quantity of an order position.
To create an audit log, you can use the following snippet:

```php
$auditLogValue = new AuditLogValueDiffEntity();
$auditLogValue->newValue = 'newValue';
$auditLogValue->oldValue = 'oldValue';

$auditLog = new AuditLogEntity();
$auditLog->logValue = $auditLogValue->toDatabaseString();
$auditLog->logType = 'changeOrderPosition';

$orderReferenceIndex = new AuditLogIndexEntity();
$orderReferenceIndex->referenceId = 10;
$orderReferenceIndex->referenceTable = OrderContextRepository::TABLE_NAME;

$this->auditLogService->createAuditLog($auditLog, $identity, [$orderReferenceIndex]);
```

With the following snippet, you can get all available audit logs:

```php
$auditLogSearchStruct = new AuditLogSearchStruct();
$auditLogs = $this->auditLogService->fetchList(OrderContextRepository::TABLE_NAME, 10, $auditLogSearchStruct);
```

---

---
url: /docs/products/tools/cli/shopware-account-commands/authentication.md
---

# Authentication

To interact with the Shopware Account API, you need to authenticate yourself. Run the command:

```bash
shopware-cli account login
```

A browser window will open for you to log in.

## Logout

To log out from the Shopware Account:

```bash
shopware-cli account logout
```

This removes your stored credentials from the CLI.

## CI/CD authentication

For CI/CD pipelines, pass `SHOPWARE_CLI_ACCOUNT_CLIENT_ID` and `SHOPWARE_CLI_ACCOUNT_CLIENT_SECRET` as environment variables and directly call the command you want to use. The client ID and client secret can be generated in the **Extension Partner** section under the [Development](https://account.shopware.com/producer/development) navigation point in the [Shopware Account](https://account.shopware.com).

## List extensions in producer account

To list all extensions in your producer account (across all projects and versions):

```bash
shopware-cli account producer extension list
```

This displays all extensions you have in the Shopware Store, including their names, versions, and status. This is useful for scripts and automation that need to query your store account.

---

---
url: /docs/v6.6/products/cli/shopware-account-commands/authentication.md
---

# Authentication

To interact with the Shopware Account API, you need to authenticate yourself.

For this, you need to log in using:

```bash
shopware-cli account login
```

and it will ask you interactively for your credentials.

For CI/CD pipelines, you should pass `SHOPWARE_CLI_ACCOUNT_EMAIL` and `SHOPWARE_CLI_ACCOUNT_PASSWORD` as environment variables and call directly the command you want to use.

::: info
For CI/CD tasks you should create a dedicated Shopware Account with limited access to the Shopware Store.
:::

## Multiple companies

A single Shopware Account can be part of multiple companies. You can only interact with one company at a time.

You can use the following commands to list all companies you have access to:

```bash
shopware-cli account company list
```

Next, select the active company with:

```bash
shopware-cli account company use <id>
```

---

---
url: /docs/guides/development/integrations-api/auth-api-requests.md
---

# Authentication and API Requests

This guide builds on the [APIs](./index.md) guide and covers additional authentication details, practical request patterns, and troubleshooting for local development.

## Local password-grant shortcut

The [APIs](./index.md) guide uses integrations with `client_credentials`, which should remain the default approach.

For local development only, you can also obtain an Admin API token with the default Administration credentials:

```bash
curl -X POST "http://localhost:8000/api/oauth/token" \
  -H "Content-Type: application/json" \
  -d '{
    "grant_type": "password",
    "client_id": "administration",
    "scopes": "write",
    "username": "admin",
    "password": "shopware"
  }'
```

Example response:

```json
{
  "token_type": "Bearer",
  "expires_in": 600,
  "access_token": "...",
  "refresh_token": "..."
}
```

Use this only as a local shortcut. For integrations and reproducible setups, prefer `client_credentials` as described in the [APIs](./index.md) guide.

## Prefer search endpoints for real requests

For most real Admin API work, prefer search endpoints over simple entity listing routes.

Instead of:

```bash
curl "http://localhost:8000/api/product" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json"
```

Use:

```bash
curl -X POST "http://localhost:8000/api/search/product" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'
```

Search endpoints support:

* filtering
* sorting
* pagination
* loading associations (loading relations of the entity in the same request)

## Download the OpenAPI schema

Shopware exposes OpenAPI schema endpoints for both Admin API and Store API. If you want to work with the raw Admin API schemas instead of the browser reference, you can download them directly.

### OpenAPI specification

Use the OpenAPI spec when you need the full API contract for tooling, client generation, or inspection of available endpoints.

```bash
curl -X GET "http://localhost:8000/api/_info/openapi3.json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o openapi.json
```

This saves the file as `openapi.json` in your current working directory.

To verify where it was written and inspect it:

```bash
pwd
ls -lh openapi.json
head -n 5 openapi.json
```

### Entity schema

Use the entity schema when you need metadata about entities and their fields:

```bash
curl -X GET "http://localhost:8000/api/_info/open-api-schema.json" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -o entity-schema.json
```

To verify the downloaded file:

```bash
pwd
ls -lh entity-schema.json
head -n 5 entity-schema.json
```

::: warning
Due to security restrictions, your `APP_ENV` environment variable must be set to `dev` to access the specifications described below.
:::

Available raw schema endpoints:

* OpenAPI spec: `/(api|store-api)/_info/openapi3.json`.
* Entity schema: `/(api|store-api)/_info/open-api-schema.json`.

## Troubleshooting local request failures

If you encounter errors like:

* `Table 'shopware.system_config' doesn't exist`
* `Table 'shopware.plugin' doesn't exist`
* `HTTP 500 on /api/_info/openapi3.json`

your database may not be initialized.

Run:

```bash
docker compose exec web bin/console system:install --create-database --basic-setup
```

## Next steps

Learn how to structure queries using:

* [Search Criteria](../integrations-api/search-criteria.md): Encapsulates the entire search definition in one generic object.
* [Request Headers](../integrations-api/request-headers.md): Covers optional headers that customize API requests.
* [Partial Data Loading](../integrations-api/partial-data-loading.md): Limits responses to the fields you actually need.

---

---
url: /docs/products/tools/cli/project-commands/autofix.md
---

# Autofixer

Shopware-CLI comes with some builtin auto fixers for project migrations.

## Migrate a project to Symfony Flex

Shopware 6.4 and earlier used a different project structure without Symfony Flex. When upgrading to Shopware 6.5 or later, the `shopware-cli project autofix flex` command will migrate your project from the legacy structure to Symfony Flex, moving all configuration files to the correct locations.

::: warning
Ensure that you have a backup of your project before running this command.
:::

```bash
shopware-cli project autofix flex
```

The command will delete all unnecessary configuration files. It will also update the `composer.json` file and the `bin/console` file to use the new configuration files.

## Migrate custom/plugins extensions to Composer

Instead of manually cloning extensions into `custom/plugins`, it's best practice to manage store extensions via Composer. [For more details, see this guide](../../../../guides/hosting/installation-updates/extension-management.md).

Migrate locally cloned plugins to Composer-managed extensions:

```bash
shopware-cli project autofix composer-plugins
```

Benefits of using Composer:

* Composer knows which extension versions exist and are compatible
* Automatic dependency resolution: Composer handles version compatibility for you
* Automatic updates: easily update extensions to new versions
* Less manual work: no need to manually clone and manage extensions in custom directories

You need a Shopware Packages Token. Get it from your Shopware Account: "Shops" > "Licenses" > "..." of one extension > "Install via Composer".

---

---
url: /docs/v6.6/products/cli/project-commands/autofix.md
---

# Autofixer

Shopware-CLI comes with some builtin auto fixers for project migrations.

## Migrate a Project to Symfony Flex

Prior to Shopware 6.5, Shopware didn't use Symfony Flex. This means that the project structure was different, and some configuration files were located in different places. The `shopware-cli project autofix flex` command will migrate your project to Symfony Flex and move all configuration files to the correct locations.

::: warning
Ensure that you have a backup of your project before running this command.
:::

```bash
shopware-cli project autofix flex
```

The command will delete all unnecessary configuration files. It will also update the `composer.json` file and the `bin/console` file to use the new configuration files.

## Migrate custom/plugins extensions to Composer

It's best practice to manage the store and your custom plugins via Composer. [If you want to learn more about this check out this guide](../../../guides/hosting/installation-updates/extension-managment.md). Shopware-CLI has a helper for migrating locally installed plugins to Composer through Shopware Packagist for the Shopware Store. Make sure you have a Shopware Packages Token, which can be gathered in the Shopware Account. You can find the token in the Shopware Account under "Shops" > "Licenses" > "..." of one extension and "Install via Composer.

```bash
shopware-cli project autofix composer-plugins
```

---

---
url: /docs/products/tools/cli/automatic-refactoring.md
---

# Automatic refactoring

Shopware CLI includes a built-in automatic refactoring tool with pre-configured rules for Shopware projects. Instead of manually configuring and managing multiple linters and fixers, this tool automatically handles breaking changes and code modernization when you upgrade Shopware versions.

Use this tool to:

* Automatically fix breaking changes between Shopware versions
* Apply Shopware-idiomatic code fixes
* Modernize your codebase without manual linter configuration

The tool uses:

* [Rector](https://getrector.com/) for PHP
* [ESLint](https://eslint.org/) for JavaScript
* Custom rules for Admin Twig files

The refactoring command runs PHP and Node.js tooling under the hood. The Docker examples are recommended because the image already contains the required runtime dependencies. If PHP and Node.js are available locally, you can run the `shopware-cli` commands directly instead.

## Refactoring an extension

::: warning
Before you start, make sure you work on a copy or Git-versioned branch, because this command will modify your files in place!
:::

The command mounts your current directory to `/ext` inside the container and refactors that mounted extension directory:

```shell
docker run --rm -v "$(pwd)":/ext ghcr.io/shopware/shopware-cli extension fix /ext
```

Use the local path to your extension when running the command without Docker:

```shell
shopware-cli extension fix /path/to/your/extension
```

## Refactoring an entire project

You can also refactor a full Shopware project instead of a single extension.

The command mounts your current directory to `/project` inside the container and refactors that mounted project directory:

```shell
docker run --rm -v "$(pwd)":/project ghcr.io/shopware/shopware-cli project fix /project
```

Use the local path to your project when running the command without Docker:

```shell
shopware-cli project fix /path/to/your/project
```

The CLI runs Rector and ESLint automatically. After completion, review all changes and commit or revert them as needed.

Make sure the `shopware/core` requirement in your `composer.json` file reflects the version you're targeting. Shopware CLI determines which upgrade rules to apply based on that version constraint.

### Project fix options

Run only specific tools:

```shell
shopware-cli project fix /path/to/your/project --only phpstan
shopware-cli project fix /path/to/your/project --only "phpstan,eslint"
```

Allow running on non-Git repositories:

```shell
shopware-cli project fix /path/to/your/project --allow-non-git
```

By default, `project fix` requires a Git repository to safely track changes.

## After running refactoring

Use Git or your diff tool to review the changes.

Test your extension or project thoroughly.

Commit the accepted changes and discard any unwanted ones.

You can combine automatic refactoring with other Shopware CLI commands (e.g., `project build` or `extension validate`) as part of your upgrade workflow.

---

---
url: /docs/v6.6/products/cli/automatic-refactoring.md
---

# Automatic refactoring

Shopware-CLI comes with a built-in automatic refactoring tool for PHP, JavaScript, and Admin Twig files.

It uses the tools:

* [Rector](https://getrector.org/) for PHP
* [ESLint](https://eslint.org/) for JavaScript
* Custom rules for Admin Twig files

## Refactoring an extension

::: warning
Make sure you have a copy of your extension before running the command, as it will change your files!
:::

```shell
shopware-cli extension fix /path/to/your/extension
```

```shell
docker run --rm -v $(pwd):/ext shopware/shopware-cli extension fix /ext
```

## Refactoring an entire project

```shell
shopware-cli project fix /path/to/your/project
```

```shell
docker run --rm -v $(pwd):/ext shopware/shopware-cli project fix /project
```

This will execute Rector and ESLint to refactor your code. You should review the changes made and decide whether you want to keep them or not.

Make sure that you have adjusted the `shopware/core` requirement in the `composer.json` file of your extension to the version you want to upgrade to. It will use the lowest supported version your Composer constraint is compatible with.

## Experimental Twig upgrade using Large Language Models

The Extension Verifier also includes an experimental feature to upgrade your Twig templates using Large Language Models (LLMs). This feature is experimental and should only be executed on code that is versioned in Git or similar.
To use this feature, you can run the following command:

```shell
shopware-cli extension ai twig-upgrade /ext 6.6.0.0 6.7.0.0-rc1 --provider gemini --model gemini-2.5-pro-exp-03-25
```

```shell
docker run --rm -v $(pwd):/ext shopware/shopware-cli extension ai twig-upgrade /ext 6.6.0.0 6.7.0.0-rc1 --provider gemini --model gemini-2.5-pro-exp-03-25
```

Extension Verifier currently supports multiple providers:

* `gemini` - Google Gemini LLM (requires `GEMINI_API_KEY` environment variable)
* `openrouter` - OpenRouter API (requires `OPENROUTER_API_KEY` environment variable)
* `ollama` - Local Ollama (uses localhost by default, `OLLAMA_HOST` environment variable can be used to specify a different host)

Our recommendation is to use Google Gemini 2.5 Pro, as it provides the best results for the upgrade.

---

---
url: /docs/resources/references/adr/2022-03-25-available-stock.md
---

# Available stock improvements

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-03-25-available-stock.md)
:::
Currently, the available stock calculation is performed on every update of a product. This is true if the product is updated via the API but also if it is ordered via the store api route. When an order is placed, this is triggered by `StockUpdater::lineItemWritten` and performs an update of the available stock by subtracting the stock with the quantity of open orders. If there are many open orders in the storage, this can lead to a bottleneck if many orders are executed at the same time, with the same products.

We have solved this problem by updating the available stock directly in the `CheckoutOrderPlaced` event with the ordered quantity:

```php
public function orderPlaced(CheckoutOrderPlacedEvent $event): void
{
    $ids = [];
    foreach ($event->getOrder()->getLineItems() as $lineItem) {
        if ($lineItem->getType() !== LineItem::PRODUCT_LINE_ITEM_TYPE) {
            continue;
        }

        if (!\array_key_exists($lineItem->getReferencedId(), $ids)) {
            $ids[$lineItem->getReferencedId()] = 0;
        }

        $ids[$lineItem->getReferencedId()] += $lineItem->getQuantity();
    }

    // order placed event is a high load event. Because of the high load, we simply reduce the quantity here instead of executing the high costs `update` function
    $query = new RetryableQuery(
        $this->connection,
        $this->connection->prepare('UPDATE product SET available_stock = available_stock - :quantity WHERE id = :id')
    );

    foreach ($ids as $id => $quantity) {
        $query->execute(['id' => Uuid::fromHexToBytes((string) $id), 'quantity' => $quantity]);
    }

    $this->updateAvailableFlag(\array_keys($ids), $event->getContext());
}
```

To prevent executing the `lineItemWritten` logic in addition to the `CheckoutOrderPlaced` logic, we set a context state within the `CartOrderRoute`, which we can then query in the event listener and skip the process:

```php
public function lineItemWritten(EntityWrittenEvent $event): void
{
    $ids = [];

    // we don't want to trigger to `update` method when we are inside the order process
    if ($event->getContext()->hasState('checkout-order-route')) {
        return;
    }
    
    //...
}
```

In addition to this optimization, we only perform a stock update if one of the three relevant fields (`stock`, `minPurchase`, `isCloseout`) has changed. This is checked in the `ProductIndexer` within the `update` method:

```php
$stocks = $event->getPrimaryKeysWithPropertyChange(ProductDefinition::ENTITY_NAME, ['stock', 'isCloseout', 'minPurchase']);
$this->stockUpdater->update($stocks, $event->getContext());
```

---

---
url: /docs/v6.5/resources/references/adr/2022-03-25-available-stock.md
---

# Available stock improvements

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-03-25-available-stock.md)
:::
Currently, the available stock calculation is performed on every update of a product. This is true if the product is updated via the API but also if it is ordered via the store api route. When an order is placed, this is triggered by `StockUpdater::lineItemWritten` and performs an update of the available stock by subtracting the stock with the quantity of open orders. If there are many open orders in the storage, this can lead to a bottleneck if many orders are executed at the same time, with the same products.

We have solved this problem by updating the available stock directly in the `CheckoutOrderPlaced` event with the ordered quantity:

```php
public function orderPlaced(CheckoutOrderPlacedEvent $event): void
{
    $ids = [];
    foreach ($event->getOrder()->getLineItems() as $lineItem) {
        if ($lineItem->getType() !== LineItem::PRODUCT_LINE_ITEM_TYPE) {
            continue;
        }

        if (!\array_key_exists($lineItem->getReferencedId(), $ids)) {
            $ids[$lineItem->getReferencedId()] = 0;
        }

        $ids[$lineItem->getReferencedId()] += $lineItem->getQuantity();
    }

    // order placed event is a high load event. Because of the high load, we simply reduce the quantity here instead of executing the high costs `update` function
    $query = new RetryableQuery(
        $this->connection,
        $this->connection->prepare('UPDATE product SET available_stock = available_stock - :quantity WHERE id = :id')
    );

    foreach ($ids as $id => $quantity) {
        $query->execute(['id' => Uuid::fromHexToBytes((string) $id), 'quantity' => $quantity]);
    }

    $this->updateAvailableFlag(\array_keys($ids), $event->getContext());
}
```

To prevent executing the `lineItemWritten` logic in addition to the `CheckoutOrderPlaced` logic, we set a context state within the `CartOrderRoute`, which we can then query in the event listener and skip the process:

```php
public function lineItemWritten(EntityWrittenEvent $event): void
{
    $ids = [];

    // we don't want to trigger to `update` method when we are inside the order process
    if ($event->getContext()->hasState('checkout-order-route')) {
        return;
    }
    
    //...
}
```

In addition to this optimization, we only perform a stock update if one of the three relevant fields (`stock`, `minPurchase`, `isCloseout`) has changed. This is checked in the `ProductIndexer` within the `update` method:

```php
$stocks = $event->getPrimaryKeysWithPropertyChange(ProductDefinition::ENTITY_NAME, ['stock', 'isCloseout', 'minPurchase']);
$this->stockUpdater->update($stocks, $event->getContext());
```

---

---
url: /docs/v6.6/resources/references/adr/2022-03-25-available-stock.md
---

# Available stock improvements

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-03-25-available-stock.md)
:::
Currently, the available stock calculation is performed on every update of a product. This is true if the product is updated via the API but also if it is ordered via the store api route. When an order is placed, this is triggered by `StockUpdater::lineItemWritten` and performs an update of the available stock by subtracting the stock with the quantity of open orders. If there are many open orders in the storage, this can lead to a bottleneck if many orders are executed at the same time, with the same products.

We have solved this problem by updating the available stock directly in the `CheckoutOrderPlaced` event with the ordered quantity:

```php
public function orderPlaced(CheckoutOrderPlacedEvent $event): void
{
    $ids = [];
    foreach ($event->getOrder()->getLineItems() as $lineItem) {
        if ($lineItem->getType() !== LineItem::PRODUCT_LINE_ITEM_TYPE) {
            continue;
        }

        if (!\array_key_exists($lineItem->getReferencedId(), $ids)) {
            $ids[$lineItem->getReferencedId()] = 0;
        }

        $ids[$lineItem->getReferencedId()] += $lineItem->getQuantity();
    }

    // order placed event is a high load event. Because of the high load, we simply reduce the quantity here instead of executing the high costs `update` function
    $query = new RetryableQuery(
        $this->connection,
        $this->connection->prepare('UPDATE product SET available_stock = available_stock - :quantity WHERE id = :id')
    );

    foreach ($ids as $id => $quantity) {
        $query->execute(['id' => Uuid::fromHexToBytes((string) $id), 'quantity' => $quantity]);
    }

    $this->updateAvailableFlag(\array_keys($ids), $event->getContext());
}
```

To prevent executing the `lineItemWritten` logic in addition to the `CheckoutOrderPlaced` logic, we set a context state within the `CartOrderRoute`, which we can then query in the event listener and skip the process:

```php
public function lineItemWritten(EntityWrittenEvent $event): void
{
    $ids = [];

    // we don't want to trigger to `update` method when we are inside the order process
    if ($event->getContext()->hasState('checkout-order-route')) {
        return;
    }
    
    //...
}
```

In addition to this optimization, we only perform a stock update if one of the three relevant fields (`stock`, `minPurchase`, `isCloseout`) has changed. This is checked in the `ProductIndexer` within the `update` method:

```php
$stocks = $event->getPrimaryKeysWithPropertyChange(ProductDefinition::ENTITY_NAME, ['stock', 'isCloseout', 'minPurchase']);
$this->stockUpdater->update($stocks, $event->getContext());
```

---

---
url: /frontends/best-practices/testing/accessibility-testing.md
---

# Axe Core

Axe Core is an open-source accessibility testing engine used for automated web testing. You can use it as an extension for Chrome or Firefox to scan web pages for accessibility issues and also implement it in the e2e tests used (e.g. in Playwright) and automate accessibility checks in continuous integration environments.

## Axe Core

Playwright and e2e tests can also be used to test application for many types of accessibility issues.
By default, axe checks against a wide variety of accessibility rules, but rules can be defined easily at the test level

```js
const accessibilityScanResults = await new AxeBuilder({ page })
  .withTags(["wcag2a", "wcag2aa", "wcag21a", "wcag21aa"])
  .analyze();
```

## Example accessibility tests

Using the ax core library is practically no different from typical work with playwright. You can create tests for each page from scratch or integrate accessibility scans and assertions into your existing test cases.

```js
import { test, expect } from '@playwright/test';
import AxeBuilder from "@axe-core/playwright";

//Uses normal Playwright Test syntax to define a test case
test('Check accessibility violations', async ({ page }) => {
//Uses normal Playwright syntax to navigate to the page under test
  await page.goto('https://example.com');
//Awaits AxeBuilder.analyze() to run the accessibility scan against the page
  const accessibilityScanResults = await new AxeBuilder({ page }).analyze();
  //Uses normal Playwright Test assertions to verify that there are no violations in the returned scan results
      expect(accessibilityScanResults.violations).toEqual([]);
```

You can also run tests for a specific part of the page

```js
test("navigation menu should not have automatically detectable accessibility violations", async ({
  page,
}) => {
  await page.goto("https://your-site.com/");

  await page.getByRole("button", { name: "Navigation Menu" }).click();

  // It is important to waitFor() the page to be in the desired
  // state *before* running analyze(). Otherwise, axe might not
  // find all the elements your test expects it to scan.
  await page.locator("#navigation-menu-flyout").waitFor();

  const accessibilityScanResults = await new AxeBuilder({ page })
    .include("#navigation-menu-flyout")
    .analyze();

  expect(accessibilityScanResults.violations).toEqual([]);
});
```

---

---
url: /docs/v6.5/products/extensions/b2b-components.md
---

# B2B Components

The B2B Components allow merchants to selectively choose and configure B2B capabilities according to their needs. They offer merchants the ability to craft a tailored B2B ecommerce experience for their business partners while also allowing agencies to fine-tune Shopware to meet specific requirements. This means that B2B Components can be individually activated or deactivated for each business partner.

In the world of digital B2B commerce, where businesses engage with other companies, we emphasize this vital distinction through these specific features :

* **Employee Management** enables B2B Merchants to create a buyer platform for their business partners.

* **Quote Managements** covers Sales Representative related jobs around negotiating quotes with customers.

* **Order Approval** allows for a more controlled buying process by introducing an approval workflow.

* **Quick Order and Order List** takes care of distinctive B2B buying behaviors.

* **Digital Sales Composables** aims to provide a set of composable frontends to cover more complex Sales Representative jobs.

---

---
url: >-
  /docs/products/extensions/b2b-components/employee-management/guides/subscription-integration.md
---

# B2B Employee Integration for Subscriptions

This guide describes how B2B Employees are integrated with the Subscription module, enabling employee-based subscription management and tracking within a B2B context.

## Overview

The B2B Employee Integration for Subscriptions extends subscription functionality to support B2B employee workflows without modifying the core Subscription module. All B2B-specific logic is contained within the B2B Employee Management module using decorators, extensions, and event subscribers.

This integration enables:

* **Permission-based subscription access** - Control which subscriptions employees can view
* **Employee tracking** - Track which employee created each subscription
* **Organization context preservation** - Maintain organization data throughout the subscription lifecycle

## Prerequisites

* Shopware 6.7 with Subscriptions extension
* B2B Components with Employee Management module
* Understanding of [Subscription concepts](../../../../extensions/subscriptions/concept.md)
* Understanding of [B2B Employee Management concepts](../concepts/index.md)

## Key Features

### Employee-Based Subscription Permissions

Employees can view subscriptions based on their assigned permissions:

| Permission                            | Access Level                                                           |
|---------------------------------------|------------------------------------------------------------------------|
| `subscription.read.all`               | View all subscriptions in the system                                   |
| `organization_unit.subscription.read` | View subscriptions from assigned organization unit + own subscriptions |
| (no permission)                       | View only own subscriptions                                            |

These permissions are checked when employees access subscription lists, ensuring data isolation and security in B2B contexts.

### Employee Tracking

Subscriptions track which employee created them through the `b2b_components_subscription_employee` association table. This enables:

* **Permission-based filtering** - Filter subscriptions by employee and organization
* **Employee context in orders** - Both initial and renewal orders maintain employee context
* **Audit trails** - Track which employee initiated each subscription

### Organization Context

Organization data is preserved throughout the subscription lifecycle:

* **Initial orders** - Organization data is added when a subscription is created during checkout
* **Renewal orders** - Organization data is maintained in later automated orders
* **Context preservation** - Organization information flows through all subscription-related processes

## Architecture

### Core Components

The integration is built using several key components in the B2B Employee Management module:

**Decorators:**

* `SubscriptionRouteDecorator` - Decorates `SubscriptionRoute` to apply permission-based filtering
* `SalesChannelContextServiceDecorator` - Adds employee context to subscription sales channel contexts

**Event Subscribers:**

* `SubscriptionTransformedSubscriber` - Adds employee and organization data during subscription creation
* `SubscriptionCartConvertedSubscriber` - Adds employee and organization data to initial orders
* `SubscriptionOrderPlacedSubscriber` - Maintains employee context in renewal orders

**Entity Extension:**

* `SubscriptionExtension` - Extends `SubscriptionDefinition` with `subscriptionEmployee` association
* `SubscriptionEmployeeDefinition` - Defines the subscription-employee relationship

**Filter Service:**

* `SubscriptionEmployeeFilter` - Implements permission-based subscription filtering logic

### Integration Patterns

The integration follows Shopware best practices:

**1. Decorator Pattern**

Instead of modifying core Subscription code, the integration uses decorators to extend functionality:

```php
// SubscriptionRouteDecorator wraps the core SubscriptionRoute
$this->decorated->load($request, $context, $criteria);
// Then applies employee-based filtering
$this->subscriptionEmployeeFilter->applyEmployeeFilter($criteria, $employee);
```

**2. Event-Based Integration**

Key subscription events are used to inject employee data:

* `SubscriptionTransformedEvent` - Fired when subscription is created from cart
* `SUBSCRIPTION_CART_CONVERTED` - Fired when subscription cart is converted to order
* `CheckoutOrderPlacedEvent` - Fired when renewal order is placed

**3. Entity Extension Pattern**

The `SubscriptionExtension` adds the employee association to subscriptions without modifying the core entity:

```php
new OneToOneAssociationField(
    'subscriptionEmployee',
    'id',
    'subscription_id',
    SubscriptionEmployeeDefinition::class,
    false
);
```

## Database Schema

### b2b\_components\_subscription\_employee Table

This table links subscriptions to the employees who created them:

| Column            | Type        | Description                            |
|-------------------|-------------|----------------------------------------|
| `id`              | BINARY(16)  | Primary key                            |
| `subscription_id` | BINARY(16)  | Foreign key to `subscription` (UNIQUE) |
| `employee_id`     | BINARY(16)  | Foreign key to `b2b_employee`          |
| `created_at`      | DATETIME(3) | Creation timestamp                     |
| `updated_at`      | DATETIME(3) | Update timestamp                       |

**Key characteristics:**

* One-to-one relationship between subscription and subscription\_employee
* `subscription_id` has a UNIQUE constraint ensuring one employee per subscription
* Foreign keys maintain referential integrity

## Technical Flows

### Initial Subscription Order Flow

When an employee checks out with a subscription product, the following flow occurs:

```mermaid
sequenceDiagram
    participant Customer as Employee Customer
    participant Checkout as Checkout Process
    participant Transformer as SubscriptionTransformer
    participant TransformedSub as SubscriptionTransformedSubscriber
    participant CartSub as SubscriptionCartConvertedSubscriber
    participant Order as Initial Order

    Customer->>Checkout: Checkout with subscription product
    Checkout->>Transformer: transform() subscription cart
    Transformer->>TransformedSub: dispatch SubscriptionTransformedEvent
    TransformedSub->>TransformedSub: Add subscriptionEmployee data
    TransformedSub->>TransformedSub: Add orderEmployee to convertedOrder
    TransformedSub->>TransformedSub: Add organization to convertedOrder
    Transformer->>CartSub: dispatch SUBSCRIPTION_CART_CONVERTED
    CartSub->>CartSub: Add orderEmployee to cart
    CartSub->>CartSub: Add organization to cart
    CartSub->>Order: Create initial order with employee + org

    Note over Order: Initial Order has:<br/>- orderEmployee ✓<br/>- organization ✓
    Note over Transformer: Subscription has:<br/>- subscriptionEmployee ✓<br/>- convertedOrder with employee ✓
```

**Key Points:**

1. `SubscriptionTransformedSubscriber` adds employee and organization data to the subscription being created
2. `SubscriptionCartConvertedSubscriber` ensures the initial order contains employee and organization data
3. The subscription's `convertedOrder` field stores this data for future renewal orders

### Permission-Based Subscription Filtering

When an employee views their subscriptions, filtering is applied based on permissions:

```mermaid
flowchart TD
    Start[Employee loads subscriptions]
    Start --> Decorator[SubscriptionRouteDecorator]
    Decorator --> Filter[SubscriptionEmployeeFilter]
    Filter --> CheckAll{Has subscription.read.all?}

    CheckAll -->|Yes| NoFilter[No filter applied]
    NoFilter --> ResultAll[View ALL subscriptions]

    CheckAll -->|No| CheckOrg{Has organization_unit<br/>.subscription.read?}

    CheckOrg -->|Yes| OrgFilter[Apply OR filter]
    OrgFilter --> OwnSubs[Own subscriptions]
    OrgFilter --> OrgSubs[Organization subscriptions]
    OrgSubs --> ResultOrg[View own + org subscriptions]
    OwnSubs --> ResultOrg

    CheckOrg -->|No| EmpFilter[Filter by employeeId]
    EmpFilter --> ResultOwn[View ONLY own subscriptions]
```

**Permission Logic:**

* **No filter** (`subscription.read.all`) - Employee sees all subscriptions
* **OR filter** (`organization_unit.subscription.read`) - Employee sees their own subscriptions or subscriptions from their organization unit
* **Default filter** - Employee sees only subscriptions they created

## Developer Integration Points

### Accessing Employee Data from Subscriptions

To access the employee who created a subscription:

```php
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;

// Add association when loading subscriptions
$criteria = new Criteria();
$criteria->addAssociation('subscriptionEmployee.employee');

$subscription = $subscriptionRepository->search($criteria, $context)->first();

if ($subscription->getSubscriptionEmployee()) {
    $employee = $subscription->getSubscriptionEmployee()->getEmployee();
    // Access employee data
}
```

### Accessing Employee Data from Orders

Employee data is stored in order extensions:

```php
// For initial or renewal orders
$order = $orderRepository->search($criteria, $context)->first();

// Check if the order has employee context
$orderEmployee = $order->getExtension('orderEmployee');
if ($orderEmployee) {
    $employeeId = $orderEmployee->getEmployeeId();
}

// Check if the order has organization context
$organization = $order->getExtension('organization');
if ($organization) {
    $organizationId = $organization->getId();
}
```

### Event Subscribers

The integration provides several event subscribers you can use as reference:

**SubscriptionTransformedSubscriber** - Priority: 0

Listens to: `SubscriptionTransformedEvent`

Use case: Add custom data when a subscription is created from a cart

**SubscriptionCartConvertedSubscriber** - Priority: 0

Listens to: `SUBSCRIPTION_CART_CONVERTED` event

Use case: Modify the initial order data during subscription checkout

**SubscriptionOrderPlacedSubscriber** - Priority: 0

Listens to: `CheckoutOrderPlacedCriteriaEvent` and `CheckoutOrderPlacedEvent`

Use case: Add employee context to renewal orders

### Adding Custom Logic

To add custom B2B logic to subscriptions:

1. **Create a decorator** for subscription services (follow `SubscriptionRouteDecorator` pattern)
2. **Subscribe to subscription events** to inject your data
3. **Use entity extensions** to add custom associations without modifying core entities
4. **Check context state** instead of relying on event priorities for more robust integration

Example decorator pattern:

```php
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class CustomSubscriptionServiceDecorator extends AbstractSubscriptionService
{
    public function __construct(
        private readonly AbstractSubscriptionService $decorated,
        private readonly CustomLogicService $customService
    ) {}

    public function getDecorated(): AbstractService
    {
        return $this->decorated;
    }

    public function someMethod(SalesChannelContext $context): void
    {
        // Your custom logic before
        $this->customService->doSomething($context);

        // Call decorated service
        $this->decorated->someMethod($context);

        // Your custom logic after
    }
}
```

## Related Documentation

* [Subscription Concept](../../../../extensions/subscriptions/concept.md) - Core subscription concepts
* [Mixed Checkout](../../../../extensions/subscriptions/guides/mixed-checkout.md) - Mixed cart checkout flow
* [Separate Checkout](../../../../extensions/subscriptions/guides/separate-checkout.md) - Separate subscription checkout
* [B2B Employee Management Concepts](../concepts/index.md) - Employee and role concepts
* [Creating Permissions via Plugin](./creating-own-permissions-via-plugin.md) - How to extend permissions
* [API Route Restriction](./api-route-restriction-for-employees.md) - Route-level permission control

## Summary

The B2B Employee Integration for Subscriptions provides a clean, maintainable way to add employee context to subscriptions without modifying core code. By using decorators, event subscribers, and entity extensions, the integration:

* Maintains separation of concerns between modules
* Follows Shopware architectural patterns
* Enables permission-based subscription access
* Preserves employee and organization context throughout the subscription lifecycle
* Provides clear extension points for custom logic

---

---
url: /docs/products/extensions/subscriptions/guides/b2b-employee-integration.md
---

# B2B Employee Integration for Subscriptions

When using Subscriptions together with B2B Components Employee Management, subscriptions can be managed and tracked in a B2B employee context.

## Overview

The B2B Employee Integration extends subscription functionality to support employee-based workflows in B2B scenarios. This integration enables:

* **Permission-based subscription access** - Control which subscriptions employees can view based on their assigned permissions
* **Employee tracking** - Track which employee created each subscription for audit and reporting purposes
* **Organization context** - Maintain organization information in both initial and renewal subscription orders

## When to Use

This integration is relevant when you have:

* A B2B store with employee management enabled
* Subscriptions that employees should manage on behalf of their organization
* Requirements for permission-based access control to subscription data
* Need for tracking which employee initiated subscriptions

## Prerequisites

To use this integration, you need:

* Shopware 6.7 with the **Subscriptions** extension installed
* **B2B Components** with Employee Management module enabled
* Employees configured with appropriate roles and permissions

## Key Capabilities

### 1. Permission-Based Viewing

Employees can view subscriptions based on three permission levels:

* **`subscription.read.all`** - View all subscriptions in the system
* **`organization_unit.subscription.read`** - View subscriptions from their organization unit plus their own
* **No subscription permission** - View only subscriptions they personally created

### 2. Employee Context in Orders

When an employee creates a subscription:

* The **initial order** includes employee and organization data
* All **renewal orders** automatically maintain this context
* Employee information is preserved for reporting and compliance

### 3. Transparent Integration

The integration works seamlessly with existing subscription workflows:

* Works with both [separate checkout](./separate-checkout.md) and [mixed checkout](./mixed-checkout.md) flows
* No changes required to existing subscription products or plans
* Employee context is automatically added when an employee is logged in

## Technical Documentation

For detailed technical information including architecture, event flows, database schema, and developer integration points, see:

**[B2B Employee Subscription Integration Guide](../../b2b-components/employee-management/guides/subscription-integration.md)**

The technical guide covers:

* Architecture and integration patterns (decorators, event subscribers, entity extensions)
* Database schema for employee-subscription relationships
* Detailed flow diagrams for initial orders, renewals, and permission filtering
* Code examples for accessing employee data from subscriptions and orders
* Extension points for adding custom B2B logic

## Related Documentation

* [Subscription Concept](../concept.md) - Understanding subscription fundamentals
* [Mixed Checkout](./mixed-checkout.md) - Mixed cart checkout with subscriptions
* [Separate Checkout](./separate-checkout.md) - Separate subscription checkout flow
* [B2B Employee Management](../../b2b-components/employee-management/index.md) - Employee and role management basics

---

---
url: >-
  /docs/v6.5/products/extensions/b2b-components/employee-management/guides/b2b-employee-invite-registration.md
---

# B2B Employee invite / registration

Employees can be created via storefront and api to get an invite mail. This has to be later confirmed by the employee to set a password.

It’s possible to invite new employees or manage them via the API.

---

---
url: /frontends/guides/b2b.md
---

# B2B modules

Collection of B2B elements and documentation how to use them.

---

---
url: /frontends/guides/b2b/quote-management.md
---

# B2B Quote Management

In this chapter you will learn how to

* Request new quote
* Fetch a list of quote and display detail
* Decline quote
* Request change in quote
* Change payment or shipping in quote
* Create a order from a quote

## Quick reference

* [useB2bQuoteManagement](../../packages/composables/useB2bQuoteManagement) is a composable used for a quote management

## Request new quote

The "Request New Quote" feature allows B2B users to request a custom quote for their current basket. This is particularly useful for large or complex orders where standard pricing may not apply, or special discounts may be negotiated.

This feature enhances the B2B shopping experience by providing flexibility in pricing and order customization. It also allows for direct communication between the buyer and seller, facilitating better negotiation and understanding of needs.

:::warning
Cart cannot be empty
:::

```vue
<script setup lang="ts">
import { ref } from "vue";
import { useCart, useB2bQuoteManagement } from "@shopware/composables";
const { cartItems } = useCart();
const { requestQuote } = useB2bQuoteManagement();
const comment = ref("");
const handleRequestQuote = async () => {
  await requestQuote(comment.value);
};
</script>
<template>
  <textarea v-model="comment"> </textarea>
  <button :disabled="cartItems.length <= 0" @click="handleRequestQuote">
    Request quote
  </button>
</template>
```

## Fetch a list of quote and display detail

This feature allows users to retrieve a list of all their requested quotes or quotes created by the admin.

```vue
<script setup lang="ts">
import { ref, onBeforeMount } from "vue";
import { useB2bQuoteManagement } from "@shopware/composables";
const quotesList = ref([]);
const { getQuoteList } = useB2bQuoteManagement();
onBeforeMount(async () => {
  quotesList.value = await getQuoteList();
});
</script>
<template>
  <table>
    <thead>
      <tr>
        <th>Quote #</th>
        <th>Created at</th>
        <th>Valid until</th>
        <th>Grand total</th>
        <th>Status</th>
      </tr>
    </thead>
    <tbody>
      <tr v-for="quote in quotesList" :key="quote.id">
        <td>{{ quote.quoteNumber }}</td>
        <td>{{ quote.createdAt }}</td>
        <td>{{ quote.expirationDate }}</td>
        <td>
          {{ quote.price.totalPrice }}
        </td>
        <td>
          {{ quote.stateMachineState.translated.name }}
        </td>
      </tr>
    </tbody>
  </table>
</template>
```

## Decline quote

The "Decline Quote" feature provides users with the ability to reject a quote that doesn't meet their requirements or expectations. By declining a quote, users can communicate their dissatisfaction with the proposed terms, prompting the sales team to review and potentially adjust the quote to better meet the user's needs. This feature ensures that the negotiation process is interactive and that the final agreement is satisfactory to both parties.

```vue
<script setup lang="ts">
import { ref } from "vue";
import { useB2bQuoteManagement } from "@shopware/composables";
const declineComment = ref("");
const quote = ref("example-id");
const { declineQuote } = useB2bQuoteManagement();
const handleDecline = async () => {
  declineQuote(quote.value.id, declineComment.value);
  declineComment.value = "";
};
</script>
<template>
  <form @submit.prevent="handleDecline">
    <textarea v-model="declineComment"> </textarea>
    <button>Decline</button>
  </form>
</template>
```

## Request change in quote

The "Request Change in Quote" feature empowers users to actively participate in the negotiation process. If a quote doesn't meet their expectations or requirements, users can request specific changes to the quote. This could involve adjustments to pricing, quantities, delivery terms, or product specifications. By requesting a change, users can ensure that the final agreement is tailored to their needs, fostering a more collaborative and satisfactory business relationship.

```vue
<script setup lang="ts">
import { ref } from "vue";
import { useB2bQuoteManagement } from "@shopware/composables";
const quote = ref("example-id");
const changeRequest = ref("");
const { requestChangeQuote } = useB2bQuoteManagement();
const handleChangeRequest = async () => {
  requestChangeQuote(quote.value.id, changeRequest.value);
  changeRequest.value = "";
};
</script>
<template>
  <form @submit.prevent="handleChangeRequest">
    <textarea v-model="changeRequest"> </textarea>
    <button type="submit">Send</button>
  </form>
</template>
```

## Change payment or shipping in quote

The "Change Payment or Shipping in Quote" feature provides users with the flexibility to modify the payment method or shipping details in a quote.

```vue
<script setup lang="ts">
import { ref } from "vue";
import { useB2bQuoteManagement } from "@shopware/composables";
const quote = ref("example-id");
const { changeShippingMethod, changePaymentMethod } = useB2bQuoteManagement();
changeShippingMethod(quote.value.id, "example-shipping-id");
changePaymentMethod(quote.value.id, "example-payment-id");
</script>
```

## Create an order from a quote

The "Create an Order from a Quote" feature allows users to seamlessly convert a negotiated quote into a formal order. Once a quote has been reviewed and agreed upon, users can use this feature to initiate the ordering process directly from the quote.

```vue
<script setup lang="ts">
import { ref } from "vue";
import { useB2bQuoteManagement } from "@shopware/composables";
const quote = ref("example-id");
const comment = ref("");
const { createOrderFromQuote } = useB2bQuoteManagement();
const handleCreateOrder = async () => {
  await createOrderFromQuote(quote.value.id, comment.value);
};
</script>
<template>
  <template>
    <form @submit.prevent="handleCreateOrder">
      <textarea v-model="comment"> </textarea>
      <button type="submit">Create order</button>
    </form>
  </template>
</template>
```

---

---
url: /frontends/integrations/commercial/b2b-quote-management.md
---

# B2B Quote Management

In this chapter you will learn how to

* Request new quote
* Fetch a list of quote and display detail
* Decline quote
* Request change in quote
* Change payment or shipping in quote
* Create a order from a quote

## Quick reference

* [useB2bQuoteManagement](../../packages/composables/useB2bQuoteManagement) is a composable used for a quote management

## Request new quote

The "Request New Quote" feature allows B2B users to request a custom quote for their current basket. This is particularly useful for large or complex orders where standard pricing may not apply, or special discounts may be negotiated.

This feature enhances the B2B shopping experience by providing flexibility in pricing and order customization. It also allows for direct communication between the buyer and seller, facilitating better negotiation and understanding of needs.

:::warning
Cart cannot be empty
:::

```vue
<script setup lang="ts">
import { ref } from "vue";
import { useCart, useB2bQuoteManagement } from "@shopware/composables";
const { cartItems } = useCart();
const { requestQuote } = UseB2bQuoteManagement();
const comment = ref("");
const handleRequestQuote = async () => {
  await requestQuote(comment.value);
};
</script>
<template>
  <textarea v-model="comment"> </textarea>
  <button :disabled="cartItems.length <= 0" @click="handleRequestQuote">
    Request quote
  </button>
</template>
```

## Fetch a list of quote and display detail

This feature allows users to retrieve a list of all their requested quotes or quotes created by the admin.

```vue
<script setup lang="ts">
import { ref, onBeforeMount } from "vue";
import { useB2bQuoteManagement } from "@shopware/composables";
const quotesList = ref([]);
const { getQuoteList } = useB2bQuoteManagement();
onBeforeMount(async () => {
  quotesList.value = await getQuoteList();
});
</script>
<template>
  <table>
    <thead>
      <tr>
        <th>Quote #</th>
        <th>Created at</th>
        <th>Valid until</th>
        <th>Grand total</th>
        <th>Status</th>
      </tr>
    </thead>
    <tbody>
      <tr v-for="quote in quotesList" :key="quote.id">
        <td>{{ quote.quoteNumber }}</td>
        <td>{{ quote.createdAt }}</td>
        <td>{{ quote.expirationDate }}</td>
        <td>
          {{ quote.price.totalPrice }}
        </td>
        <td>
          {{ quote.stateMachineState.translated.name }}
        </td>
      </tr>
    </tbody>
  </table>
</template>
```

## Decline quote

The "Decline Quote" feature provides users with the ability to reject a quote that doesn't meet their requirements or expectations. By declining a quote, users can communicate their dissatisfaction with the proposed terms, prompting the sales team to review and potentially adjust the quote to better meet the user's needs. This feature ensures that the negotiation process is interactive and that the final agreement is satisfactory to both parties.

```vue
<script setup lang="ts">
import { ref } from "vue";
import { useB2bQuoteManagement } from "@shopware/composables";
const declineComment = ref("");
const quote = ref("example-id");
const { declineQuote } = useB2bQuoteManagement();
const handleDecline = async () => {
  declineQuote(quote.value.id, declineComment.value);
  declineComment.value = "";
};
</script>
<template>
  <form @submit.prevent="handleDecline">
    <textarea v-model="declineComment"> </textarea>
    <button>Decline</button>
  </form>
</template>
```

## Request change in quote

The "Request Change in Quote" feature empowers users to actively participate in the negotiation process. If a quote doesn't meet their expectations or requirements, users can request specific changes to the quote. This could involve adjustments to pricing, quantities, delivery terms, or product specifications. By requesting a change, users can ensure that the final agreement is tailored to their needs, fostering a more collaborative and satisfactory business relationship.

```vue
<script setup lang="ts">
import { ref } from "vue";
import { useB2bQuoteManagement } from "@shopware/composables";
const quote = ref("example-id");
const changeRequest = ref("");
const { requestChangeQuote } = useB2bQuoteManagement();
const handleChangeRequest = async () => {
  requestChangeQuote(quote.value.id, changeRequest.value);
  changeRequest.value = "";
};
</script>
<template>
  <form @submit.prevent="handleChangeRequest">
    <textarea v-model="changeRequest"> </textarea>
    <button type="submit">Send</button>
  </form>
</template>
```

## Change payment or shipping in quote

The "Change Payment or Shipping in Quote" feature provides users with the flexibility to modify the payment method or shipping details in a quote.

```vue
<script setup lang="ts">
import { ref } from "vue";
import { useB2bQuoteManagement } from "@shopware/composables";
const quote = ref("example-id");
const { changeShippingMethod, changePaymentMethod } = useB2bQuoteManagement();
changeShippingMethod(quote.value.id, "example-shipping-id");
changePaymentMethod(quote.value.id, "example-payment-id");
</script>
```

## Create an order from a quote

The "Create an Order from a Quote" feature allows users to seamlessly convert a negotiated quote into a formal order. Once a quote has been reviewed and agreed upon, users can use this feature to initiate the ordering process directly from the quote.

```vue
<script setup lang="ts">
import { ref } from "vue";
import { useB2bQuoteManagement } from "@shopware/composables";
const quote = ref("example-id");
const comment = ref("");
const { createOrderFromQuote } = useB2bQuoteManagement();
const handleCreateOrder = async () => {
  await createOrderFromQuote(quote.value.id, comment.value);
};
</script>
<template>
  <template>
    <form @submit.prevent="handleCreateOrder">
      <textarea v-model="comment"> </textarea>
      <button type="submit">Create order</button>
    </form>
  </template>
</template>
```

---

---
url: >-
  /docs/products/extensions/b2b-components/employee-management/guides/b2b-roles.md
---

# B2B Roles

Roles can be used to bind multiple permission to employees with contexts. Every employee can have one assigned role. Based on that role and the containing permission, the employee will get access to certain information and functionalities.

The business partner has the opportunity to create a **default** role that will be selected by default, when creating a new employee.

---

---
url: >-
  /docs/v6.5/products/extensions/b2b-components/employee-management/guides/b2b-roles.md
---

# B2B Roles

Roles can be used to bind multiple permission to employees with contexts. Every employee can have one assigned role. Based on that role and the containing permission, the employee will get access to certain information and functionalities.

The business partner has the opportunity to create a “default” role that will be selected by default, when creating a new employee.

---

---
url: >-
  /docs/v6.6/products/extensions/b2b-components/employee-management/guides/b2b-roles.md
---

# B2B Roles

Roles can be used to bind multiple permission to employees with contexts. Every employee can have one assigned role. Based on that role and the containing permission, the employee will get access to certain information and functionalities.

The business partner has the opportunity to create a **default** role that will be selected by default, when creating a new employee.

---

---
url: /docs/products/extensions/b2b-suite.md
---

# B2B Suite

To build a robust B2B solution within the Shopware ecosystem, refer to this section which details every concept from scratch, including installation, system architecture, basic conventions, example plugins, Core, Administration, and Storefront component operations.

This section covers Shopware 6 related information on our B2B Suite. However, for information on Shopware 5, go through [B2B Suite Shopware 5 documentation](https://developers.shopware.com/shopware-enterprise/b2b-suite/).

---

---
url: /docs/v6.5/products/extensions/b2b-suite.md
---

# B2B Suite

To build a robust B2B solution within the Shopware ecosystem, refer to this section which details every concept from scratch, including installation, system architecture, basic conventions, example plugins, Core, Administration, and Storefront component operations.

This section covers Shopware 6 related information on our B2B Suite. However, for information on Shopware 5, go through [B2B Suite Shopware 5 documentation](https://devdocs.safefive.de/shopware-enterprise/b2b-suite/).

---

---
url: /docs/v6.6/products/extensions/b2b-suite.md
---

# B2B Suite

To build a robust B2B solution within the Shopware ecosystem, refer to this section which details every concept from scratch, including installation, system architecture, basic conventions, example plugins, Core, Administration, and Storefront component operations.
This section covers Shopware 6 related information on our B2B Suite. However, for information on Shopware 5, go through [B2B Suite Shopware 5 documentation](https://devdocs.safefive.de/shopware-enterprise/b2b-suite/).

---

---
url: /docs/products/extensions/b2b-suite-migration.md
---

# B2B Suite Migration

The B2B Suite Migration extension is designed to facilitate the migration of data from the B2B Suite to the B2B Components. This migration process is essential for merchants who want to transition from the legacy B2B Suite to the more modular and flexible B2B Components.

## Purpose

This section provides a comprehensive guide for developers to migrate data from B2B Suite to B2B Commercial. It covers the migration process, from high-level concepts to detailed execution and development instructions, ensuring a smooth and reliable transition. The content is structured into focused sections to help you understand, execute, and extend the migration process effectively.

::: warning
B2B Suite will no longer be supported starting Shopware 6.8. Plan your migration promptly to avoid disruptions.
:::

## Prerequisites

Please refer to the [B2B Suite Migration Prerequisites](./execution/prerequisites) section.

---

---
url: /docs/resources/guidelines/code/backward-compatibility.md
---

# Backward Compatibility

## Introduction

Shopware is a standard ecommerce solution used by many customers worldwide and is the technical foundation of their online business. As developers of Shopware, it is our highest goal to guarantee the reliability of the software for our customers. Always remember that every change you make can have a big impact on the life of our customers, either in a good way or in a bad way.

For the release strategy, Shopware uses a semantic [versioning](https://www.shopware.com/en/news/shopware-6-versioning-strategy/) and therefore has to be always backward compatible for minor and patch updates. This brings additional challenges when changing the code of Shopware. The following guide aims to provide you with the necessary workflows and techniques to do your changes in a backward compatible way and what to do if it is not possible.

## Annotations

During the development, different cases occur where you want to replace old code with new ones or even remove some obsolete code. As Shopware must always be backward compatible on minor and patch updates, old code should only be removed with a major release. Until the next major release, you want to mark the code with a corresponding annotation to inform other developers of the planned change. This overview shows the most important annotations and in which situation they must be used.

### @deprecated

```php
/**
 * @deprecated tag:v6.8.0 - Use NewFunction() instead
 */
```

The `@deprecated` annotation is used for obsolete public code, which will be removed with the next major release. The annotation always needs the specific major version tag, in which the code should be removed. Always add a meaningful comment with information about the corresponding replacement and how the deprecated code can be removed.

### @experimental

```php
/**
 * @experimental feature:FEATURE_FLAG stableVersion:v6.8.0
 */
```

The `@experimental` annotation is used for newly introduced code, which is not yet released. This ensures that it will not be treated as a public API until the corresponding feature is released and makes it possible to change the code in any way until the final release. Always add the name of the corresponding feature flag to the annotation so that it will not be forgotten when the corresponding feature is released.
The `@experimental` annotation should be treated like the default `@internal` annotation.
The mentioned  `stableVersion` tag is used to hint when the feature is planned to be stable.

## Workflows

### Backward-compatible features

When developing new features, the goal should always be to do this in a backward compatible way. This ensures that the feature can be shipped with a minor release to provide value for customers as soon as possible. The following table should help you to use the correct approach for each type of change.

| Case                   | During development                                                                                                                                                                                                                                                                         | On feature release                                                                                                                                       | Next major release                              |
|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------|-------------------------------------------------|
| 🚩 **Feature Flag**    | Hide code behind normal [feature flag](https://developer.shopware.com/docs/resources/references/adr/2020-08-10-feature-flag-system.html).                                                                                                                                                                                            | Remove the feature flag.                                                                                                                                 |                                                 |
| ➕ **New code**         | Add `@internal annotation` for new public API.                                                                                                                                                                                                                                             | Remove `@internal` annotation.                                                                                                                           |                                                 |
| ⚪ **Obsolete code**    | Add `@feature-deprecated` annotation.                                                                                                                                                                                                                                                      | Replace @feature-deprecated with normal `@deprecated` annotation.                                                                                        | Remove old code.                                |
| 🔴 **Breaking change** | Add `@major-deprecated` annotation. Hide breaking code behind additional major [feature flag](https://developer.shopware.com/docs/resources/references/adr/2020-08-10-feature-flag-system.html). Also, create a separate [changelog](https://developer.shopware.com/docs/resources/references/adr/2020-08-03-implement-new-changelog.html) for the change with the major flag. |                                                                                                                                                          | Remove old code. Remove the major feature flag. |
| 🔍 **Tests**           | Add new tests behind a feature flag.                                                                                                                                                                                                                                                       | Remove feature flags from new tests. Declare old tests as [legacy](https://symfony.com/doc/current/components/phpunit_bridge.html#mark-tests-as-legacy). | Remove legacy tests.                            |

You can also find more detailed information and code examples in the corresponding **[ADR](https://github.com/shopware/shopware/tree/trunk/adr)** for the deprecation strategy.

### Breaking Changes / Features

The first goal should always be to make your changes backward compatible. But there might be some special cases where it isn't possible in any way. In this case, the change can only be released with a major version. As we develop all changes in the same code base, the `trunk` branch, the changes have to stay behind a special feature flag, which is especially marked as a major feature flag.

| Case                    | During development                                                                                                                                           | Next major release (feature release) |
| ---                     | ---                                                                                                                                                          | ---                                  |
| 🚩 **Feature Flag**     | Hide code behind a major feature flag.                                                                                                                         | Remove major feature flag.           |
| ➕ **New code**         | Add `@internal` annotation for new public API.                                                                                                               | Remove `@internal` annotation.       |
| ⚪ **Obsolete code**    | Add `@major-deprecated` annotation.                                                                                                                          | Remove old code.                     |
| 🔴 **Breaking change**  | Add `@major-deprecated` annotation.                                                                                                                          | Remove old code.                     |
| 🔍 **Tests**            | Add new tests behind a major feature flag. Declare old tests as [legacy](https://symfony.com/doc/current/components/phpunit_bridge.html#mark-tests-as-legacy). | Remove legacy tests.                 |

## Compatibility sheet

To ensure backward compatibility, it is important to know what you are allowed to do and what not. The following sheet should give you an orientation on common changes and how they could affect the backward compatibility. Although a lot of effort went into this list, it is not guaranteed to be 100% complete. Always keep the persona of third-party developers in mind and challenge your changes against external needs.

### PHP

As Shopware is based on the PHP framework Symfony, we also have to make sure to use the rules which the framework follows. Besides the list below, always keep in mind the backward compatibility promise and implement your changes in a way the promise is kept.

**[Symfony Backward Compatibility Promise](https://symfony.com/doc/current/contributing/code/bc.html)**

| Use Case                                                                                                      | Allowed?   | Notes / Alternatives                                                                                                                                                                                                           |
| ---                                                                                                           | ---        | ---                                                                                                                                                                                                                            |
| Change the typehint of a class, interface or trait.                                                           | 🔴 NO      | Add the new typehint as an abstract class. Code Example: [Extend class with abstract class](#extend-class-with-abstract-class)                                                                                             |
| Change the constructor of a service.                                                                          | ✅ YES     | Services have to be instantiated over the container, so the changes should not break anything.                                                                                                                                 |
| Change the constructor of a class, that is not a service. (Instantiated with new Class())                     | ⚪ PARTIAL | Only optional arguments are allowed to be added and this should be made via `func_get_args()`.  Code Example: [Add an argument](#add-an-argument)                                                                            |
| Change the arguments of a public method.                                                                      | ⚪ PARTIAL | Only optional arguments are allowed to be added and this should be made via `func_get_args()`. Code Example: [Add an argument](#add-an-argument)                                                                             |
| Change the arguments of a protected method.                                                                   | ⚪ PARTIAL | Only optional arguments are allowed to be added and this should be made via `func_get_args()`. Code Example: [Add an argument](#add-an-argument)                                                                             |
| Change the arguments of a private method.                                                                     | ✅ YES     |                                                                                                                                                                                                                                |
| Change the return the type of a method.                                                                       | 🔴 NO      | Create a new method and deprecate the old one.                                                                                                                                                                                 |
| Change the value of a public constant.                                                                        | 🔴 NO      | You should add a new constant. Annotate the old constant as deprecated and remove it in the next major version.                                                                                                                |
| Change the value of a private constant.                                                                       | ✅ YES     | Check all potential usages of the constant. Maybe it is used somewhere to be stored in the database. In that case, you must write a migration for it which ensures every use of the constant in a db-value is updated as well. |
| Change a class or method to final.                                                                            | 🔴 NO      | You will have to deprecate the class or method and add an annotation that it will be final in the next major version.                                                                                                          |
| Change the visibility of a class, method or property from public to private/protected or protected to private | 🔴 NO      | Annotate it as deprecated and change the visibility in the next major version.                                                                                                                                                 |
| Change the namespace of a class.                                                                              | 🔴 NO      | Duplicate the class and mark the old one as deprecated.                                                                                                                                                                        |
| Change static state (remove static or delete static keyword).                                                 | 🔴 NO      | Annotate it as deprecated and add or remove the static keyword in the next major version.                                                                                                                                      |
| Add parameter to interface or abstract class function.                                                        | ⚪ PARTIAL | Only optional arguments are allowed to be added and this should be made via `func_get_args()`.  Code Example: [Add an argument](#add-an-argument)                                                                            |
| Add new public function to interface.                                                                         | 🔴 NO      |                                                                                                                                                                                                                                |
| Add new public function to abstract class.                                                                    | ⚪ PARTIAL | Only possible if the abstract class already contains the `getDecorated` call.  Code Example: [Add a public function](#add-a-public-function)                                                                                 |
| Add an event or event dispatch.                                                                               | ✅ YES     |                                                                                                                                                                                                                                |
| Add a constant.                                                                                               | ✅ YES     |                                                                                                                                                                                                                                |
| Remove an event or event dispatch.                                                                            | 🔴 NO      |                                                                                                                                                                                                                                |
| Remove a public property, constant or method.                                                                 | 🔴 NO      | Annotate it as deprecated and remove it in the next major release.                                                                                                                                                             |
| Remove a protected property, constant or method.                                                              | 🔴 NO      | Annotate it as deprecated and remove it in the next major release.                                                                                                                                                             |
| Remove a private property, constant, or method.                                                               | ✅ YES     |                                                                                                                                                                                                                                |

### Storefront

#### TWIG templates

| Use Case                                                           | Allowed?     | Notes / Alternatives                                                                                                                                                                                                                                                                |
| ---                                                                | ---          | ---                                                                                                                                                                                                                                                                                 |
| Removing TWIG blocks.                                              | 🔴 NO        | Use the deprecation workflow.Code Example: [Deprecate TWIG block](#deprecate-twig-block)                                                                                                                                                                                            |
| Renaming TWIG blocks.                                              | 🔴 NO        | Use the deprecation workflow. Create a new surrounding block with the new name and deprecate the old one. All variables which are defined in the scope of the old block must be moved to the new surrounding block scope.Code Example: [Rename TWIG block](#rename-twig-block) |
| Moving TWIG blocks within the same file.                           | ⚪ PARTIAL   | Only within the same scope/parent block.                                                                                                                                                                                                                                          |
| Removing TWIG variables.                                           | 🔴 NO        |                                                                                                                                                                                                                                                                                     |
| Renaming TWIG variables.                                           | 🔴 NO        | Create a new variable within the same scope and deprecate the old one.                                                                                                                                                                                                              |
| Changing the value of TWIG variables                               | ⚪ PARTIAL   | The data type has to stay the same. Otherwise, use the deprecation workflow.                                                                                                                                                                                                         |
| Moving TWIG variable definitions to other TWIG blocks.             | ⚪ PARTIAL   | Only when they are being moved higher up in the block scope.                                                                                                                                                                                                                        |
| Adding TWIG blocks that affect the scope of variable definitions. | 🔴 NO        |                                                                                                                                                                                                                                                                                     |
| Moving template files to other directories.                        | 🔴 NO        |                                                                                                                                                                                                                                                                                     |

#### HTML

| Use Case                                   | Allowed?   | Notes / Alternatives                                                                              |
| ---                                        | ---        | ---                                                                                               |
| Removing HTML sections.                    | 🔴 NO      |                                                                                                   |
| Moving HTML sections within the same file. | ⚪ PARTIAL | Only within the same TWIG Block.                                                                  |
| Renaming of removing CSS selectors.        | 🔴 NO      | Use the deprecation workflow.Code Example: [Deprecate CSS selectors](#deprecate-css-selectors) |

#### JavaScript

| Use Case                                           | Allowed? | Notes / Alternatives                                                                                                  |
| ---                                                | ---      | ---                                                                                                                   |
| Renaming or removing JS services.                  | 🔴 NO    | Use the deprecation workflow.Code Example: [Renaming or removing JS services](#renaming-or-removing-js-services)  |
| Renaming or removing JS plugins.                | 🔴 NO    | Use the deprecation workflow.Code Example: [Renaming or removing JS plugins](#renaming-or-removing-js-plugins) |
| Changing the public API of a JS plugin or service. | 🔴 NO    | Use the deprecation workflow.Code Example: [Add new public function](#add-new-public-function)                    |
| Renaming methods of JS plugins or services.        | 🔴 NO    | Use the deprecation workflow.Code Example: [Rename a method](#rename-a-method)                                    |
| Renaming or removing of JS events.                 | 🔴 NO    |                                                                                                                       |
| Changing the parameters of JS events.              | 🔴 NO    |                                                                                                                       |

#### Styling / CSS

| Use Case                                                  | Allowed?   | Notes / Alternatives                                                                                                                                                                                                                       |
| ---                                                       | ---        | ---                                                                                                                                                                                                                                        |
| Renaming or removing CSS definitions.                     | ⚪ PARTIAL | Only CSS properties that have a visual effect but no structure or functional CSS properties. Not allowed are: `display`, `position`, `visibility`, `z-index`, `pointer-events`, `overflow`, `transform`                              |
| Changing generic selectors of the Bootstrap framework.    | ⚪ PARTIAL | Be aware of what you are doing. Fixing a small styling issue might be ok. Changing structural properties might have a big impact on the layout and functionality.                                                                      |
| Changing the CSS properties of generic Bootstrap classes. | ⚪ PARTIAL | Be aware of what you are doing. Fixing a small styling issue might be ok. Changing structural properties might have a big impact on the layout and functionality.                                                                      |
| Renaming or removing SASS variables or mixins.            | 🔴 NO      |                                                                                                                                                                                                                                            |
| Renaming or removing standard theme variables.         | 🔴 NO      |                                                                                                                                                                                                                                            |

### Administration

#### Component Templates

| Use Case                                                                        | Allowed?   | Notes / Alternatives                                                                     |
| ---                                                                             | ---        | ---                                                                                      |
| Renaming or removing TWIG blocks.                                               | 🔴 NO      | Use the deprecation workflow.Code Example: [Deprecate TWIG block](#deprecate-twig-block) |
| Moving TWIG blocks within the same file.                                        | ⚪ PARTIAL | Only within the same scope/parent block.                                               |
| Changing the "ref" attribute of elements.                                       | 🔴 NO      |                                                                                          |
| Changing VueJS specific template functions, like v-if.                          | 🔴 NO      |                                                                                          |
| Changing VueJS data functions, like v-model, or v-bind.                         | 🔴 NO      |                                                                                          |
| Renaming or removing VueJS slots.                                               | 🔴 NO      | Use the deprecation workflow.Code Example: [Deprecate Vue Slot](#deprecate-vue-slot) |
| Using new functionality of the VueJS framework, which has a breaking behavior. | 🔴 NO      |                                                                                          |
| Renaming or removing global available VueJS template functions.              | 🔴 NO      |                                                                                          |

#### JavaScript Modules & Components

| Use Case                                                     | Allowed?   | Notes / Alternatives                                                                                                                                                                                                                        |
|---                                                           | ---        | ---                                                                                                                                                                                                                                         |
| Renaming or removing base components.                     | 🔴 NO      | Use the deprecation workflow.Code Example: [Deprecate admin components](#deprecate-admin-components)                                                                                                                                    |
| Renaming or removing module components.                   | 🔴 NO      | Use the deprecation workflow.Code Example: [Deprecate admin components](#deprecate-admin-components)                                                                                                                                    |
| Renaming or removing methods                                 | 🔴 NO      | Use the deprecation workflow.Code Example: [Rename a method](#rename-a-method)                                                                                                                                                          |
| Changing the return value of a method                        | 🔴 NO      | Use the deprecation workflow.Code Example: [Add new public function](#add-new-public-function)                                                                                                                                          |
| Changing the parameters of a method                          | 🔴 NO      | Only with new optional parameters with a default value or if the method uses a single object as a parameter via destructuring. Otherwise, use the deprecation workflow.Code Example: [Add new public function](#add-new-public-function) |
| Renaming or removing of required props                       | 🔴 NO      | Use the deprecation workflow.Code Example: [Deprecate properties](#deprecate-admin-component-properties)                                                                                                                                |
| Renaming or removing of vue events                           | 🔴 NO      | Use the deprecation workflow.Add a deprecation annotation to the event which needs to be renamed or removed and offer an alternative inside the deprecation comment when possible                                                       |
| Changing the parameters of a vue event                       | ⚪ PARTIAL | Only with new optional parameters with a default value. Only when the method receives an object as a parameter and when working with destructuring                                                             |
| Adding required properties to components.                    | 🔴 NO      | Add the property as optional property and show a warning if the property is empty. This could be done on component creation or with a property validator.Code Example: [Adding required properties to components](#adding-required-properties-to-components) |
| Renaming or removing data that is used in the data binding. | 🔴 NO      |                                                                                                                                                                                                                                             |
| Renaming or removing the routes of a module.                 | 🔴 NO      |                                                                                                                                                                                                                                             |
| Changing the parameters of a route.                          | 🔴 NO      |                                                                                                                                                                                                                                             |
| Adding required parameters to a route.                       | 🔴 NO      |                                                                                                                                                                                                                                             |
| Changing the public API of the global "Shopware" object.     | 🔴 NO      | Use the deprecation workflow. Use the same workflow as for other methods.Code Example: [Rename a method](#rename-a-method)                                                                                                                  |
| Changing the public API of state stores. (VueX)              | 🔴 NO      |                                                                                                                                                                                                                                             |
| Renaming, removing, or not-using of assets or other imports.  | 🔴 NO      |                                                                                                                                                                                                                                             |

#### Component Styling

| Use Case                                                    | Allowed?   | Notes / Alternatives                                                                                                                                                                                                                                        |
| ---                                                         | ---        | ---                                                                                                                                                                                                                                                         |
| Renaming or removing CSS definitions.                       | ⚪ PARTIAL | Only CSS properties that have a visual effect but no structure or functional CSS properties. Not allowed are: `display`, `position`, `visibility`, `z-index`, `pointer-events`, `overflow`, `transform`                                               |
| Renaming or removing functional selectors, like `is--*`. | 🔴 NO      |                                                                                                                                                                                                                                                             |
| Renaming or removing root CSS selectors.                    | 🔴 NO      |                                                                                                                                                                                                                                                             |

### Feature Flags

Feature flags itself, mainly the name and existence of the feature flag itself, are part of the backward compatibility promise.
Which means feature flags won't be removed in a minor version and will be deprecated instead.

However, the behavior behind the feature flag might change at any time, this might include the complete removal of the feature behind the flag, or the use of a new flag to toggle the behaviour.
In these cases the old feature flag will still be registered, so checks for that feature flag won't throw any error, but the feature flag itself will do nothing.

This allows for easier compatibility across different versions in plugins, as the feature flag checks can stay in the plugin code.
All changes to the functionality behind the feature flag will be documented in the release notes.

## Code Examples

### PHP

#### Extend a class with an abstract class

```php
/** Before */
class MailService implements MailServiceInterface

/** After */
class MailService extends AbstractMailService
class AbstractMailService implements MailServiceInterface
```

#### Add an argument

```php
/**
 * @deprecated tag:v6.5.0 - Parameter $precision will be mandatory in future implementation
 */
public function calculate(ProductEntity $product, Context $context /*, int $precision */): Product
{
   if (Feature::isActive('v6.5.0.0')) {
      if (\func_num_args() === 3) {
         $precision = func_get_arg(2);
         // Do new calculation
      } else {
         Feature::triggerDeprecationOrThrow(
            'v6.5.0.0',
            'The parameter $precision will be mandatory in future implementation.'
         );
      }
   } else {
      // Do old calculation
   }
}
```

#### Add a public function

```php
/** Before */
abstract class AbstractProductRoute
{
    abstract public function getDecorated(): AbstractProductRoute;

    abstract public function load();
}


/** After */
abstract class AbstractProductRoute
{
    abstract public function getDecorated(): AbstractProductRoute;

    abstract public function load();

    /**
     * @deprecated tag:v6.5.0 - Will be abstract
     */
    public function loadV2()
    {
        return $this->getDecorated()->loadV2();
    }
}
```

### TWIG & HTML

#### Deprecate TWIG block

**Storefront**: Use the `deprecated` tag from TWIG, including a comment with the normal annotation.

```html
{% block the_block_name %}
    {% deprecated '@deprecated tag:v6.5.0 - Block will be removed completely including the content' %}
    <div>Content</div>
{% endblock %}
```

**Administration**: Use normal TWIG comments for the annotation, as the other syntax is not supported.

```html
{% block the_block_name %}
    {# @deprecated tag:v6.5.0 - Block will be removed completely including the content #}
    <div>Content</div>
{% endblock %}
```

#### Rename TWIG block

```html
{% block new_block_name %}
    {% block old_block_name %}
    {% deprecated '@deprecated tag:v6.5.0 - Use `new_block_name` instead' %}
        <div>Content</div>
    {% endblock %}
{% endblock %}
```

#### Deprecate CSS selectors

```html
{# @deprecated tag:v6.5.0 - CSS class "card-primary" is deprecated, use "card-major" instead #}
<div class="card card-major card-primary">
    ...
</div>
```

#### Deprecate Vue Slot

```html
{# @deprecated tag:v6.5.0 - Use slot "main-content" instead #}
<slot name="content"></slot>
<slot name="main-content"></slot>
```

### JavaScript

#### Add new public function

```javascript
// route.service.js
export default class RouteService {
    /**
     * @deprecated tag:v6.5.0 - Use getRouteConfig() instead
     */
    getRoute(symfonyRoute) {
        // Returns string 'foo/bar'
        return this._someMagic(symfonyRoute);
    }

    getRouteConfig() {
        // Returns object { name: 'foo/bar', params: [] }
        return {
            url: this._someMagic(symfonyRoute).url,
            params: this._someMagic(symfonyRoute).params
        }
    }
}
```

#### Rename a method

```javascript
/**
 * @deprecated tag:v6.5.0 - Use onItemClick() instead
 */
onClick(event) {
    return onItemClick(event);
},

onItemClick(event) {
    // ...
}
```

#### Deprecate admin components

```javascript
/**
 * @deprecated tag:v6.5.0 - Use sw-new instead
 * @status deprecated
 */
Shopware.Component.register('sw-old', {
    deprecated: '6.5.0'
});
```

#### Deprecate admin component properties

```json
{
    name: 'example-component',
    props: {
        /** @deprecated tag:v6.5.0 - Insert additional information in comments */
        exampleProp: {
            type: String,
            required: false,
            default: 'Default value',
            deprecated: {
                version: '6.5.0',
                comment: 'Insert additional information in comments'
            }
        }
    }
}
```

#### Adding required properties to components

```javascript
{
    createdComponent() {
        /** @deprecated tag:v6.5.0 - Warning will be removed when prop is required */
        if (!this.newProp) {
            debug.warn(
                'sw-example-component',
                '"newProp" will be required in tag:v6.5.0'
            );
        }
    }
}
```

#### Renaming or removing JS services

```javascript
// http-client.service.js
/**
* @deprecated tag:v6.5.0 - Use NewHttpClient instead (new-http-client.service.js)
*/
export default class HttpClient {
    // ...
}

// new-http-client.service.js
export default class NewHttpClient {
    // ...
}
```

#### Renaming or removing JS plugins

```javascript
// buy-button.plugin.js
/**
* @deprecated tag:v6.5.0 - Use NewBuyButtonPlugin instead (new-buy-button.plugin.js)
*/
export default class BuyButtonPlugin extends Plugin {
    // ...
}

// new-buy-button.plugin.js
export default class NewBuyButtonPlugin extends Plugin {
    // ...
}
```

---

---
url: /docs/v6.5/resources/guidelines/code/backward-compatibility.md
---

# Backward Compatibility

## Introduction

Shopware is a standard ecommerce solution used by many customers worldwide and is the technical foundation of their online business. As developers of Shopware, it is our highest goal to guarantee the reliability of the software for our customers. Always remember that every change you make can have a big impact on the life of our customers, either in a good way or in a bad way.

For the release strategy, Shopware uses a semantic [versioning](https://www.shopware.com/en/news/shopware-6-versioning-strategy/) and therefore has to be always backward compatible for minor and patch updates. This brings additional challenges when changing the code of Shopware. The following guide aims to provide you with the necessary workflows and techniques to do your changes in a backward compatible way and what to do if it is not possible.

## Annotations

During the development, different cases occur where you want to replace old code with new ones or even remove some obsolete code. As Shopware must always be backward compatible on minor and patch updates, old code should only be removed with a major release. Until the next major release, you want to mark the code with a corresponding annotation to inform other developers of the planned change. This overview shows the most important annotations and in which situation they must be used.

### @deprecated

```php
/**
 * @deprecated tag:v6.5.0 - Use NewFunction() instead
 */
```

The `@deprecated` annotation is used for obsolete public code, which will be removed with the next major release. The annotation always needs the specific major version tag, in which the code should be removed. Always add a meaningful comment with information about the corresponding replacement and how the deprecated code can be removed.

### @feature-deprecated

```php
/**
 * @feature-deprecated (flag:FEATURE_NEXT_11111)
 */
```

The `@feature-deprecated` annotation is used for obsolete code during the development of a feature when the code is still hidden behind a feature flag. This is important so that code that is not public will not trigger deprecation warnings. This annotation has to be changed to the correct `@deprecated` annotation when the feature is released, and the corresponding feature flag is removed. Always add the name of the corresponding feature flag to the annotation so that it will not be forgotten when the flag is removed.

### @major-deprecated

```php
/**
 * @major-deprecated (flag:FEATURE_NEXT_22222)
 */
```

The `@major-deprecated` annotation is used for breaking code which has to stay behind a specific major feature flag until the next major release. Always add the name of the corresponding feature flag to the annotation so that it will not be forgotten when the flag is removed.

### @internal

```php
/**
 * @internal (flag:FEATURE_NEXT_11111)
 */
```

In combination with a feature flag, like shown above, the `@internal` annotation is used for newly introduced code, which is not yet released. This ensures that it will not be treated as a public API until the corresponding feature is released and makes it possible to change the code in any way until the final release. Always add the name of the corresponding feature flag to the annotation so that it will not be forgotten when the corresponding feature is released.

## Workflows

### Backward compatible features

When developing new features, the goal should always be to do this in a backward compatible way. This ensures that the feature can be shipped with a minor release to provide value for customers as soon as possible. The following table should help you to use the correct approach for each type of change.

| Case                    | During development                                                                                                                                                                                                                                                                                                                                       | On feature release                                                                                                                                       | Next major release                          |
| ---                     | ---                                                                                                                                                                                                                                                                                                                                                      | ---                                                                                                                                                      | ---                                         |
| 🚩 **Feature Flag**     | Hide code behind normal [feature flag](../../references/adr/2020-08-10-feature-flag-system.md).                                                                                                                                                                                                                                                                                            | Remove the feature flag.                                                                                                                                     |                                             |
| ➕ **New code**         | Add `@internal annotation` for new public API.                                                                                                                                                                                                                                                                                                           | Remove `@internal` annotation.                                                                                                                           |                                             |
| ⚪ **Obsolete code**    | Add `@feature-deprecated` annotation.                                                                                                                                                                                                                                                                                                                    | Replace @feature-deprecated with normal `@deprecated` annotation.                                                                                        | Remove old code.                            |
| 🔴 **Breaking change**  | Add `@major-deprecated` annotation. Hide breaking code behind additional major [feature flag](../../references/adr/2020-08-10-feature-flag-system.md). Also, create a separate [changelog](../../references/adr/2020-08-03-implement-new-changelog.md) for the change with the major flag. |                                                                                                                                                          | Remove old code. Remove the major feature flag. |
| 🔍 **Tests**            | Add new tests behind a feature flag.                                                                                                                                                                                                                                                                                                                       | Remove feature flags from new tests. Declare old tests as [legacy](https://symfony.com/doc/current/components/phpunit_bridge.html#mark-tests-as-legacy). | Remove legacy tests.                        |

You can also find more detailed information and code examples in the corresponding **[ADR](https://github.com/shopware/shopware/blob/trunk/adr/)** for the deprecation strategy.

### Breaking Changes / Features

The first goal should always be to make your changes backward compatible. But there might be some special cases where it isn't possible in any way. In this case, the change can only be released with a major version. As we develop all changes in the same code base, the `trunk` branch, the changes have to stay behind a special feature flag, which is especially marked as a major feature flag.

| Case                    | During development                                                                                                                                           | Next major release (feature release) |
| ---                     | ---                                                                                                                                                          | ---                                  |
| 🚩 **Feature Flag**     | Hide code behind a major feature flag.                                                                                                                         | Remove major feature flag.           |
| ➕ **New code**         | Add `@internal` annotation for new public API.                                                                                                               | Remove `@internal` annotation.       |
| ⚪ **Obsolete code**    | Add `@major-deprecated` annotation.                                                                                                                          | Remove old code.                     |
| 🔴 **Breaking change**  | Add `@major-deprecated` annotation.                                                                                                                          | Remove old code.                     |
| 🔍 **Tests**            | Add new tests behind a major feature flag. Declare old tests as [legacy](https://symfony.com/doc/current/components/phpunit_bridge.html#mark-tests-as-legacy). | Remove legacy tests.                 |

## Compatibility sheet

To ensure backward compatibility, it is important to know what you are allowed to do and what not. The following sheet should give you an orientation on common changes and how they could affect the backward compatibility. Although a lot of effort went into this list, it is not guaranteed to be 100% complete. Always keep the persona of third-party developers in mind and challenge your changes against external needs.

### PHP

As Shopware is based on the PHP framework Symfony, we also have to make sure to use the rules which the framework follows. Besides the list below, always keep in mind the backward compatibility promise and implement your changes in a way the promise is kept.

**[Symfony Backward Compatibility Promise](https://symfony.com/doc/current/contributing/code/bc.html)**

| Use Case                                                                                                      | Allowed?   | Notes / Alternatives                                                                                                                                                                                                           |
| ---                                                                                                           | ---        | ---                                                                                                                                                                                                                            |
| Change the typehint of a class, interface or trait.                                                           | 🔴 NO      | Add the new typehint as an abstract class. Code Example: [Extend class with abstract class](#extend-class-with-abstract-class)                                                                                             |
| Change the constructor of a service.                                                                          | ✅ YES     | Services have to be instantiated over the container, so the changes should not break anything.                                                                                                                                 |
| Change the constructor of a class, that is not a service. (Instantiated with new Class())                     | ⚪ PARTIAL | Only optional arguments are allowed to be added and this should be made via `func_get_args()`.  Code Example: [Add an argument](#add-an-argument)                                                                            |
| Change the arguments of a public method.                                                                      | ⚪ PARTIAL | Only optional arguments are allowed to be added and this should be made via `func_get_args()`. Code Example: [Add an argument](#add-an-argument)                                                                             |
| Change the arguments of a protected method.                                                                   | ⚪ PARTIAL | Only optional arguments are allowed to be added and this should be made via `func_get_args()`. Code Example: [Add an argument](#add-an-argument)                                                                             |
| Change the arguments of a private method.                                                                     | ✅ YES     |                                                                                                                                                                                                                                |
| Change the return the type of a method.                                                                       | 🔴 NO      | Create a new method and deprecate the old one.                                                                                                                                                                                 |
| Change the value of a public constant.                                                                        | 🔴 NO      | You should add a new constant. Annotate the old constant as deprecated and remove it in the next major version.                                                                                                                |
| Change the value of a private constant.                                                                       | ✅ YES     | Check all potential usages of the constant. Maybe it is used somewhere to be stored in the database. In that case, you must write a migration for it which ensures every use of the constant in a db-value is updated as well. |
| Change a class or method to final.                                                                            | 🔴 NO      | You will have to deprecate the class or method and add an annotation that it will be final in the next major version.                                                                                                          |
| Change the visibility of a class, method or property from public to private/protected or protected to private | 🔴 NO      | Annotate it as deprecated and change the visibility in the next major version.                                                                                                                                                 |
| Change the namespace of a class.                                                                              | 🔴 NO      | Duplicate the class and mark the old one as deprecated.                                                                                                                                                                        |
| Change static state (remove static or delete static keyword).                                                 | 🔴 NO      | Annotate it as deprecated and add or remove the static keyword in the next major version.                                                                                                                                      |
| Add parameter to interface or abstract class function.                                                        | ⚪ PARTIAL | Only optional arguments are allowed to be added and this should be made via `func_get_args()`.  Code Example: [Add an argument](#add-an-argument)                                                                            |
| Add new public function to interface.                                                                         | 🔴 NO      |                                                                                                                                                                                                                                |
| Add new public function to abstract class.                                                                    | ⚪ PARTIAL | Only possible if the abstract class already contains the `getDecorated` call.  Code Example: [Add a public function](#add-a-public-function)                                                                                 |
| Add an event or event dispatch.                                                                               | ✅ YES     |                                                                                                                                                                                                                                |
| Add a constant.                                                                                               | ✅ YES     |                                                                                                                                                                                                                                |
| Remove an event or event dispatch.                                                                            | 🔴 NO      |                                                                                                                                                                                                                                |
| Remove a public property, constant or method.                                                                 | 🔴 NO      | Annotate it as deprecated and remove it in the next major release.                                                                                                                                                             |
| Remove a protected property, constant or method.                                                              | 🔴 NO      | Annotate it as deprecated and remove it in the next major release.                                                                                                                                                             |
| Remove a private property, constant, or method.                                                               | ✅ YES     |                                                                                                                                                                                                                                |

### Storefront

#### TWIG templates

| Use Case                                                           | Allowed?     | Notes / Alternatives                                                                                                                                                                                                                                                                |
| ---                                                                | ---          | ---                                                                                                                                                                                                                                                                                 |
| Removing TWIG blocks.                                              | 🔴 NO        | Use the deprecation workflow.Code Example: [Deprecate TWIG block](#deprecate-twig-block)                                                                                                                                                                                            |
| Renaming TWIG blocks.                                              | 🔴 NO        | Use the deprecation workflow. Create a new surrounding block with the new name and deprecate the old one. All variables which are defined in the scope of the old block must be moved to the new surrounding block scope.Code Example: [Rename TWIG block](#rename-twig-block) |
| Moving TWIG blocks within the same file.                           | ⚪ PARTIAL   | Only within the same scope/parent block.                                                                                                                                                                                                                                          |
| Removing TWIG variables.                                           | 🔴 NO        |                                                                                                                                                                                                                                                                                     |
| Renaming TWIG variables.                                           | 🔴 NO        | Create a new variable within the same scope and deprecate the old one.                                                                                                                                                                                                              |
| Changing the value of TWIG variables                               | ⚪ PARTIAL   | The data type has to stay the same. Otherwise, use the deprecation workflow.                                                                                                                                                                                                         |
| Moving TWIG variable definitions to other TWIG blocks.             | ⚪ PARTIAL   | Only when they are being moved higher up in the block scope.                                                                                                                                                                                                                        |
| Adding TWIG blocks that affect the scope of variable definitions. | 🔴 NO        |                                                                                                                                                                                                                                                                                     |
| Moving template files to other directories.                        | 🔴 NO        |                                                                                                                                                                                                                                                                                     |

#### HTML

| Use Case                                   | Allowed?   | Notes / Alternatives                                                                              |
| ---                                        | ---        | ---                                                                                               |
| Removing HTML sections.                    | 🔴 NO      |                                                                                                   |
| Moving HTML sections within the same file. | ⚪ PARTIAL | Only within the same TWIG Block.                                                                  |
| Renaming of removing CSS selectors.        | 🔴 NO      | Use the deprecation workflow.Code Example: [Deprecate CSS selectors](#deprecate-css-selectors) |

#### JavaScript

| Use Case                                           | Allowed? | Notes / Alternatives                                                                                                  |
| ---                                                | ---      | ---                                                                                                                   |
| Renaming or removing JS services.                  | 🔴 NO    | Use the deprecation workflow.Code Example: [Renaming or removing JS services](#renaming-or-removing-js-services)  |
| Renaming or removing JS plugins.                | 🔴 NO    | Use the deprecation workflow.Code Example: [Renaming or removing JS plugins](#renaming-or-removing-js-plugins) |
| Changing the public API of a JS plugin or service. | 🔴 NO    | Use the deprecation workflow.Code Example: [Add new public function](#add-new-public-function)                    |
| Renaming methods of JS plugins or services.        | 🔴 NO    | Use the deprecation workflow.Code Example: [Rename a method](#rename-a-method)                                    |
| Renaming or removing of JS events.                 | 🔴 NO    |                                                                                                                       |
| Changing the parameters of JS events.              | 🔴 NO    |                                                                                                                       |

#### Styling / CSS

| Use Case                                                  | Allowed?   | Notes / Alternatives                                                                                                                                                                                                                       |
| ---                                                       | ---        | ---                                                                                                                                                                                                                                        |
| Renaming or removing CSS definitions.                     | ⚪ PARTIAL | Only CSS properties that have a visual effect but no structure or functional CSS properties. Not allowed are: `display`, `position`, `visibility`, `z-index`, `pointer-events`, `overflow`, `transform`                              |
| Changing generic selectors of the Bootstrap framework.    | ⚪ PARTIAL | Be aware of what you are doing. Fixing a small styling issue might be ok. Changing structural properties might have a big impact on the layout and functionality.                                                                      |
| Changing the CSS properties of generic Bootstrap classes. | ⚪ PARTIAL | Be aware of what you are doing. Fixing a small styling issue might be ok. Changing structural properties might have a big impact on the layout and functionality.                                                                      |
| Renaming or removing SASS variables or mixins.            | 🔴 NO      |                                                                                                                                                                                                                                            |
| Renaming or removing standard theme variables.         | 🔴 NO      |                                                                                                                                                                                                                                            |

### Administration

#### Component Templates

| Use Case                                                                        | Allowed?   | Notes / Alternatives                                                                     |
| ---                                                                             | ---        | ---                                                                                      |
| Renaming or removing TWIG blocks.                                               | 🔴 NO      | Use the deprecation workflow.Code Example: [Deprecate TWIG block](#deprecate-twig-block) |
| Moving TWIG blocks within the same file.                                        | ⚪ PARTIAL | Only within the same scope/parent block.                                               |
| Changing the "ref" attribute of elements.                                       | 🔴 NO      |                                                                                          |
| Changing VueJS specific template functions, like v-if.                          | 🔴 NO      |                                                                                          |
| Changing VueJS data functions, like v-model, or v-bind.                         | 🔴 NO      |                                                                                          |
| Renaming or removing VueJS slots.                                               | 🔴 NO      | Use the deprecation workflow.Code Example: [Deprecate Vue Slot](#deprecate-vue-slot) |
| Using new functionality of the VueJS framework, which has a breaking behavior. | 🔴 NO      |                                                                                          |
| Renaming or removing global available VueJS template functions.              | 🔴 NO      |                                                                                          |

#### JavaScript Modules & Components

| Use Case                                                     | Allowed?   | Notes / Alternatives                                                                                                                                                                                                                        |
|---                                                           | ---        | ---                                                                                                                                                                                                                                         |
| Renaming or removing base components.                     | 🔴 NO      | Use the deprecation workflow.Code Example: [Deprecate admin components](#deprecate-admin-components)                                                                                                                                    |
| Renaming or removing module components.                   | 🔴 NO      | Use the deprecation workflow.Code Example: [Deprecate admin components](#deprecate-admin-components)                                                                                                                                    |
| Renaming or removing methods                                 | 🔴 NO      | Use the deprecation workflow.Code Example: [Rename a method](#rename-a-method)                                                                                                                                                          |
| Changing the return value of a method                        | 🔴 NO      | Use the deprecation workflow.Code Example: [Add new public function](#add-new-public-function)                                                                                                                                          |
| Changing the parameters of a method                          | 🔴 NO      | Only with new optional parameters with a default value or if the method uses a single object as a parameter via destructuring. Otherwise, use the deprecation workflow.Code Example: [Add new public function](#add-new-public-function) |
| Renaming or removing of required props                       | 🔴 NO      | Use the deprecation workflow.Code Example: [Deprecate properties](#deprecate-admin-component-properties)                                                                                                                                |
| Renaming or removing of vue events                           | 🔴 NO      | Use the deprecation workflow.Add a deprecation annotation to the event which needs to be renamed or removed and offer an alternative inside the deprecation comment when possible                                                       |
| Changing the parameters of a vue event                       | ⚪ PARTIAL | Only with new optional parameters with a default value. Only when the method receives an object as a parameter and when working with destructuring                                                             |
| Adding required properties to components.                    | 🔴 NO      | Add the property as optional property and show a warning if the property is empty. This could be done on component creation or with a property validator.Code Example: [Adding required properties to components](#adding-required-properties-to-components) |
| Renaming or removing data that is used in the data binding. | 🔴 NO      |                                                                                                                                                                                                                                             |
| Renaming or removing the routes of a module.                 | 🔴 NO      |                                                                                                                                                                                                                                             |
| Changing the parameters of a route.                          | 🔴 NO      |                                                                                                                                                                                                                                             |
| Adding required parameters to a route.                       | 🔴 NO      |                                                                                                                                                                                                                                             |
| Changing the public API of the global "Shopware" object.     | 🔴 NO      | Use the deprecation workflow. Use the same workflow as for other methods.Code Example: [Rename a method](#rename-a-method)                                                                                                                  |
| Changing the public API of state stores. (VueX)              | 🔴 NO      |                                                                                                                                                                                                                                             |
| Renaming, removing, or not-using of assets or other imports.  | 🔴 NO      |                                                                                                                                                                                                                                             |

#### Component Styling

| Use Case                                                    | Allowed?   | Notes / Alternatives                                                                                                                                                                                                                                        |
| ---                                                         | ---        | ---                                                                                                                                                                                                                                                         |
| Renaming or removing CSS definitions.                       | ⚪ PARTIAL | Only CSS properties that have a visual effect but no structure or functional CSS properties. Not allowed are: `display`, `position`, `visibility`, `z-index`, `pointer-events`, `overflow`, `transform`                                               |
| Renaming or removing functional selectors, like `is--*`. | 🔴 NO      |                                                                                                                                                                                                                                                             |
| Renaming or removing root CSS selectors.                    | 🔴 NO      |                                                                                                                                                                                                                                                             |

## Code Examples

### PHP

#### Extend class with abstract class

```php
/** Before */
class MailService implements MailServiceInterface
 
/** After */
class MailService extends AbstractMailService
class AbstractMailService implements MailServiceInterface
```

#### Add an argument

```php
/**
 * @feature-deprecated tag:v6.5.0 (flag:FEATURE_NEXT_22222)
 * Parameter $precision will be mandatory in future implementation
 */
public function calculate(ProductEntity $product, Context $context /*, int $precision */): Product
{
   if (Feature::isActive('FEATURE_NEXT_22222')) {
      if (\func_num_args() === 3) {
         $precision = func_get_arg(2);
         // Do new calculation
      } else {
         throw new InvalidArgumentException('Argument 3 $precision is required with feature FEATURE_NEXT_22222');
      }
   } else {
      // Do old calculation
   }
}
```

#### Add a public function

```php
/** Before */
abstract class AbstractProductRoute
{
    abstract public function getDecorated(): AbstractProductRoute;
 
    abstract public function load();
}
 
 
/** After */
abstract class AbstractProductRoute
{
    abstract public function getDecorated(): AbstractProductRoute;
 
    abstract public function load();
 
    /**
     * @deprecated tag:v6.5.0 - Will be abstract 
     */
    public function loadV2()
    {
        return $this->getDecorated()->loadV2();
    }
}
```

### TWIG & HTML

#### Deprecate TWIG block

**Storefront**: Use the `deprecated` tag from TWIG, including a comment with the normal annotation.

```html
{% block the_block_name %}
    {% deprecated '@deprecated tag:v6.5.0 - Block will be removed completely including the content' %}
    <div>Content</div>
{% endblock %}
```

**Administration**: Use normal TWIG comments for the annotation, as the other syntax is not supported.

```html
{% block the_block_name %}
    {# @deprecated tag:v6.5.0 - Block will be removed completely including the content #}
    <div>Content</div>
{% endblock %}
```

#### Rename TWIG block

```html
{% block new_block_name %}
    {% block old_block_name %}
    {% deprecated '@deprecated tag:v6.5.0 - Use `new_block_name` instead' %}
        <div>Content</div>
    {% endblock %}
{% endblock %}
```

#### Deprecate CSS selectors

```html
{# @deprecated tag:v6.5.0 - CSS class "card-primary" is deprecated, use "card-major" instead #}
<div class="card card-major card-primary">
    ...
</div>
```

#### Deprecate Vue Slot

```html
{# @deprecated tag:v6.5.0 - Use slot "main-content" instead #}
<slot name="content"></slot>
<slot name="main-content"></slot>
```

### JavaScript

#### Add new public function

```javascript
// route.service.js
export default class RouteService {
    /**
     * @deprecated tag:v6.5.0 - Use getRouteConfig() instead
     */
    getRoute(symfonyRoute) {
        // Returns string 'foo/bar'
        return this._someMagic(symfonyRoute);
    }
 
    getRouteConfig() {
        // Returns object { name: 'foo/bar', params: [] }
        return {
            url: this._someMagic(symfonyRoute).url,
            params: this._someMagic(symfonyRoute).params
        }
    }
}
```

#### Rename a method

```javascript
/**
 * @deprecated tag:v6.5.0 - Use onItemClick() instead
 */
onClick(event) {
    return onItemClick(event);
},
 
onItemClick(event) {
    // ...
}
```

#### Deprecate admin components

```javascript
/**
 * @deprecated tag:v6.5.0 - Use sw-new instead
 * @status deprecated
 */
Shopware.Component.register('sw-old', {
    deprecated: '6.5.0'
});
```

#### Deprecate admin component properties

```json
{
    name: 'example-component',
    props: {
        /** @deprecated tag:v6.5.0 - Insert additional information in comments */
        exampleProp: {
            type: String,
            required: false,
            default: 'Default value',
            deprecated: {
                version: '6.5.0',
                comment: 'Insert additional information in comments'
            }
        }
    }
}
```

#### Adding required properties to components

```json
{
    createdComponent() {
        /** @deprecated tag:v6.5.0 - Warning will be removed when prop is required */
        if (!this.newProp) {
            debug.warn(
                'sw-example-component',
                '"newProp" will be required in tag:v6.5.0'
            );
        }
    }
}
```

#### Renaming or removing JS services

```javascript
// http-client.service.js
/**
* @deprecated tag:v6.5.0 - Use NewHttpClient instead (new-http-client.service.js)
*/
export default class HttpClient {
    // ...
}
 
// new-http-client.service.js
export default class NewHttpClient {
    // ...
}
```

#### Renaming or removing JS plugins

```javascript
// buy-button.plugin.js
/**
* @deprecated tag:v6.5.0 - Use NewBuyButtonPlugin instead (new-buy-button.plugin.js)
*/
export default class BuyButtonPlugin extends Plugin {
    // ...
}
 
// new-buy-button.plugin.js
export default class NewBuyButtonPlugin extends Plugin {
    // ...
}
```

---

---
url: /docs/v6.6/resources/guidelines/code/backward-compatibility.md
---

# Backward Compatibility

## Introduction

Shopware is a standard ecommerce solution used by many customers worldwide and is the technical foundation of their online business. As developers of Shopware, it is our highest goal to guarantee the reliability of the software for our customers. Always remember that every change you make can have a big impact on the life of our customers, either in a good way or in a bad way.

For the release strategy, Shopware uses a semantic [versioning](https://www.shopware.com/en/news/shopware-6-versioning-strategy/) and therefore has to be always backward compatible for minor and patch updates. This brings additional challenges when changing the code of Shopware. The following guide aims to provide you with the necessary workflows and techniques to do your changes in a backward compatible way and what to do if it is not possible.

## Annotations

During the development, different cases occur where you want to replace old code with new ones or even remove some obsolete code. As Shopware must always be backward compatible on minor and patch updates, old code should only be removed with a major release. Until the next major release, you want to mark the code with a corresponding annotation to inform other developers of the planned change. This overview shows the most important annotations and in which situation they must be used.

### @deprecated

```php
/**
 * @deprecated tag:v6.5.0 - Use NewFunction() instead
 */
```

The `@deprecated` annotation is used for obsolete public code, which will be removed with the next major release. The annotation always needs the specific major version tag, in which the code should be removed. Always add a meaningful comment with information about the corresponding replacement and how the deprecated code can be removed.

### @feature-deprecated

```php
/**
 * @feature-deprecated (flag:FEATURE_NEXT_11111)
 */
```

The `@feature-deprecated` annotation is used for obsolete code during the development of a feature when the code is still hidden behind a feature flag. This is important so that code that is not public will not trigger deprecation warnings. This annotation has to be changed to the correct `@deprecated` annotation when the feature is released, and the corresponding feature flag is removed. Always add the name of the corresponding feature flag to the annotation so that it will not be forgotten when the flag is removed.

### @major-deprecated

```php
/**
 * @major-deprecated (flag:FEATURE_NEXT_22222)
 */
```

The `@major-deprecated` annotation is used for breaking code which has to stay behind a specific major feature flag until the next major release. Always add the name of the corresponding feature flag to the annotation so that it will not be forgotten when the flag is removed.

### @internal

```php
/**
 * @internal (flag:FEATURE_NEXT_11111)
 */
```

In combination with a feature flag, like shown above, the `@internal` annotation is used for newly introduced code, which is not yet released. This ensures that it will not be treated as a public API until the corresponding feature is released and makes it possible to change the code in any way until the final release. Always add the name of the corresponding feature flag to the annotation so that it will not be forgotten when the corresponding feature is released.

## Workflows

### Backward compatible features

When developing new features, the goal should always be to do this in a backward compatible way. This ensures that the feature can be shipped with a minor release to provide value for customers as soon as possible. The following table should help you to use the correct approach for each type of change.

| Case                    | During development                                                                                                                                                                                                                                                                                                                                       | On feature release                                                                                                                                       | Next major release                          |
| ---                     | ---                                                                                                                                                                                                                                                                                                                                                      | ---                                                                                                                                                      | ---                                         |
| 🚩 **Feature Flag**     | Hide code behind normal [feature flag](../../references/adr/2020-08-10-feature-flag-system.md).                                                                                                                                                                                                                                                                                            | Remove the feature flag.                                                                                                                                     |                                             |
| ➕ **New code**         | Add `@internal annotation` for new public API.                                                                                                                                                                                                                                                                                                           | Remove `@internal` annotation.                                                                                                                           |                                             |
| ⚪ **Obsolete code**    | Add `@feature-deprecated` annotation.                                                                                                                                                                                                                                                                                                                    | Replace @feature-deprecated with normal `@deprecated` annotation.                                                                                        | Remove old code.                            |
| 🔴 **Breaking change**  | Add `@major-deprecated` annotation. Hide breaking code behind additional major [feature flag](../../references/adr/2020-08-10-feature-flag-system.md). Also, create a separate [changelog](../../references/adr/2020-08-03-implement-new-changelog.md) for the change with the major flag. |                                                                                                                                                          | Remove old code. Remove the major feature flag. |
| 🔍 **Tests**            | Add new tests behind a feature flag.                                                                                                                                                                                                                                                                                                                       | Remove feature flags from new tests. Declare old tests as [legacy](https://symfony.com/doc/current/components/phpunit_bridge.html#mark-tests-as-legacy). | Remove legacy tests.                        |

You can also find more detailed information and code examples in the corresponding **[ADR](https://github.com/shopware/shopware/blob/trunk/adr/)** for the deprecation strategy.

### Breaking Changes / Features

The first goal should always be to make your changes backward compatible. But there might be some special cases where it isn't possible in any way. In this case, the change can only be released with a major version. As we develop all changes in the same code base, the `trunk` branch, the changes have to stay behind a special feature flag, which is especially marked as a major feature flag.

| Case                    | During development                                                                                                                                           | Next major release (feature release) |
| ---                     | ---                                                                                                                                                          | ---                                  |
| 🚩 **Feature Flag**     | Hide code behind a major feature flag.                                                                                                                         | Remove major feature flag.           |
| ➕ **New code**         | Add `@internal` annotation for new public API.                                                                                                               | Remove `@internal` annotation.       |
| ⚪ **Obsolete code**    | Add `@major-deprecated` annotation.                                                                                                                          | Remove old code.                     |
| 🔴 **Breaking change**  | Add `@major-deprecated` annotation.                                                                                                                          | Remove old code.                     |
| 🔍 **Tests**            | Add new tests behind a major feature flag. Declare old tests as [legacy](https://symfony.com/doc/current/components/phpunit_bridge.html#mark-tests-as-legacy). | Remove legacy tests.                 |

## Compatibility sheet

To ensure backward compatibility, it is important to know what you are allowed to do and what not. The following sheet should give you an orientation on common changes and how they could affect the backward compatibility. Although a lot of effort went into this list, it is not guaranteed to be 100% complete. Always keep the persona of third-party developers in mind and challenge your changes against external needs.

### PHP

As Shopware is based on the PHP framework Symfony, we also have to make sure to use the rules which the framework follows. Besides the list below, always keep in mind the backward compatibility promise and implement your changes in a way the promise is kept.

**[Symfony Backward Compatibility Promise](https://symfony.com/doc/current/contributing/code/bc.html)**

| Use Case                                                                                                      | Allowed?   | Notes / Alternatives                                                                                                                                                                                                           |
| ---                                                                                                           | ---        | ---                                                                                                                                                                                                                            |
| Change the typehint of a class, interface or trait.                                                           | 🔴 NO      | Add the new typehint as an abstract class. Code Example: [Extend class with abstract class](#extend-class-with-abstract-class)                                                                                             |
| Change the constructor of a service.                                                                          | ✅ YES     | Services have to be instantiated over the container, so the changes should not break anything.                                                                                                                                 |
| Change the constructor of a class, that is not a service. (Instantiated with new Class())                     | ⚪ PARTIAL | Only optional arguments are allowed to be added and this should be made via `func_get_args()`.  Code Example: [Add an argument](#add-an-argument)                                                                            |
| Change the arguments of a public method.                                                                      | ⚪ PARTIAL | Only optional arguments are allowed to be added and this should be made via `func_get_args()`. Code Example: [Add an argument](#add-an-argument)                                                                             |
| Change the arguments of a protected method.                                                                   | ⚪ PARTIAL | Only optional arguments are allowed to be added and this should be made via `func_get_args()`. Code Example: [Add an argument](#add-an-argument)                                                                             |
| Change the arguments of a private method.                                                                     | ✅ YES     |                                                                                                                                                                                                                                |
| Change the return the type of a method.                                                                       | 🔴 NO      | Create a new method and deprecate the old one.                                                                                                                                                                                 |
| Change the value of a public constant.                                                                        | 🔴 NO      | You should add a new constant. Annotate the old constant as deprecated and remove it in the next major version.                                                                                                                |
| Change the value of a private constant.                                                                       | ✅ YES     | Check all potential usages of the constant. Maybe it is used somewhere to be stored in the database. In that case, you must write a migration for it which ensures every use of the constant in a db-value is updated as well. |
| Change a class or method to final.                                                                            | 🔴 NO      | You will have to deprecate the class or method and add an annotation that it will be final in the next major version.                                                                                                          |
| Change the visibility of a class, method or property from public to private/protected or protected to private | 🔴 NO      | Annotate it as deprecated and change the visibility in the next major version.                                                                                                                                                 |
| Change the namespace of a class.                                                                              | 🔴 NO      | Duplicate the class and mark the old one as deprecated.                                                                                                                                                                        |
| Change static state (remove static or delete static keyword).                                                 | 🔴 NO      | Annotate it as deprecated and add or remove the static keyword in the next major version.                                                                                                                                      |
| Add parameter to interface or abstract class function.                                                        | ⚪ PARTIAL | Only optional arguments are allowed to be added and this should be made via `func_get_args()`.  Code Example: [Add an argument](#add-an-argument)                                                                            |
| Add new public function to interface.                                                                         | 🔴 NO      |                                                                                                                                                                                                                                |
| Add new public function to abstract class.                                                                    | ⚪ PARTIAL | Only possible if the abstract class already contains the `getDecorated` call.  Code Example: [Add a public function](#add-a-public-function)                                                                                 |
| Add an event or event dispatch.                                                                               | ✅ YES     |                                                                                                                                                                                                                                |
| Add a constant.                                                                                               | ✅ YES     |                                                                                                                                                                                                                                |
| Remove an event or event dispatch.                                                                            | 🔴 NO      |                                                                                                                                                                                                                                |
| Remove a public property, constant or method.                                                                 | 🔴 NO      | Annotate it as deprecated and remove it in the next major release.                                                                                                                                                             |
| Remove a protected property, constant or method.                                                              | 🔴 NO      | Annotate it as deprecated and remove it in the next major release.                                                                                                                                                             |
| Remove a private property, constant, or method.                                                               | ✅ YES     |                                                                                                                                                                                                                                |

### Storefront

#### TWIG templates

| Use Case                                                           | Allowed?     | Notes / Alternatives                                                                                                                                                                                                                                                                |
| ---                                                                | ---          | ---                                                                                                                                                                                                                                                                                 |
| Removing TWIG blocks.                                              | 🔴 NO        | Use the deprecation workflow.Code Example: [Deprecate TWIG block](#deprecate-twig-block)                                                                                                                                                                                            |
| Renaming TWIG blocks.                                              | 🔴 NO        | Use the deprecation workflow. Create a new surrounding block with the new name and deprecate the old one. All variables which are defined in the scope of the old block must be moved to the new surrounding block scope.Code Example: [Rename TWIG block](#rename-twig-block) |
| Moving TWIG blocks within the same file.                           | ⚪ PARTIAL   | Only within the same scope/parent block.                                                                                                                                                                                                                                          |
| Removing TWIG variables.                                           | 🔴 NO        |                                                                                                                                                                                                                                                                                     |
| Renaming TWIG variables.                                           | 🔴 NO        | Create a new variable within the same scope and deprecate the old one.                                                                                                                                                                                                              |
| Changing the value of TWIG variables                               | ⚪ PARTIAL   | The data type has to stay the same. Otherwise, use the deprecation workflow.                                                                                                                                                                                                         |
| Moving TWIG variable definitions to other TWIG blocks.             | ⚪ PARTIAL   | Only when they are being moved higher up in the block scope.                                                                                                                                                                                                                        |
| Adding TWIG blocks that affect the scope of variable definitions. | 🔴 NO        |                                                                                                                                                                                                                                                                                     |
| Moving template files to other directories.                        | 🔴 NO        |                                                                                                                                                                                                                                                                                     |

#### HTML

| Use Case                                   | Allowed?   | Notes / Alternatives                                                                              |
| ---                                        | ---        | ---                                                                                               |
| Removing HTML sections.                    | 🔴 NO      |                                                                                                   |
| Moving HTML sections within the same file. | ⚪ PARTIAL | Only within the same TWIG Block.                                                                  |
| Renaming of removing CSS selectors.        | 🔴 NO      | Use the deprecation workflow.Code Example: [Deprecate CSS selectors](#deprecate-css-selectors) |

#### JavaScript

| Use Case                                           | Allowed? | Notes / Alternatives                                                                                                  |
| ---                                                | ---      | ---                                                                                                                   |
| Renaming or removing JS services.                  | 🔴 NO    | Use the deprecation workflow.Code Example: [Renaming or removing JS services](#renaming-or-removing-js-services)  |
| Renaming or removing JS plugins.                | 🔴 NO    | Use the deprecation workflow.Code Example: [Renaming or removing JS plugins](#renaming-or-removing-js-plugins) |
| Changing the public API of a JS plugin or service. | 🔴 NO    | Use the deprecation workflow.Code Example: [Add new public function](#add-new-public-function)                    |
| Renaming methods of JS plugins or services.        | 🔴 NO    | Use the deprecation workflow.Code Example: [Rename a method](#rename-a-method)                                    |
| Renaming or removing of JS events.                 | 🔴 NO    |                                                                                                                       |
| Changing the parameters of JS events.              | 🔴 NO    |                                                                                                                       |

#### Styling / CSS

| Use Case                                                  | Allowed?   | Notes / Alternatives                                                                                                                                                                                                                       |
| ---                                                       | ---        | ---                                                                                                                                                                                                                                        |
| Renaming or removing CSS definitions.                     | ⚪ PARTIAL | Only CSS properties that have a visual effect but no structure or functional CSS properties. Not allowed are: `display`, `position`, `visibility`, `z-index`, `pointer-events`, `overflow`, `transform`                              |
| Changing generic selectors of the Bootstrap framework.    | ⚪ PARTIAL | Be aware of what you are doing. Fixing a small styling issue might be ok. Changing structural properties might have a big impact on the layout and functionality.                                                                      |
| Changing the CSS properties of generic Bootstrap classes. | ⚪ PARTIAL | Be aware of what you are doing. Fixing a small styling issue might be ok. Changing structural properties might have a big impact on the layout and functionality.                                                                      |
| Renaming or removing SASS variables or mixins.            | 🔴 NO      |                                                                                                                                                                                                                                            |
| Renaming or removing standard theme variables.         | 🔴 NO      |                                                                                                                                                                                                                                            |

### Administration

#### Component Templates

| Use Case                                                                        | Allowed?   | Notes / Alternatives                                                                     |
| ---                                                                             | ---        | ---                                                                                      |
| Renaming or removing TWIG blocks.                                               | 🔴 NO      | Use the deprecation workflow.Code Example: [Deprecate TWIG block](#deprecate-twig-block) |
| Moving TWIG blocks within the same file.                                        | ⚪ PARTIAL | Only within the same scope/parent block.                                               |
| Changing the "ref" attribute of elements.                                       | 🔴 NO      |                                                                                          |
| Changing VueJS specific template functions, like v-if.                          | 🔴 NO      |                                                                                          |
| Changing VueJS data functions, like v-model, or v-bind.                         | 🔴 NO      |                                                                                          |
| Renaming or removing VueJS slots.                                               | 🔴 NO      | Use the deprecation workflow.Code Example: [Deprecate Vue Slot](#deprecate-vue-slot) |
| Using new functionality of the VueJS framework, which has a breaking behavior. | 🔴 NO      |                                                                                          |
| Renaming or removing global available VueJS template functions.              | 🔴 NO      |                                                                                          |

#### JavaScript Modules & Components

| Use Case                                                     | Allowed?   | Notes / Alternatives                                                                                                                                                                                                                        |
|---                                                           | ---        | ---                                                                                                                                                                                                                                         |
| Renaming or removing base components.                     | 🔴 NO      | Use the deprecation workflow.Code Example: [Deprecate admin components](#deprecate-admin-components)                                                                                                                                    |
| Renaming or removing module components.                   | 🔴 NO      | Use the deprecation workflow.Code Example: [Deprecate admin components](#deprecate-admin-components)                                                                                                                                    |
| Renaming or removing methods                                 | 🔴 NO      | Use the deprecation workflow.Code Example: [Rename a method](#rename-a-method)                                                                                                                                                          |
| Changing the return value of a method                        | 🔴 NO      | Use the deprecation workflow.Code Example: [Add new public function](#add-new-public-function)                                                                                                                                          |
| Changing the parameters of a method                          | 🔴 NO      | Only with new optional parameters with a default value or if the method uses a single object as a parameter via destructuring. Otherwise, use the deprecation workflow.Code Example: [Add new public function](#add-new-public-function) |
| Renaming or removing of required props                       | 🔴 NO      | Use the deprecation workflow.Code Example: [Deprecate properties](#deprecate-admin-component-properties)                                                                                                                                |
| Renaming or removing of vue events                           | 🔴 NO      | Use the deprecation workflow.Add a deprecation annotation to the event which needs to be renamed or removed and offer an alternative inside the deprecation comment when possible                                                       |
| Changing the parameters of a vue event                       | ⚪ PARTIAL | Only with new optional parameters with a default value. Only when the method receives an object as a parameter and when working with destructuring                                                             |
| Adding required properties to components.                    | 🔴 NO      | Add the property as optional property and show a warning if the property is empty. This could be done on component creation or with a property validator.Code Example: [Adding required properties to components](#adding-required-properties-to-components) |
| Renaming or removing data that is used in the data binding. | 🔴 NO      |                                                                                                                                                                                                                                             |
| Renaming or removing the routes of a module.                 | 🔴 NO      |                                                                                                                                                                                                                                             |
| Changing the parameters of a route.                          | 🔴 NO      |                                                                                                                                                                                                                                             |
| Adding required parameters to a route.                       | 🔴 NO      |                                                                                                                                                                                                                                             |
| Changing the public API of the global "Shopware" object.     | 🔴 NO      | Use the deprecation workflow. Use the same workflow as for other methods.Code Example: [Rename a method](#rename-a-method)                                                                                                                  |
| Changing the public API of state stores. (VueX)              | 🔴 NO      |                                                                                                                                                                                                                                             |
| Renaming, removing, or not-using of assets or other imports.  | 🔴 NO      |                                                                                                                                                                                                                                             |

#### Component Styling

| Use Case                                                    | Allowed?   | Notes / Alternatives                                                                                                                                                                                                                                        |
| ---                                                         | ---        | ---                                                                                                                                                                                                                                                         |
| Renaming or removing CSS definitions.                       | ⚪ PARTIAL | Only CSS properties that have a visual effect but no structure or functional CSS properties. Not allowed are: `display`, `position`, `visibility`, `z-index`, `pointer-events`, `overflow`, `transform`                                               |
| Renaming or removing functional selectors, like `is--*`. | 🔴 NO      |                                                                                                                                                                                                                                                             |
| Renaming or removing root CSS selectors.                    | 🔴 NO      |                                                                                                                                                                                                                                                             |

## Code Examples

### PHP

#### Extend class with abstract class

```php
/** Before */
class MailService implements MailServiceInterface
 
/** After */
class MailService extends AbstractMailService
class AbstractMailService implements MailServiceInterface
```

#### Add an argument

```php
/**
 * @feature-deprecated tag:v6.5.0 (flag:FEATURE_NEXT_22222)
 * Parameter $precision will be mandatory in future implementation
 */
public function calculate(ProductEntity $product, Context $context /*, int $precision */): Product
{
   if (Feature::isActive('FEATURE_NEXT_22222')) {
      if (\func_num_args() === 3) {
         $precision = func_get_arg(2);
         // Do new calculation
      } else {
         throw new InvalidArgumentException('Argument 3 $precision is required with feature FEATURE_NEXT_22222');
      }
   } else {
      // Do old calculation
   }
}
```

#### Add a public function

```php
/** Before */
abstract class AbstractProductRoute
{
    abstract public function getDecorated(): AbstractProductRoute;
 
    abstract public function load();
}
 
 
/** After */
abstract class AbstractProductRoute
{
    abstract public function getDecorated(): AbstractProductRoute;
 
    abstract public function load();
 
    /**
     * @deprecated tag:v6.5.0 - Will be abstract 
     */
    public function loadV2()
    {
        return $this->getDecorated()->loadV2();
    }
}
```

### TWIG & HTML

#### Deprecate TWIG block

**Storefront**: Use the `deprecated` tag from TWIG, including a comment with the normal annotation.

```html
{% block the_block_name %}
    {% deprecated '@deprecated tag:v6.5.0 - Block will be removed completely including the content' %}
    <div>Content</div>
{% endblock %}
```

**Administration**: Use normal TWIG comments for the annotation, as the other syntax is not supported.

```html
{% block the_block_name %}
    {# @deprecated tag:v6.5.0 - Block will be removed completely including the content #}
    <div>Content</div>
{% endblock %}
```

#### Rename TWIG block

```html
{% block new_block_name %}
    {% block old_block_name %}
    {% deprecated '@deprecated tag:v6.5.0 - Use `new_block_name` instead' %}
        <div>Content</div>
    {% endblock %}
{% endblock %}
```

#### Deprecate CSS selectors

```html
{# @deprecated tag:v6.5.0 - CSS class "card-primary" is deprecated, use "card-major" instead #}
<div class="card card-major card-primary">
    ...
</div>
```

#### Deprecate Vue Slot

```html
{# @deprecated tag:v6.5.0 - Use slot "main-content" instead #}
<slot name="content"></slot>
<slot name="main-content"></slot>
```

### JavaScript

#### Add new public function

```javascript
// route.service.js
export default class RouteService {
    /**
     * @deprecated tag:v6.5.0 - Use getRouteConfig() instead
     */
    getRoute(symfonyRoute) {
        // Returns string 'foo/bar'
        return this._someMagic(symfonyRoute);
    }
 
    getRouteConfig() {
        // Returns object { name: 'foo/bar', params: [] }
        return {
            url: this._someMagic(symfonyRoute).url,
            params: this._someMagic(symfonyRoute).params
        }
    }
}
```

#### Rename a method

```javascript
/**
 * @deprecated tag:v6.5.0 - Use onItemClick() instead
 */
onClick(event) {
    return onItemClick(event);
},
 
onItemClick(event) {
    // ...
}
```

#### Deprecate admin components

```javascript
/**
 * @deprecated tag:v6.5.0 - Use sw-new instead
 * @status deprecated
 */
Shopware.Component.register('sw-old', {
    deprecated: '6.5.0'
});
```

#### Deprecate admin component properties

```json
{
    name: 'example-component',
    props: {
        /** @deprecated tag:v6.5.0 - Insert additional information in comments */
        exampleProp: {
            type: String,
            required: false,
            default: 'Default value',
            deprecated: {
                version: '6.5.0',
                comment: 'Insert additional information in comments'
            }
        }
    }
}
```

#### Adding required properties to components

```json
{
    createdComponent() {
        /** @deprecated tag:v6.5.0 - Warning will be removed when prop is required */
        if (!this.newProp) {
            debug.warn(
                'sw-example-component',
                '"newProp" will be required in tag:v6.5.0'
            );
        }
    }
}
```

#### Renaming or removing JS services

```javascript
// http-client.service.js
/**
* @deprecated tag:v6.5.0 - Use NewHttpClient instead (new-http-client.service.js)
*/
export default class HttpClient {
    // ...
}
 
// new-http-client.service.js
export default class NewHttpClient {
    // ...
}
```

#### Renaming or removing JS plugins

```javascript
// buy-button.plugin.js
/**
* @deprecated tag:v6.5.0 - Use NewBuyButtonPlugin instead (new-buy-button.plugin.js)
*/
export default class BuyButtonPlugin extends Plugin {
    // ...
}
 
// new-buy-button.plugin.js
export default class NewBuyButtonPlugin extends Plugin {
    // ...
}
```

---

---
url: /docs/v6.5/resources/references/adr/2022-03-25-base-context-factory.md
---

# Base context factory

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-03-25-base-context-factory.md)
:::
Within each store api request (and storefront), the sales channel context must be built. Building the sales channel context is a very resource consuming task for the database, since many DAL objects are now included in the sales channel context. Therefore, a cache for the corresponding service (`Shopware\Core\System\SalesChannel\Context\SalesChannelContextFactory`) has already been implemented in the past: `Shopware\Core\System\SalesChannel\Context\CachedSalesChannelContextFactory`. However, since the context also contains the customer and the selected shipping address as well as billing address, the context cannot be cached once a customer is logged in:

```php
<?php declare(strict_types=1);

namespace Shopware\Core\System\SalesChannel\Context;

class CachedSalesChannelContextFactory extends AbstractSalesChannelContextFactory
{
    public function create(string $token, string $salesChannelId, array $options = []): SalesChannelContext
    {
        if (!$this->isCacheable($options)) {
            return $this->getDecorated()->create($token, $salesChannelId, $options);
        }

        // ...
    }

    private function isCacheable(array $options): bool
    {
        return !isset($options[SalesChannelContextService::CUSTOMER_ID])
            && !isset($options[SalesChannelContextService::BILLING_ADDRESS_ID])
            && !isset($options[SalesChannelContextService::SHIPPING_ADDRESS_ID]);
    }
}
```

However, since there is also data in the context that is independent of a customer's data, it is possible to cache some of this resource-costing data across customers, even if the customer is logged in, has selected a different payment method, shipping method or address. For this we have implemented the `Shopware\Core\System\SalesChannel\Context\BaseContextFactory`, which is responsible for creating the `Shopware\Core\System\SalesChannel\BaseContext`. Only data that belongs to the sales channel or is independent of the customer account is loaded into the `BaseContext`:

```php
<?php declare(strict_types=1);

namespace Shopware\Core\System\SalesChannel;

class BaseContext
{
    protected CustomerGroupEntity $currentCustomerGroup;

    protected CustomerGroupEntity $fallbackCustomerGroup;

    protected CurrencyEntity $currency;

    protected SalesChannelEntity $salesChannel;

    protected TaxCollection $taxRules;

    protected PaymentMethodEntity $paymentMethod;

    protected ShippingMethodEntity $shippingMethod;

    protected ShippingLocation $shippingLocation;

    protected Context $context;

    private CashRoundingConfig $itemRounding;

    private CashRoundingConfig $totalRounding;
}
```

The `BaseContextFactory` as well as the `BaseContext` are both marked as `@internal` and are not intended for extensions. Any intervention in the loading of the BaseContext can quickly lead to cache misses and is therefore not supported.

In addition to the corresponding `$salesChannelId`, the current session parameters are passed to the service, which contains a list of changed parameters. The `BaseContextFactory` takes into account the following parameters, which also have an effect on the corresponding cache permutation of the service:

* `shippingMethodId` - Contains the id of the selected shipping method.
* `paymentMethodId` - Contains the id of the selected payment method
* `countryId` - Contains the id of the selected shipping country
* `countryStateId` - Contains the id of the selected shipping state
* `currencyId` - Contains the id of the selected currency
* `languageId` - Contains the id of the selected language

In addition to the `Shopware\Core\System\SalesChannel\Context\BaseContextFactory` the `Shopware\Core\System\SalesChannel\Context\CachedSalesChannelContextFactory` was implemented, which is responsible for caching the base context. It assembles the cache key based on the parameters listed above and loads the base context from the cache if it has already been loaded once.

```php
<?php declare(strict_types=1);

namespace Shopware\Core\System\SalesChannel\Context;

class CachedBaseContextFactory extends AbstractBaseContextFactory
{
    public function create(string $salesChannelId, array $options = []): BaseContext
    {
        ksort($options);

        $keys = \array_intersect_key($options, [
            SalesChannelContextService::CURRENCY_ID => true,
            SalesChannelContextService::LANGUAGE_ID => true,
            SalesChannelContextService::DOMAIN_ID => true,
            SalesChannelContextService::PAYMENT_METHOD_ID => true,
            SalesChannelContextService::SHIPPING_METHOD_ID => true,
            SalesChannelContextService::VERSION_ID => true,
            SalesChannelContextService::COUNTRY_ID => true,
            SalesChannelContextService::COUNTRY_STATE_ID => true,
        ]);

        $key = implode('-', [$name, md5(json_encode($keys, \JSON_THROW_ON_ERROR))]);
        
        //...
    }
}
```

So now the caching of the Sales Channel context is handled on two levels:

* `CachedSalesChannelContextFactory`: Is responsible for global caching and provides a fast hit rate and load time for customers who are not logged in.
* `CachedBaseContextFactory`: Is responsible for caching generic objects that do not relate to the customer account. Once a customer has created the context for another payment or shipping method, it will be shared with all logged-in users.

---

---
url: /docs/v6.6/resources/references/adr/2022-03-25-base-context-factory.md
---

# Base context factory

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-03-25-base-context-factory.md)
:::
Within each store api request (and storefront), the sales channel context must be built. Building the sales channel context is a very resource consuming task for the database, since many DAL objects are now included in the sales channel context. Therefore, a cache for the corresponding service (`Shopware\Core\System\SalesChannel\Context\SalesChannelContextFactory`) has already been implemented in the past: `Shopware\Core\System\SalesChannel\Context\CachedSalesChannelContextFactory`. However, since the context also contains the customer and the selected shipping address as well as billing address, the context cannot be cached once a customer is logged in:

```php
<?php declare(strict_types=1);

namespace Shopware\Core\System\SalesChannel\Context;

class CachedSalesChannelContextFactory extends AbstractSalesChannelContextFactory
{
    public function create(string $token, string $salesChannelId, array $options = []): SalesChannelContext
    {
        if (!$this->isCacheable($options)) {
            return $this->getDecorated()->create($token, $salesChannelId, $options);
        }

        // ...
    }

    private function isCacheable(array $options): bool
    {
        return !isset($options[SalesChannelContextService::CUSTOMER_ID])
            && !isset($options[SalesChannelContextService::BILLING_ADDRESS_ID])
            && !isset($options[SalesChannelContextService::SHIPPING_ADDRESS_ID]);
    }
}
```

However, since there is also data in the context that is independent of a customer's data, it is possible to cache some of this resource-costing data across customers, even if the customer is logged in, has selected a different payment method, shipping method or address. For this we have implemented the `Shopware\Core\System\SalesChannel\Context\BaseContextFactory`, which is responsible for creating the `Shopware\Core\System\SalesChannel\BaseContext`. Only data that belongs to the sales channel or is independent of the customer account is loaded into the `BaseContext`:

```php
<?php declare(strict_types=1);

namespace Shopware\Core\System\SalesChannel;

class BaseContext
{
    protected CustomerGroupEntity $currentCustomerGroup;

    protected CustomerGroupEntity $fallbackCustomerGroup;

    protected CurrencyEntity $currency;

    protected SalesChannelEntity $salesChannel;

    protected TaxCollection $taxRules;

    protected PaymentMethodEntity $paymentMethod;

    protected ShippingMethodEntity $shippingMethod;

    protected ShippingLocation $shippingLocation;

    protected Context $context;

    private CashRoundingConfig $itemRounding;

    private CashRoundingConfig $totalRounding;
}
```

The `BaseContextFactory` as well as the `BaseContext` are both marked as `@internal` and are not intended for extensions. Any intervention in the loading of the BaseContext can quickly lead to cache misses and is therefore not supported.

In addition to the corresponding `$salesChannelId`, the current session parameters are passed to the service, which contains a list of changed parameters. The `BaseContextFactory` takes into account the following parameters, which also have an effect on the corresponding cache permutation of the service:

* `shippingMethodId` - Contains the id of the selected shipping method.
* `paymentMethodId` - Contains the id of the selected payment method
* `countryId` - Contains the id of the selected shipping country
* `countryStateId` - Contains the id of the selected shipping state
* `currencyId` - Contains the id of the selected currency
* `languageId` - Contains the id of the selected language

In addition to the `Shopware\Core\System\SalesChannel\Context\BaseContextFactory` the `Shopware\Core\System\SalesChannel\Context\CachedSalesChannelContextFactory` was implemented, which is responsible for caching the base context. It assembles the cache key based on the parameters listed above and loads the base context from the cache if it has already been loaded once.

```php
<?php declare(strict_types=1);

namespace Shopware\Core\System\SalesChannel\Context;

class CachedBaseContextFactory extends AbstractBaseContextFactory
{
    public function create(string $salesChannelId, array $options = []): BaseContext
    {
        ksort($options);

        $keys = \array_intersect_key($options, [
            SalesChannelContextService::CURRENCY_ID => true,
            SalesChannelContextService::LANGUAGE_ID => true,
            SalesChannelContextService::DOMAIN_ID => true,
            SalesChannelContextService::PAYMENT_METHOD_ID => true,
            SalesChannelContextService::SHIPPING_METHOD_ID => true,
            SalesChannelContextService::VERSION_ID => true,
            SalesChannelContextService::COUNTRY_ID => true,
            SalesChannelContextService::COUNTRY_STATE_ID => true,
        ]);

        $key = implode('-', [$name, md5(json_encode($keys, \JSON_THROW_ON_ERROR))]);
        
        //...
    }
}
```

So now the caching of the Sales Channel context is handled on two levels:

* `CachedSalesChannelContextFactory`: Is responsible for global caching and provides a fast hit rate and load time for customers who are not logged in.
* `CachedBaseContextFactory`: Is responsible for caching generic objects that do not relate to the customer account. Once a customer has created the context for another payment or shipping method, it will be shared with all logged-in users.

---

---
url: /resources/admin-extension-sdk/api-reference/base-options.md
---
# Base Options

Base options are shared configuration options that can be passed to SDK methods which accept a single payload object. They are provided as additional properties alongside the method's own parameters.

This applies to APIs such as `notification.dispatch()`, `toast.dispatch()`, many `ui.*` methods, `context.*`, `data.get()`, and `data.update()`.

Higher-level data helpers such as `data.repository.*` and `data.subscribe()` currently use narrower method signatures and do not expose base options on their public API.

More options may be added in the future. Currently, the following option is available:

| Name         | Required | Default | Availability        | Description                                                                                |
| :----------- | :------- | :------ | :------------------ | :----------------------------------------------------------------------------------------- |
| `privileges` | false    |         | >= Shopware 6.6.3.0 | Check the current user's privileges before executing the action. See [Privileges](#privileges). |

#### Usage

In this example, the base options are passed on the same object as the method-specific fields:

```ts
import { notification } from '@shopware-ag/meteor-admin-sdk';

notification.dispatch({
    title: 'Product report ready',
    message: 'Your product report is ready',
    /* ... base options ... */
});
```

## Privileges

The `privileges` option accepts an array of privilege strings. When provided, the SDK checks whether the current Administration user holds all listed privileges before executing the action. If any privilege is missing, the action is silently skipped.

:::warning Not a security feature
Privilege checks happen client-side in the browser. They prevent UI elements from appearing for users who lack the required permissions, but they do not enforce access control on the server. Server-side authorization is still required for any sensitive operation.
:::

#### Privilege string format

Each privilege string follows the pattern `action:entity`:

```
'product:read'
'order:update'
'category:create'
'customer:delete'
```

Available actions:

| Action       | Description                          |
| :----------- | :----------------------------------- |
| `read`       | Read access to the entity            |
| `create`     | Permission to create new entities    |
| `update`     | Permission to modify existing entities |
| `delete`     | Permission to remove entities        |
| `additional` | Custom additional privileges         |

#### Usage

Pass the `privileges` array to any SDK method that supports base options:

```ts
import { notification, ui } from '@shopware-ag/meteor-admin-sdk';

notification.dispatch({
    title: 'Product report ready',
    message: 'Your product report is ready',
    privileges: [
        'product:read',
    ],
});

ui.actionButton.add({
    name: 'generate-report',
    entity: 'product',
    view: 'detail',
    label: 'Generate Report',
    privileges: [
        'product:read',
        'order:read',
    ],
});
```

#### Parameters

| Name         | Type       | Required | Description                                                                 |
| :----------- | :--------- | :------- | :-------------------------------------------------------------------------- |
| `privileges` | `string[]` | false    | Array of `action:entity` strings. All must match for the action to execute. |

---

---
url: /docs/resources/references/adr/2022-03-25-base-context-factory.md
---

# Base sales channel context factory

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-03-25-base-context-factory.md)
:::
Within each store api request (and storefront), the sales channel context must be built.
Building the sales channel context is a very resource consuming task for the database,
since many DAL objects are now included in the sales channel context.
Therefore, a cache for the corresponding service (`Shopware\Core\System\SalesChannel\Context\SalesChannelContextFactory`) has already been implemented in the past: `Shopware\Core\System\SalesChannel\Context\CachedSalesChannelContextFactory`.
However, since the context also contains the customer and the selected shipping address as well as billing address, the context cannot be cached once a customer is logged in:

```php
<?php declare(strict_types=1);

namespace Shopware\Core\System\SalesChannel\Context;

class CachedSalesChannelContextFactory extends AbstractSalesChannelContextFactory
{
    public function create(string $token, string $salesChannelId, array $options = []): SalesChannelContext
    {
        if (!$this->isCacheable($options)) {
            return $this->getDecorated()->create($token, $salesChannelId, $options);
        }

        // ...
    }

    private function isCacheable(array $options): bool
    {
        return !isset($options[SalesChannelContextService::CUSTOMER_ID])
            && !isset($options[SalesChannelContextService::BILLING_ADDRESS_ID])
            && !isset($options[SalesChannelContextService::SHIPPING_ADDRESS_ID]);
    }
}
```

However, since there is also data in the context that is independent of a customer's data,
it is possible to cache some of this resource-costing data across customers, even if the customer is logged in, has selected a different payment method, shipping method or address.
For this we have implemented the `Shopware\Core\System\SalesChannel\Context\BaseSalesChannelContextFactory`, which is responsible for creating the `Shopware\Core\System\SalesChannel\BaseSalesChannelContext`.
Only data that belongs to the sales channel or is independent of the customer account is loaded into the `BaseSalesChannelContext`:

```php
<?php declare(strict_types=1);

namespace Shopware\Core\System\SalesChannel;

class BaseSalesChannelContext
{
    protected CustomerGroupEntity $currentCustomerGroup;

    protected CustomerGroupEntity $fallbackCustomerGroup;

    protected CurrencyEntity $currency;

    protected SalesChannelEntity $salesChannel;

    protected TaxCollection $taxRules;

    protected PaymentMethodEntity $paymentMethod;

    protected ShippingMethodEntity $shippingMethod;

    protected ShippingLocation $shippingLocation;

    protected Context $context;

    private CashRoundingConfig $itemRounding;

    private CashRoundingConfig $totalRounding;
}
```

The `BaseSalesChannelContextFactory` as well as the `BaseSalesChannelContext` are both marked as `@internal` and are not intended for extensions.
Any intervention in the loading of the `BaseSalesChannelContext` can quickly lead to cache misses and is therefore not supported.

In addition to the corresponding `$salesChannelId`, the current session parameters are passed to the service, which contains a list of changed parameters.
The `BaseSalesChannelContextFactory` takes into account the following parameters, which also have an effect on the corresponding cache permutation of the service:

* `shippingMethodId` - Contains the id of the selected shipping method.
* `paymentMethodId` - Contains the id of the selected payment method
* `countryId` - Contains the id of the selected shipping country
* `countryStateId` - Contains the id of the selected shipping state
* `currencyId` - Contains the id of the selected currency
* `languageId` - Contains the id of the selected language

In addition to the `Shopware\Core\System\SalesChannel\Context\BaseSalesChannelContextFactory` the `Shopware\Core\System\SalesChannel\Context\CachedBaseSalesChannelContextFactory` was implemented, which is responsible for caching the base context.
It assembles the cache key based on the parameters listed above and loads the base context from the cache if it has already been loaded once.

```php
<?php declare(strict_types=1);

namespace Shopware\Core\System\SalesChannel\Context;

class CachedBaseSalesChannelContextFactory extends AbstractBaseSalesChannelContextFactory
{
    public function create(string $salesChannelId, array $options = []): BaseContext
    {
        ksort($options);

        $keys = \array_intersect_key($options, [
            SalesChannelContextService::CURRENCY_ID => true,
            SalesChannelContextService::LANGUAGE_ID => true,
            SalesChannelContextService::DOMAIN_ID => true,
            SalesChannelContextService::PAYMENT_METHOD_ID => true,
            SalesChannelContextService::SHIPPING_METHOD_ID => true,
            SalesChannelContextService::VERSION_ID => true,
            SalesChannelContextService::COUNTRY_ID => true,
            SalesChannelContextService::COUNTRY_STATE_ID => true,
        ]);

        $key = implode('-', [$name, md5(json_encode($keys, \JSON_THROW_ON_ERROR))]);
        
        //...
    }
}
```

So now the caching of the Sales Channel context is handled on two levels:

* `CachedSalesChannelContextFactory`: Is responsible for global caching and provides a fast hit rate and load time for customers who are not logged in.
* `CachedBaseSalesChannelContextFactory`: Is responsible for caching generic objects that do not relate to the customer account.
  Once a customer has created the context for another payment or shipping method, it will be shared with all logged-in users.

---

---
url: /docs/products/extensions/b2b-suite/concept/basic-conventions.md
---

# Basic Conventions

## Codebase conventions

List of naming conventions the B2B Suite complies to:

| Group                                              | Practice                                                                             |
|----------------------------------------------------|--------------------------------------------------------------------------------------|
| DI Container                                       | All container ids look like `b2b_*.*`                                                |
| The first asterisk is the component name           |                                                                                      |
| The second asterisk is a class name abbreviation   |                                                                                      |
| Database                                           | All table names start with `b2b_`                                                    |
| All table names are in singular                    |                                                                                      |
| All field and table names are in snake case        |                                                                                      |
| Attributes                                         | All attribute names start with `swag_b2b_`                                           |
| Subscriber                                         | All subscriber methods are named in accordance with their function, not to the event |
| Tests                                              | All test methods are in snake case                                                   |
| All test methods start with `test_`                |                                                                                      |
| Templates                                          | All new layout modules are wrapped in `b2b--*` class containers                      |
| Modules reuse the template style of Shopware       |                                                                                      |
| CSS Selectors                                      | Three levels of selector depth as max                                                |
| Twig Blocks                                        | `{% block b2b_* %}{% endblock %}` empty blocks are in one line    |                                                                                     |
| JavaScript                                         | The B2B Suite is written in TypeScript                                               |
| Storefront plugins                                 | File names end with \*.plugin.ts                                                      |
| Interfaces                                         | File names start with `I`, e.g., `IAjaxPanelEvent.ts`                                |
| Snippets                                           | The root snippet key is `b2b`                                                        |

## Entity naming conventions

Certain domain entities, such as Contact, Contingent Rule, and others, have different naming conventions in the B2B UI and the codebase. To make things easier to understand, here is a comparison between these entities' B2B UI to their corresponding names in English Storefronts:

| English term (Display name)                        | B2B-Suite term (Entity name)                      |
|----------------------------------------------------|---------------------------------------------------|
| Company administrator                              | Debtor                                            |
| Employee                                           | Contact                                           |
| Cart details                                       | Positions                                         |
| Quick order                                        | Fastorder                                         |
| Quote                                              | Offers                                            |
| Purchase restriction                               | Contingent                                        |
| Order restriction                                  | Contingent rule                                   |
| Product restriction                                | Contingent restrictions                           |

You can use the table above as a reference to identify a domain entity in the codebase when working with the B2B storefront.

---

---
url: /docs/v6.5/products/extensions/b2b-suite/concept/basic-conventions.md
---

# Basic Conventions

## Codebase conventions

List of naming conventions the B2B Suite complies to:

| Group                                              | Practice                                                                             |
|----------------------------------------------------|--------------------------------------------------------------------------------------|
| DI Container                                       | All container ids look like `b2b_*.*`                                                |
| The first asterisk is the component name           |                                                                                      |
| The second asterisk is a class name abbreviation   |                                                                                      |
| Database                                           | All table names start with `b2b_`                                                    |
| All table names are in singular                    |                                                                                      |
| All field and table names are in snake case        |                                                                                      |
| Attributes                                         | All attribute names start with `swag_b2b_`                                           |
| Subscriber                                         | All subscriber methods are named in accordance with their function, not to the event |
| Tests                                              | All test methods are in snake case                                                   |
| All test methods start with `test_`                |                                                                                      |
| Templates                                          | All new layout modules are wrapped in `b2b--*` class containers                      |
| Modules reuse the template style of Shopware       |                                                                                      |
| CSS Selectors                                      | Three levels of selector depth as max                                                |
| Twig Blocks                                        | `{% block b2b_* %}{% endblock %}` empty blocks are in one line    |                                                                                     |
| JavaScript                                         | The B2B Suite is written in TypeScript                                               |
| Storefront plugins                                 | File names end with \*.plugin.ts                                                      |
| Interfaces                                         | File names start with `I`, e.g., `IAjaxPanelEvent.ts`                                |
| Snippets                                           | The root snippet key is `b2b`                                                        |

## Entity naming conventions

Certain domain entities, such as Contact, Contingent Rule, and others, have different naming conventions in the B2B UI and the codebase. To make things easier to understand, here is a comparison between these entities' B2B UI to their corresponding names in English Storefronts:

| English term (Display name)                        | B2B-Suite term (Entity name)                      |
|----------------------------------------------------|---------------------------------------------------|
| Company administrator                              | Debtor                                            |
| Employee                                           | Contact                                           |
| Cart details                                       | Positions                                         |
| Quick order                                        | Fastorder                                         |
| Quote                                              | Offers                                            |
| Purchase restriction                               | Contingent                                        |
| Order restriction                                  | Contingent rule                                   |
| Product restriction                                | Contingent restrictions                           |

You can use the table above as a reference to identify a domain entity in the codebase when working with the B2B storefront.

---

---
url: /docs/v6.6/products/extensions/b2b-suite/concept/basic-conventions.md
---

# Basic Conventions

## Codebase conventions

List of naming conventions the B2B Suite complies to:

| Group                                              | Practice                                                                             |
|----------------------------------------------------|--------------------------------------------------------------------------------------|
| DI Container                                       | All container ids look like `b2b_*.*`                                                |
| The first asterisk is the component name           |                                                                                      |
| The second asterisk is a class name abbreviation   |                                                                                      |
| Database                                           | All table names start with `b2b_`                                                    |
| All table names are in singular                    |                                                                                      |
| All field and table names are in snake case        |                                                                                      |
| Attributes                                         | All attribute names start with `swag_b2b_`                                           |
| Subscriber                                         | All subscriber methods are named in accordance with their function, not to the event |
| Tests                                              | All test methods are in snake case                                                   |
| All test methods start with `test_`                |                                                                                      |
| Templates                                          | All new layout modules are wrapped in `b2b--*` class containers                      |
| Modules reuse the template style of Shopware       |                                                                                      |
| CSS Selectors                                      | Three levels of selector depth as max                                                |
| Twig Blocks                                        | `{% block b2b_* %}{% endblock %}` empty blocks are in one line    |                                                                                     |
| JavaScript                                         | The B2B Suite is written in TypeScript                                               |
| Storefront plugins                                 | File names end with \*.plugin.ts                                                      |
| Interfaces                                         | File names start with `I`, e.g., `IAjaxPanelEvent.ts`                                |
| Snippets                                           | The root snippet key is `b2b`                                                        |

## Entity naming conventions

Certain domain entities, such as Contact, Contingent Rule, and others, have different naming conventions in the B2B UI and the codebase. To make things easier to understand, here is a comparison between these entities' B2B UI to their corresponding names in English Storefronts:

| English term (Display name)                        | B2B-Suite term (Entity name)                      |
|----------------------------------------------------|---------------------------------------------------|
| Company administrator                              | Debtor                                            |
| Employee                                           | Contact                                           |
| Cart details                                       | Positions                                         |
| Quick order                                        | Fastorder                                         |
| Quote                                              | Offers                                            |
| Purchase restriction                               | Contingent                                        |
| Order restriction                                  | Contingent rule                                   |
| Product restriction                                | Contingent restrictions                           |

You can use the table above as a reference to identify a domain entity in the codebase when working with the B2B storefront.

---

---
url: /docs/v6.5/resources/guidelines/code/core/benchmarks.md
---
::: info
This document represents core guidelines and has been mirrored from the core in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/coding-guidelines/core/benchmarks.md)
:::

# Benchmarks

Since the 6.4.11 version, we have run continuous performance benchmarks via [locust.io](https://locust.io/). We want to extend these benchmarks continuously. You can find the sources in the [src/Core/Devops/Locust](https://github.com/shopware/shopware/tree/trunk/src/Core/DevOps/Locust) folder. You can find all the information on setting up and running these tests in the [README.md](https://github.com/shopware/shopware/blob/trunk/src/Core/DevOps/Locust/README.md).

If you develop a new feature that impacts the store (storefront and/or store API), this functionality must be performance tested. It is not enough to rest on the fact that performance tests already exist and hope they will test it somehow. New functionality usually also needs a configuration which is not inside the existing mysqldump.

## Extend `setup.php`

The [`setup.php`](https://github.com/shopware/shopware/blob/trunk/src/Core/DevOps/Locust/setup.php) exports a fixture set which you can use inside the locust python files. Getting the data on demand via API would also be possible, but this would put additional load on the server and possibly falsify the results.

So if you need additional data to test your feature, you can write other .json files here. These will then be parsed in the [Context](https://github.com/shopware/shopware/blob/trunk/src/Core/DevOps/Locust/common/context.py) class and made available globally.

## Extend the scenarios

We have defined several [scenarios](https://github.com/shopware/shopware/tree/trunk/src/Core/DevOps/Locust/scenarios) in locust.

You have to customize the following scenarios under the following conditions:

* API-benchmark.py > Here, we test the performance of our API for ERP imports.
  * API Write / Sync processes extended
  * Indexing process of products or categories
* integration-benchmark.py > In this scenario, we test everything
  * Always
* Nvidia-benchmark.py > In this scenario, we test many orders per second
  * Changes to the order process
  * Changes to `available_stock`
  * Changes to the product detail page
* store-API-benchmark.py > In this scenario, we test our store API routes
  * If you have added a new store API route
  * If you have added a function to an existing store API
* storefront-benchmark.py > Here, we test only storefront routes without a shopping cart
  * If you have added new functions to the storefront

## Extend mysqldump

If the new feature needs new data, the mysqldump of the demo-data environment must be adjusted. For example, if you implement a new CMS element, it is essential, that this element is used somewhere. Otherwise, this element will never be considered when running the performance tests.

Since the mysqldump is static and defined as a snapshot on our servers, it is not easy to manipulate it.

Therefore, you should build a script that can manipulate an existing system to add the necessary data for you.
Let's take product ratings as an example. In the script, you would simply add ten ratings to each product, which are randomly generated.

Test the script locally and build your locust scenarios based on the results. Once you have met all criteria for a merge, create a merge request and add the @ct-core team as reviewers. You should put the script to adjust the dump in the merge request description.

@ct-core will do a review of your script and your performance tests. Once the review is successful, please contact @ct-core team to spawn the mysql server. Afterwards you can manipulate the dump and @ct-core create a new snapshot.

Since we also test other dumps, you must program the locust scenarios so that the results are not affected if your data (fixtures) does not exist.

---

---
url: /docs/guides/development/testing/e2e-playwright/best-practices.md
---

# Best practices

A good first read about this is the official [playwright best practices page](https://playwright.dev/docs/best-practices). It outlines the essential practices to follow when writing acceptance tests for Shopware.

The most important part is [test isolation](https://playwright.dev/docs/best-practices#make-tests-as-isolated-as-possible), which helps to prevent flaky behavior and enables the test to be run in parallel and on systems with an unknown state.

## Dos

* Use the [`TestDataService`](https://github.com/shopware/acceptance-test-suite/blob/trunk/src/services/TestDataService.ts) for creating test data
* Create all the data that is required for your test case. That includes sales channels, customers, and users (the page fixtures handle most of the common use cases)
* Clean it up if you don't need it anymore. The `TestDataService` will take care of it if you used it to create the test data
* If you need specific settings for your test, set them explicitly for the `user/customer/sales` channel
* Directly jump to the detail pages with the ID of the entities you have created. If that is not possible, use the search with a unique name to filter lists to just that single entity
* If you need to skip tests, comment any relevant github issues as part of the skip method: `test.skip('Blocked by https://[...])`

## Don'ts

* Do not expect lists/tables only to contain one item; leverage unique IDs/names to open or find your entity instead
* Same with helper functions, do not expect only to get one item back from the API. Always use unique criteria for the API call
* Avoid unused fixtures. If you request a fixture but don't use any data from the fixture, the test or fixture should be refactored
* Do not depend on implicit configuration and existing data. Examples:
  * rules
  * flows
  * categories
* Do not expect the shop to have the defaults `en_GB` and `EUR`
* Do not change global settings (sales channel is ok, because we created it). Everything in "Settings" that is not specific to a sales channel (tax, search, etc.)

## Sensitive Data / Credentials

Sometimes you have to provide sensitive data or credentials for your tests to run, for example, credentials for a sandbox environment for a payment provider. Apart from avoiding having those credentials in the actual code, you should also prevent them from appearing in logs or traces. To achieve this, you should outsource steps involving sensitive data to a separate project that runs before the actual test project and disable traces for it.

**Example**

```Typescript
projects: [
    // Init project using sensitive data
 {
      name: 'init', 
      testMatch: /.*\.init\.ts/,
      use : {trace : 'off'}
 },

 {
      // actual test project
      // [...]
      dependencies: ['init'],
 }]
```

## Debugging API calls

Debugging API calls may not be an easy task at first glance, because if the call you made returns an error, it is not directly visible to you. But you can use the `errors[]` array of the response and log that on the console.

**Example**

```Typescript
const response = await this.AdminApiClient.post('some/route', {
    data: {
        limit: 1,
        filter: [
 {
                type: 'equals',
                field: 'someField',
                value: 'someValue',
 },
 ],
 },
});
const responseData = await response.json();
console.log(responseData.errors[0]);
```

## Code contribution

You can contribute to this project via its [official repository](https://github.com/shopware/acceptance-test-suite/) on GitHub.

This project uses [conventional commits](https://www.conventionalcommits.org/en/v1.0.0/). Make sure to form your commits accordingly to the spec.

---

---
url: /docs/products/tools/mcp-server/best-practices.md
---

# Best Practices

Lessons learned building Shopware's MCP server. These principles apply to any MCP extension (plugin, bundle, or app) that exposes a complex domain to AI agents.

## Tools

[Tools](./mcp-concepts.md#tools) are the primary surface area of an MCP server. Getting their design right has the biggest impact on agent reliability.

### Design for outcomes, not operations

Design tools around what the agent wants to achieve, not around raw CRUD operations.

**Instead of** exposing generic create/read/update/delete tools and expecting the agent to chain them correctly, wrap common multi-step workflows into a single tool with flattened parameters.

For example, `shopware-order-state` wraps order, transaction, and delivery state changes into a single call with `orderNumber` and per-entity action parameters, instead of requiring three or more separate state-machine tool calls.

**When to add an outcome tool:** If an agent needs three or more tool calls to accomplish a single user intent, that workflow is a candidate for a dedicated outcome tool.

### Keep the generic tools too

Outcome tools cover the 80% that is common. The generic entity tools (`shopware-entity-search`, `shopware-entity-upsert`, `shopware-entity-delete`) cover the remaining 20%: edge cases, ad-hoc queries, and entities without dedicated workflow tools. Do not remove the generic layer when you add higher-level tools.

### Flatten parameters

AI agents struggle with deeply nested JSON structures. Every level of nesting increases hallucination risk. Tool parameters should be flat strings, numbers, and booleans wherever possible.

If complex input is unavoidable (e.g., search criteria), accept it as a JSON string parameter and parse it server-side. This gives the agent a single string to construct rather than a nested object tree.

### Default to dryRun=true on all write tools

All write tools should default to `dryRun=true`. This lets the agent preview the result before committing and catches errors early. The agent calls again with `dryRun=false` to persist.

Agents tend to be overconfident; they will call a write tool on the first attempt without verifying parameters. A dry-run default forces a two-step pattern that catches mistakes before they cause damage.

### Validate inputs before writing

If a tool accepts a name that maps to an internal enum, registry, or state machine (event names, action names, state transitions), validate it before writing. The database may silently accept invalid values that produce broken data at runtime.

### Keep allowlists and toolsets focused

Shopware uses progressive discovery so a fresh session advertises only three meta-tools. The agent searches the allowed catalogue and enables additional toolsets as needed. This bounds the startup context even when many tools are installed.

Allowlists still matter. They define the catalogue that discovery can search and remain the call-time security boundary. The practical approach is **one integration per persona or job**, each with a scoped tool allowlist. A persona is a specific role with a specific job; it only includes the tools that role actually needs. For example:

* **Merchant integration:** order state, system config, media upload, theme config. What a store manager needs day-to-day.
* **Developer integration:** entity search, entity schema, aggregate, system config read. What a developer or CI pipeline needs for inspection and debugging.
* **App-specific integration:** only the tools relevant to a specific workflow or external system.

Each integration can discover and call only its allowed tools, resources, and prompts. Treat the allowlist, system prompt, tool groups, and exposed resources together as **product quality**, not just security. A focused catalogue improves search relevance and limits what the agent can enable. Configure allowlists under **Settings → Integrations → Edit MCP Allowlist** (per integration) and **Settings → Users & Permissions → \[user] → MCP tool allowlist** (per user).

Both modals group tools by their tool group, so allowing or denying a complete toolset is a single click. That makes the group a design decision, not just metadata: a group that mixes read-only inspection with destructive writes forces operators to choose between too much and too little.

Every enabled tool consumes tokens from the agent's context window throughout the rest of the session. Each tool schema (name, description, parameters) costs roughly **550–1,400 tokens** depending on complexity. Some clients also enforce hard caps on the number of tools. Keep toolsets cohesive so an agent can enable one relevant group without loading unrelated schemas.

When everything is enabled, the modal also shows inline privilege gaps, meaning the integration's role does not actually cover what its allowlist exposes:

Strategies to reduce tool count within a single integration:

* Use an `action` parameter to multiplex related operations into one tool (e.g., `shopware-theme-config` with `action: "get" | "update"`)
* Use resources instead of tools for static reference data
* Assign tools from plugins and Symfony bundles to focused groups with `#[McpToolGroup]`

### Keep responses compact

Tool responses are injected directly into the agent's context window, so large responses consume a significant portion of the token budget.

When a response exceeds 100 KB, `McpToolResponse` does not inline it. Instead, it stores the payload in a session-scoped cache and returns a `shopware://tool-result/{uuid}` URI in `_meta.resourceUri`. The agent can fetch the full content via `resources/read`. The `_meta` block also includes `responseSize` and `note`, which explain why the result was deferred. For responses above 20 KB (but under the cap), `_meta.responseSize` is included as a size hint so the agent can learn to use tighter parameters next time.

The goal is still to keep responses small. Deferred resources still cost tokens when the agent fetches them, and some clients may not automatically follow up.

* **Separate entity rows from aggregations.** Aggregations (especially `terms` or `date-histogram` with many buckets) can produce thousands of entries. Mixing them with entity rows in a single response compounds the problem — use `shopware-entity-aggregate` for aggregations and `shopware-entity-search` for records; never both in a single tool call.
* **Use `McpEntityIncludes` in plugin tools.** If your tool returns DAL entity data via `JsonEntityEncoder`, use the `McpEntityIncludes` trait. It automatically strips unrequested associations, thumbnails, and translated duplicates, keeping responses compact without manual field filtering.
* **Paginate large result sets.** Return a bounded `limit` and let the agent increment `page` rather than returning everything at once.

### Use consistent response shapes

Extend `McpToolResponse` to get consistent `{"success": true, "data": ..., "_meta": ...}` and `{"success": false, "error": "..."}` envelopes. Agents learn one pattern and apply it everywhere.

### Write tool descriptions for agent routing

The `description` field on `#[McpTool]` is the only signal the agent uses to pick between similar tools. Write it for routing accuracy, not as documentation.

**Lead with the trigger phrases the user will say.** Agents pattern-match on user wording. A description that opens with "The correct tool for count, sum, average, and other aggregate questions" correctly routes when the user asks "how many products?" A description that opens with "Run aggregations over any Shopware entity" does not.

**Use negative phrasing to break ties.** When two tools share keywords (e.g., `shopware-entity-search` and `shopware-entity-aggregate` both work on entities), the agent will gravitate to the more concrete description. Spell out the contrast directly:

> "Use this — NOT shopware-entity-search — for any 'how many', 'total value', or 'average' query. The search tool's `_meta.total` is pagination metadata, not a reporting count."

**Do not reference other tools as prerequisites unless they truly are.** A description that ends with "Use shopware-foo-read to check current values first" trains the agent to call the read tool even when it should not. If a tool is genuinely a prerequisite, declare it with `#[McpToolDependsOn]` instead of with prose.

**Mention the use cases the user will name.** If a prompt is "upload this image as a product cover", the description should contain the phrase "product cover" — and clarify that no extra parameter is required to satisfy that case. Otherwise, the agent infers it cannot fulfill the request and returns no tool selection.

**Make required parameters truly required.** Leave a parameter without a PHP default only if every prompt that should call this tool will include it. If the parameter is something the user rarely provides (e.g., a sales channel UUID or a tax ID), set it to `''` or `null` and validate it in the method. Required-but-missing parameters cause some agents to refuse the tool call entirely rather than ask the user.

**Test descriptions with an LLM, not just a code reviewer.** A description that reads well to a developer can route badly. Run a small fixture set through the agent you target (Claude, GPT-4o) and compare expected versus selected tool. The cost of a routing failure is that the user does not get the tool they wanted; the cost of running the evaluation is a few hundred tokens.

**Use automated checks as the regression net for descriptions and prompt wording.** Tool descriptions, system-prompt recipes, and resource lists are written in natural language. Changes to any of them can silently break routing on prompts that used to work. Maintain a small library of representative prompts ("how many products?", "ship order 10042", "upload this image as a product cover") with the expected tool selection, and run it before merging description changes the same way you run unit tests before merging behavior changes.

### Tool descriptions are baked into the DI container

Shopware reads `#[McpTool]` attributes at container compile time. Changing a description requires `bin/console cache:clear` for the new text to reach the MCP endpoint. If your changes do not appear in `bin/console debug:mcp` or `tools/list`, clear the container cache first.

### Use the system prompt as the disambiguation override layer

Some routing decisions cannot be solved at the description level alone — for example, when two tools have legitimate overlap in keywords or when an unusual phrasing is common in your domain. Use the `shopware-context` prompt (or your own `#[McpPrompt]`) for these:

```text
### Counting and aggregating (entity-aggregate vs entity-search)
- "How many products are there?" → shopware-entity-aggregate (count aggregation), NOT entity-search
- "List all orders from the last 7 days" → shopware-entity-search (date-range filter, NOT aggregate)
- Rule: any question asking for a NUMBER (count, total, sum, average) → always shopware-entity-aggregate
- Rule: any question asking to LIST, SHOW, or RETRIEVE records → always shopware-entity-search
```

The system prompt is fetched fresh on every session, so updates take effect without a cache clear. Tool descriptions are static and ship with the integration; the system prompt is the place to encode evolving guidance.

### Write actionable error messages

When a tool fails, the error message is the agent's only signal for recovery. Make it actionable:

**Bad:** `"Error: not found"`

**Good:** `"Order not found. Verify the order number with shopware-entity-search on the 'order' entity, or provide an orderId (UUID) instead."`

## Resources

[Resources](./mcp-concepts.md#resources) expose stable reference data without consuming tool-call budget.

### Use resources for reference data

Use MCP resources for lists of valid values and configuration lookups:

* Entity names: `shopware://entities`
* Valid state machine transitions: `shopware://state-machines`
* Sales channel IDs: `shopware://sales-channels`
* Business event names: `shopware://business-events`

Without resources, the agent would need a tool call to discover each of these, adding latency and consuming tool-call budget.

### Keep resources small

Resources are loaded into the agent's context. A resource that returns thousands of lines defeats the purpose. If a data set is large or dynamic, use a tool with search and filter parameters instead.

### When to use a resource vs. a tool

Use a **resource** when:

* The data is read-only and identified by a stable URI
* No agent guidance is needed about when or how to use it

Use a **tool** when:

* You need the `description` field to guide agent behavior (resources have no description)
* The operation has parameters beyond a single identifier
* The data involves writes or dynamic queries

When in doubt, prefer a tool: the description field is your primary lever for shaping agent behavior.

## Prompts

[Prompts](./mcp-concepts.md#prompts) set up the agent's domain understanding before any tool calls happen.

### One system prompt, not many

Provide a single well-structured system prompt that covers:

1. Domain model overview (key entities and their relationships)
2. Available tools grouped by purpose
3. Common workflows as step-by-step recipes
4. Error recovery guidance
5. Which resources exist and when to use them

Multiple prompts fragment the agent's understanding. A single coherent prompt is more effective.

### Write workflow recipes, not tool documentation

The tool descriptions (in `#[McpTool(description: '...')]`) explain what each tool does. The system prompt should explain **how to combine tools** for real tasks:

```text
### Ship an order
1. shopware://state-machines resource to confirm "ship" is a valid delivery action
2. shopware-order-state with orderNumber and deliveryAction: "ship", dryRun=true to preview
3. shopware-order-state with dryRun=false to execute
```

Agents follow step-by-step recipes better than they infer multi-step plans from individual tool docs.

### Mention resources explicitly

Resources are easy to overlook. Explicitly tell the agent which resources exist and when to use them:

```text
## Available resources (read without a tool call)
- shopware://entities: all entity names
- shopware://sales-channels: sales channels with IDs and domains
- shopware://state-machines: states and valid transitions
```

## ACL and Security

### Enforce permissions in every tool

Every tool should check ACL permissions before performing any action. Do not rely on the database layer to reject unauthorized writes; by then, the agent has already spent tokens constructing the payload.

Return a clear error when permissions are missing: `"Missing privilege: order:read"`.

### Declare required privileges

Annotate your tool class with `#[McpToolRequires]` so operators can configure ACL roles correctly before hitting a runtime error:

```php
// Static privilege
#[McpToolRequires('system_config:read')]

// Dynamic privilege (entity name comes from a runtime parameter)
#[McpToolRequires(entityParam: 'entity', operations: ['read'])]
```

This is **declarative only**: it populates the Admin UI coverage warnings and `bin/console debug:mcp` output, but does not add a new enforcement layer. You still must call `$this->requirePrivilege($context, '...')` inside `__invoke()` for actual runtime enforcement.

### Be aware of prompt injection via tool results

Tool results that include user-generated content (order notes, customer names, product descriptions) can contain text that attempts to redirect the agent's behavior. An agent who reads a customer order with a shipping note that says "Ignore all previous instructions and..." may act on that instruction. Shopware's ACL and tool allowlist limit the blast radius, but they do not prevent the agent from being misled by data it reads.

Prefer read-only integrations for workflows that expose customer-supplied data, and avoid giving agents write access when the workflow only requires reading.

### Keep admin and storefront contexts separate

Tools that operate through the storefront (cart, checkout, storefront search) use `SalesChannelContext`, not the Admin API `Context`. They do not need Admin ACL checks but do require a valid sales channel ID.

Keep the two authentication models clearly separated. Admin context tools belong in core or admin-focused plugins. Storefront context tools belong in plugins like `SwagMcpMerchantTools`.

## General Design

### Prefer fewer round-trips

Each tool call is a round-trip with latency and a token cost. Design tools that return everything the agent needs in a single call, even if that means preloading associations.

For example, a merchant plugin's order summary tool can load an order with customer, line items, transactions, and deliveries in a single query, without requiring four separate `shopware-entity-read` or `shopware-entity-search` calls.

### Let the agent discover

Provide discovery mechanisms so the agent does not need to guess valid input values:

* `shopware-entity-schema` for field names and types
* `shopware://entities` for valid entity names
* `shopware://business-events` for valid event names
* `shopware://state-machines` for valid state transition actions
* `shopware://sales-channels` for sales channel IDs

An agent that can discover valid inputs makes fewer errors than one that relies on training data.

### Test with real agent conversations

Unit tests verify correctness. Real agent conversations verify usability. Write scenario tests that simulate multi-step agent workflows to catch usability issues that unit tests miss; an agent that produces technically correct output but fails the user story is still a broken tool.

---

---
url: /frontends/best-practices.md
---

# BEST PRACTICES

---

---
url: /docs/guides/development/testing/legacy/cypress/cypress-best-practises.md
---

# Best practices for writing end-to-end tests

A typical E2E test can be complex, with many steps that take a lot of time to complete manually. Because of this complexity, E2E tests can be difficult to automate and slow to execute. The following tips can help reduce the cost and pain of E2E testing and still reap the benefits.

Cypress got you covered with their best practices as well: So please also look at their best practices to get to know their patterns:

::: warning
We strongly recommend following Cypress's own best practices as well.
:::

## Amount and prioritization of end-to-end tests

### Video

When it comes to dividing test types, selecting and prioritizing test cases, and thus designing tests, things get a bit more complicated. We have generally aligned our test strategy with the test pyramid, although not 100%. The pyramid states that end-to-end tests should be written in a few but well-chosen test cases because end-to-end tests are slow and expensive.

At [Shopware Community Day](https://scd.shopware.com/en-US/) 2020, we gave a talk on how we approach automated testing in Shopware, how far we have come on this journey, and what we have gained so far:

To sum it up briefly, the end-to-end tests are slow and thus expensive to maintain. That is why we need a way to prioritize our test cases.

### When should I write an end-to-end test

::: danger
Cover every possible workflow with E2E tests.
:::

::: tip
Use proper prioritization to choose test cases covered by E2E tests.
:::

Due to time constraints, it is not advisable to cover every available workflow. The following criteria may help you with that:

* **Cover the most general, most used workflows of a feature**, e.g., CRUD operations. The term "[happy path](https://en.wikipedia.org/wiki/Happy_path)" describes those workflows quite well.
* **Beware the critical path**: Cover those workflows with E2E tests, which are the most vulnerable and would cause the most damage if broken.
* **Avoid duplicate coverage**: E2E tests should only cover what they can, usually big-picture user stories (workflows) that contain many components and views.
  * Sometimes, unit tests are better suited. For example, use an E2E test to test your application's reaction to a failed validation, not the validation itself.

## Workflow-based end-to-end tests

::: danger
Write the E2E test as you would write unit tests.
:::

::: tip
Writing E2E tests in a "workflow-based" manner means writing tests that describe a real user's workflow, just as a real user would use your application.
:::

A test should be written "workflow-based" - We like to use this word very much because it is simply apt for this purpose. You should always keep your persona and goal of an E2E test in mind. The test is then written from the user's point of view, not from the developer's point of view.

## Structure and scope

### Test scope

::: danger
Write long E2E tests covering lots of workflows and use cases.
:::

::: tip
Keep tests as simple as possible. Only test the workflow you explicitly want to test. Ideally, use **one test for one workflow**.
:::

The second most important thing is to test the workflow you explicitly want to test. Any other steps or workflows to get your test running should be performed via API operations in the `beforeEach` hook, since we don't want to test them more than once. For example, if you want to test the checkout process, you shouldn't do all the steps, like creating the sales channel, products, and categories, although you need them to process the checkout. Use the API to create these things, and let the test just do the checkout.

You need to focus on the workflow to be tested to ensure minimum test runtimes and to get a valid result of your test case if it fails. For this workflow, you have to think like the end-user would do - Focus on the usage of your feature, not the technical implementation.

Other examples of steps or workflows to cut off the actual tests are:

* The routines that should only provide the data we need: Just use test fixtures to create this data to have everything available before the test starts.
* Logging in to the Administration: You need it in almost every Administration test, but writing it in all tests is pure redundancy and way more error sensitive.

::: info
This [scope practice](https://docs.cypress.io/guides/references/best-practices.html#Organizing-Tests-Logging-In-Controlling-State) is also mentioned in the Cypress best practices.
:::

### Focus on stability first

::: danger
Design your tests so they depend on each other, performing many write operations without removing the corresponding data.
:::

::: tip
Keep tests isolated, enable them to run independently, and restore a clean installation between tests.
:::

It is important to focus on stability as the most important asset of a test suite. A flaky test like this can block the continuous deployment pipeline, making feature delivery slower than it needs to be. Moreover, imagine the following case: Tests that fail to deliver deterministic results. Those flaky tests are problematic because they won't show valid results, making them useless. After all, you wouldn't trust one any more than you would trust a liar. If you want to find out more on that topic, including solutions, please take a look at this article:

This was one of the reasons you need stable tests to create value. To achieve that, you have several possibilities. We will introduce you to some of them in the following paragraphs.

Let's start with an easy strategy. Keep tests as simple as possible, and avoid a lot of logic in each one. Think about it this way: the more you do in a test, the more you can go wrong. In addition, by avoiding big tests, you avoid causing a load on your application and resource leaks in your environment.

When planning your test cases and structure, always keep your tests isolated from other tests so they can be run in an independent or random order. Don't ever rely on previous tests. You need to test specs in isolation to take control of your application’s state. Every test is supposed to run independently of any other tests. This is crucial to ensure valid test results. You can realize these using test fixtures to create all the data you need beforehand and take care of the cleanup of your application using an appropriate reset method.

## Choosing selectors

::: danger
Choose fuzzy selectors that are prone to change, e.g., XPath.
:::

::: tip
Use selectors that won't change often.
:::

XPath selectors rely heavily on text, which can change quickly. Please avoid using them as much as possible. If you work on the Shopware platform and notice that one selector is missing or not unique enough, just add another one in the form of an additional class.

### Avoid framework-specific selectors

::: danger
Choose framework-specific syntax as a selector prone to change, e.g., `.btn-primary`.
:::

::: tip
Use individual selectors that won't often change, e.g., `.btn-buy`.
:::

Using selectors that rely on a framework-specific syntax can be unstable because the framework selectors are prone to change. Instead, you should use individual selectors, which are less likely to change.

```html
<button class="btn btn-primary btn-buy">Add to cart</button>
```

```javascript
// ✗ Avoid using framework-specific syntax from Bootstrap as a selector.
cy.get('.btn.btn-primary').click();

// ✓ Instead, you should use a shopware-specific class like `.btn-buy`.
// (This also remains stable when the button variant is changed to, e.g., `.btn-secondary`.)
cy.get('.btn-buy').click();
```

```html
<button
    data-toggle="modal"
    data-target="#exampleModal"
    class="btn btn-primary btn-open-settings">
 Open settings modal
</button>
```

```javascript
// ✗ Avoid using framework-specific syntax from Bootstrap as a selector.
cy.get('[data-toggle="modal"]').click();

// ✓ Instead, you should use a shopware-specific class like `.btn-open-settings`.
cy.get('.btn-open-settings').click();
```

```html
<div class="custom-control custom-checkbox">
  <label 
      for="tos" 
      class="checkout-confirm-tos-label custom-control-label">
 I have read and accepted the general terms and conditions.
  </label>
</div>
```

```javascript
// ✗ Avoid using framework-specific syntax from Bootstrap as a selector.
cy.get('.custom-checkbox label').click();

// ✓ Instead, you should use a shopware-specific class like `.checkout-confirm-tos-label`.
cy.get('.checkout-confirm-tos-label').click();
```

If no suitable selectors are available, please add descriptive classes or IDs to your desired elements.

## Waiting in E2E tests

::: danger
Waiting for arbitrary time periods, e.g., using `cy.wait(500)`
:::

::: tip
Use route aliases or assertions to guard Cypress from proceeding until an explicit condition is met.
:::

Never use fixed waiting times in the form of `.wait(500)` or similar. Using Cypress, you never need to do this. Cypress has a built-in retryability in almost every command, so you don't need to wait, e.g., if an element already exists. If you need more than that, we've got you covered. Wait for changes in the UI instead, notifications, API requests, etc., via the appropriate assertions. For example, if you need to wait for an element to be visible:

```javascript
cy.get('.sw-category-tree').should('be.visible');
```

Another useful way to wait in the Administration is to use Cypress's [network requests](https://docs.cypress.io/app/guides/network-requests). Here you can let the test wait for a successful API response:

```javascript
cy.server();

// Route POST requests with matching URL and assign an alias to it
cy.route({
    url: '/api/search/category',
    method: 'post'
}).as('getData');

// Later, you can use the alias to wait for the API response
cy.wait('@getData').then((xhr) => {
    expect(xhr).to.have.property('status', 200);
});
```

::: info
This [best practice](https://docs.cypress.io/guides/references/best-practices#Unnecessary-Waiting) is also mentioned in the Cypress best practices. Actually, avoiding flakiness is a general best practice.
:::

## Cypress commands and their queue

::: danger
Using vanilla JavaScript logic alongside Cypress commands without further caution
:::

::: tip
If you need vanilla Javascript in your test, wrap it in a Cypress `then` or build a custom command to get it queued.
:::

Cypress commands are asynchronous and get queued for execution at a later time. During execution, subjects are yielded from one command to the next, and a lot of helpful Cypress code runs between each command to ensure everything is in order.

This won't happen with Vanilla JS, though. It will be executed immediately. In the worst case, this difference can cause timing issues. So always wrap your vanilla JavaScript code into Cypress commands or `then` in order to make use of the Cypress command queue.

::: warning
Concerning Cypress `then`: Even though Cypress commands look like promises, they aren't completely the same. Head over to the [Cypress docs](https://docs.cypress.io/guides/core-concepts/introduction-to-cypress#Commands-Are-Not-Promises) for more information.
:::

---

---
url: /docs/v6.5/resources/guidelines/testing/e2e-best-practises.md
---

# Best practices for writing end-to-end tests

## Overview

A typical E2E test can be complex, with many steps that take a lot of time to complete manually. Because of this complexity, E2E tests can be difficult to automate and slow to execute. The following tips can help reduce the cost and pain of E2E testing and still reap the benefits.

Cypress got you covered with their best practices as well: So please also look at their best practices to get to know their patterns:

::: warning
We strongly recommend following Cypress own best practices as well.
:::

## Amount and prioritization of end-to-end tests

### Video

When it comes to dividing test types, selecting and prioritizing test cases, and thus designing tests, things get a bit more complicated. We have generally aligned our test strategy with the test pyramid, although not 100%. The pyramid states that end-to-end tests should be written in a few but well chosen test cases because end-to-end tests are slow and expensive.

At [Shopware Community Day](https://scd.shopware.com/en-US/) 2020, we gave a talk on how we approach automated testing in Shopware, how far we have come on this journey, and what we have gained so far:

To sum it up briefly, the end-to-end tests are slow and thus expensive to maintain. That is why we need a way to prioritize our test cases.

### When should I write an end-to-end test

::: danger
Cover every possible workflow with E2E tests.
:::

::: tip
Use proper prioritization to choose test cases covered by E2E tests.
:::

Due to running times, it is not advisable to cover every single workflow available. The following criteria may help you with that:

* **Cover the most general, most used workflows of a feature**, e.g., CRUD operations. The term "[happy path](https://en.wikipedia.org/wiki/Happy_path)" describes those workflows quite well.
* **Beware the critical path**: Cover those workflows with E2E tests, which are the most vulnerable and would cause the most damage if broken.
* **Avoid duplicate coverage**: E2E tests should only cover what they can, usually big-picture user stories (workflows) that contain many components and views.
  * Sometimes, unit tests are better suited. For example, use an E2E test to test your application's reaction to a failed validation, not the validation itself.

## Workflow-based end-to-end tests

::: danger
Write the E2E test as you would write unit tests.
:::

::: tip
Writing E2E tests in a "workflow-based" manner means writing the test describing a real user's workflow just like a real user would use your application.
:::

A test should be written "workflow-based" - We like to use this word very much because it is simply apt for this purpose. You should always keep your persona and goal of an E2E test in mind. The test is then written from the user's point of view, not from the developer's point of view.

## Structure and scope

### Test scope

::: danger
Write long E2E tests covering lots of workflows and use cases.
:::

::: tip
Keep tests as simple as possible. Only test the workflow you explicitly want to test. Ideally, use **one test for one workflow**.
:::

The second most important thing is to test the workflow you explicitly want to test. Any other steps or workflows to get your test running should be done using API operations in the `beforeEach` hook, as we don't want to test them more than once. For example, if you want to test the checkout process, you shouldn't do all the steps, like creating the sales channel, products, and categories, although you need them to process the checkout. Use the API to create these things and let the test just do the checkout.

You need to focus on the workflow to be tested to ensure minimum test runtimes and to get a valid result of your test case if it fails. For this workflow, you have to think like the end-user would do - Focus on the usage of your feature, not technical implementation.

Other examples of steps or workflow to cut off the actual tests are:

* The routines which should only provide the data we need: Just use test fixtures to create this data to have everything available before the test starts.
* Logging in to the Administration: You need it in almost every Administration test, but writing it in all tests is pure redundancy and way more error sensitive.

::: info
This [scope practice](https://docs.cypress.io/guides/references/best-practices.html#Organizing-Tests-Logging-In-Controlling-State) is also mentioned in Cypress best practices as well.
:::

### Focus on stability first

::: danger
Design your tests dependent on each other, doing lots of write operations without removing corresponding data.
:::

::: tip
Keep tests isolated, enable them to run independently, and restore a clean installation between tests
:::

It is important to focus on stability as the most important asset of a test suite. A flaky test like this can block the continuous deployment pipeline, making feature delivery slower than it needs to be. Moreover, imagine the following case: Tests that fail to deliver deterministic results: Those flaky test is problematic because they won't show valid results anymore, making them useless. After all, you wouldn't trust one any more than you would trust a liar. If you want to find out more on that topic, including solutions, please take a look at this article:

This was one of the reasons you need stable tests to create value. To achieve that, you have several possibilities. We will introduce you to some of them in the following paragraphs.

Let's start with some easy strategy. Keep tests as simple as possible, and avoid a lot of logic in each one. Think about it this way, the more you do in a test, the more you can go wrong. In addition, by avoiding big tests, you avoid causing load on your application and resource leaks in your environment.

When planning your test cases and structure, always keep your tests isolated from other tests so that they are able to be run in an independent or random order. Don't ever rely on previous tests. You need to test specs in isolation to take control of your application’s state. Every test is supposed to be able to run on its own and independent from any other tests. This is crucial to ensure valid test results. You can realize these using test fixtures to create all data you need beforehand and take care of the cleanup of your application using an appropriate reset method.

## Choosing selectors

::: danger
Choose fuzzy selectors which are prone to change, e.g. xpath.
:::

::: tip
Use selectors which won't change often.
:::

XPath selectors are quite fuzzy and rely a lot on the texts, which can change quickly. Please avoid using them as much as possible. If you work in Shopware platform and notice that one selector is missing or not unique enough, just add another one in the form of an additional class.

### Avoid framework specific selectors

::: danger
Choose framework specific syntax as a selector prone to change, e.g. `.btn-primary`.
:::

::: tip
Use individual selectors which won't often change, e.g., `.btn-buy`.
:::

Using selectors which rely on a framework specific syntax can be unstable because the framework selectors are prone to change. Instead, you should use individual selectors, which are less likely to change.

```html
<button class="btn btn-primary btn-buy">Add to cart</button>
```

```javascript
// ✗ Avoid using framework specific syntax from Bootstrap as a selector.
cy.get('.btn.btn-primary').click();

// ✓ Instead, you should use a shopware specific class like `.btn-buy`.
// (This also remains stable when the button variant is changed to, e.g., `.btn-secondary`.)
cy.get('.btn-buy').click();
```

```html
<button
    data-toggle="modal"
    data-target="#exampleModal"
    class="btn btn-primary btn-open-settings">
    Open settings modal
</button>
```

```javascript
// ✗ Avoid using framework specific syntax from Bootstrap as a selector.
cy.get('[data-toggle="modal"]').click();

// ✓ Instead, you should use a shopware specific class like `.btn-open-settings`.
cy.get('.btn-open-settings').click();
```

```html
<div class="custom-control custom-checkbox">
  <label 
      for="tos" 
      class="checkout-confirm-tos-label custom-control-label">
      I have read and accepted the general terms and conditions.
  </label>
</div>
```

```javascript
// ✗ Avoid using framework specific syntax from Bootstrap as a selector.
cy.get('.custom-checkbox label').click();

// ✓ Instead, you should use a shopware specific class like `.checkout-confirm-tos-label`.
cy.get('.checkout-confirm-tos-label').click();
```

If there are no suitable selectors available, please add descriptive classes or IDs for your desired elements.

## Waiting in E2E tests

::: danger
Waiting for arbitrary time periods, e.g., using `cy.wait(500)`
:::

::: tip
Use route aliases or assertions to guard Cypress from proceeding until an explicit condition is met.
:::

Never use fixed waiting times in the form of `.wait(500)` or similar. Using Cypress, you never need to do this. Cypress has a built-in retry-ability in almost every command, so you don't need to wait, e.g., if an element already exists. If you need more than that, we got you covered. Wait for changes in the UI instead, notifications, API requests, etc., via the appropriate assertions. For example, if you need to wait for an element to be visible:

```javascript
cy.get('.sw-category-tree').should('be.visible');
```

Another useful way for waiting in the Administration is using Cypress possibility to work with [network requests](https://docs.cypress.io/guides/guides/network-requests.html). Here you can let the test wait for a successful API response:

```javascript
cy.server();

// Route POST requests with matching URL and assign an alias to it
cy.route({
    url: '/api/search/category',
    method: 'post'
}).as('getData');

// Later, you can use the alias to wait for the API response
cy.wait('@getData').then((xhr) => {
    expect(xhr).to.have.property('status', 200);
});
```

::: info
This [best practice](https://docs.cypress.io/guides/references/best-practices#Unnecessary-Waiting) is also mentioned in Cypress best practices as well. Actually, it can be considered a general best practice to avoid flakiness.
:::

## Cypress commands and their queue

::: danger
Using vanilla JavaScript logic alongside cypress commands without further caution
:::

::: tip
If you need vanilla Javascript in your test, wrap it in a Cypress `then` or build a custom command to get it queued.
:::

Cypress commands are asynchronous and get queued for execution at a later time. During execution, subjects are yielded from one command to the next, and a lot of helpful Cypress code runs between each command to ensure everything is in order.

This won't happen with Vanilla JS, though. It will be executed immediately. In the worst case, this difference can cause timing issues. So always wrap your vanilla JavaScript code into Cypress commands or `then` in order to make use of Cypress command queue.

::: warning
Concerning Cypress `then`: Even though Cypress commands look like promises, they aren't completely the same. Head over to the [Cypress docs](https://docs.cypress.io/guides/core-concepts/introduction-to-cypress#Commands-Are-Not-Promises) for more information.
:::

---

---
url: /docs/v6.6/resources/guidelines/testing/e2e-best-practises.md
---

# Best practices for writing end-to-end tests

## Overview

A typical E2E test can be complex, with many steps that take a lot of time to complete manually. Because of this complexity, E2E tests can be difficult to automate and slow to execute. The following tips can help reduce the cost and pain of E2E testing and still reap the benefits.

Cypress got you covered with their best practices as well: So please also look at their best practices to get to know their patterns:

::: warning
We strongly recommend following Cypress own best practices as well.
:::

## Amount and prioritization of end-to-end tests

### Video

When it comes to dividing test types, selecting and prioritizing test cases, and thus designing tests, things get a bit more complicated. We have generally aligned our test strategy with the test pyramid, although not 100%. The pyramid states that end-to-end tests should be written in a few but well chosen test cases because end-to-end tests are slow and expensive.

At [Shopware Community Day](https://scd.shopware.com/en-US/) 2020, we gave a talk on how we approach automated testing in Shopware, how far we have come on this journey, and what we have gained so far:

To sum it up briefly, the end-to-end tests are slow and thus expensive to maintain. That is why we need a way to prioritize our test cases.

### When should I write an end-to-end test

::: danger
Cover every possible workflow with E2E tests.
:::

::: tip
Use proper prioritization to choose test cases covered by E2E tests.
:::

Due to running times, it is not advisable to cover every single workflow available. The following criteria may help you with that:

* **Cover the most general, most used workflows of a feature**, e.g., CRUD operations. The term "[happy path](https://en.wikipedia.org/wiki/Happy_path)" describes those workflows quite well.
* **Beware the critical path**: Cover those workflows with E2E tests, which are the most vulnerable and would cause the most damage if broken.
* **Avoid duplicate coverage**: E2E tests should only cover what they can, usually big-picture user stories (workflows) that contain many components and views.
  * Sometimes, unit tests are better suited. For example, use an E2E test to test your application's reaction to a failed validation, not the validation itself.

## Workflow-based end-to-end tests

::: danger
Write the E2E test as you would write unit tests.
:::

::: tip
Writing E2E tests in a "workflow-based" manner means writing the test describing a real user's workflow just like a real user would use your application.
:::

A test should be written "workflow-based" - We like to use this word very much because it is simply apt for this purpose. You should always keep your persona and goal of an E2E test in mind. The test is then written from the user's point of view, not from the developer's point of view.

## Structure and scope

### Test scope

::: danger
Write long E2E tests covering lots of workflows and use cases.
:::

::: tip
Keep tests as simple as possible. Only test the workflow you explicitly want to test. Ideally, use **one test for one workflow**.
:::

The second most important thing is to test the workflow you explicitly want to test. Any other steps or workflows to get your test running should be done using API operations in the `beforeEach` hook, as we don't want to test them more than once. For example, if you want to test the checkout process, you shouldn't do all the steps, like creating the sales channel, products, and categories, although you need them to process the checkout. Use the API to create these things and let the test just do the checkout.

You need to focus on the workflow to be tested to ensure minimum test runtimes and to get a valid result of your test case if it fails. For this workflow, you have to think like the end-user would do - Focus on the usage of your feature, not technical implementation.

Other examples of steps or workflow to cut off the actual tests are:

* The routines which should only provide the data we need: Just use test fixtures to create this data to have everything available before the test starts.
* Logging in to the Administration: You need it in almost every Administration test, but writing it in all tests is pure redundancy and way more error sensitive.

::: info
This [scope practice](https://docs.cypress.io/guides/references/best-practices.html#Organizing-Tests-Logging-In-Controlling-State) is also mentioned in Cypress best practices as well.
:::

### Focus on stability first

::: danger
Design your tests dependent on each other, doing lots of write operations without removing corresponding data.
:::

::: tip
Keep tests isolated, enable them to run independently, and restore a clean installation between tests
:::

It is important to focus on stability as the most important asset of a test suite. A flaky test like this can block the continuous deployment pipeline, making feature delivery slower than it needs to be. Moreover, imagine the following case: Tests that fail to deliver deterministic results: Those flaky test is problematic because they won't show valid results anymore, making them useless. After all, you wouldn't trust one any more than you would trust a liar. If you want to find out more on that topic, including solutions, please take a look at this article:

This was one of the reasons you need stable tests to create value. To achieve that, you have several possibilities. We will introduce you to some of them in the following paragraphs.

Let's start with some easy strategy. Keep tests as simple as possible, and avoid a lot of logic in each one. Think about it this way, the more you do in a test, the more you can go wrong. In addition, by avoiding big tests, you avoid causing load on your application and resource leaks in your environment.

When planning your test cases and structure, always keep your tests isolated from other tests so that they are able to be run in an independent or random order. Don't ever rely on previous tests. You need to test specs in isolation to take control of your application’s state. Every test is supposed to be able to run on its own and independent from any other tests. This is crucial to ensure valid test results. You can realize these using test fixtures to create all data you need beforehand and take care of the cleanup of your application using an appropriate reset method.

## Choosing selectors

::: danger
Choose fuzzy selectors which are prone to change, e.g. xpath.
:::

::: tip
Use selectors which won't change often.
:::

XPath selectors are quite fuzzy and rely a lot on the texts, which can change quickly. Please avoid using them as much as possible. If you work in Shopware platform and notice that one selector is missing or not unique enough, just add another one in the form of an additional class.

### Avoid framework specific selectors

::: danger
Choose framework specific syntax as a selector prone to change, e.g. `.btn-primary`.
:::

::: tip
Use individual selectors which won't often change, e.g., `.btn-buy`.
:::

Using selectors which rely on a framework specific syntax can be unstable because the framework selectors are prone to change. Instead, you should use individual selectors, which are less likely to change.

```html
<button class="btn btn-primary btn-buy">Add to cart</button>
```

```javascript
// ✗ Avoid using framework specific syntax from Bootstrap as a selector.
cy.get('.btn.btn-primary').click();

// ✓ Instead, you should use a shopware specific class like `.btn-buy`.
// (This also remains stable when the button variant is changed to, e.g., `.btn-secondary`.)
cy.get('.btn-buy').click();
```

```html
<button
    data-toggle="modal"
    data-target="#exampleModal"
    class="btn btn-primary btn-open-settings">
    Open settings modal
</button>
```

```javascript
// ✗ Avoid using framework specific syntax from Bootstrap as a selector.
cy.get('[data-toggle="modal"]').click();

// ✓ Instead, you should use a shopware specific class like `.btn-open-settings`.
cy.get('.btn-open-settings').click();
```

```html
<div class="custom-control custom-checkbox">
  <label 
      for="tos" 
      class="checkout-confirm-tos-label custom-control-label">
      I have read and accepted the general terms and conditions.
  </label>
</div>
```

```javascript
// ✗ Avoid using framework specific syntax from Bootstrap as a selector.
cy.get('.custom-checkbox label').click();

// ✓ Instead, you should use a shopware specific class like `.checkout-confirm-tos-label`.
cy.get('.checkout-confirm-tos-label').click();
```

If there are no suitable selectors available, please add descriptive classes or IDs for your desired elements.

## Waiting in E2E tests

::: danger
Waiting for arbitrary time periods, e.g., using `cy.wait(500)`
:::

::: tip
Use route aliases or assertions to guard Cypress from proceeding until an explicit condition is met.
:::

Never use fixed waiting times in the form of `.wait(500)` or similar. Using Cypress, you never need to do this. Cypress has a built-in retry-ability in almost every command, so you don't need to wait, e.g., if an element already exists. If you need more than that, we got you covered. Wait for changes in the UI instead, notifications, API requests, etc., via the appropriate assertions. For example, if you need to wait for an element to be visible:

```javascript
cy.get('.sw-category-tree').should('be.visible');
```

Another useful way for waiting in the Administration is using Cypress possibility to work with [network requests](https://docs.cypress.io/guides/guides/network-requests.html). Here you can let the test wait for a successful API response:

```javascript
cy.server();

// Route POST requests with matching URL and assign an alias to it
cy.route({
    url: '/api/search/category',
    method: 'post'
}).as('getData');

// Later, you can use the alias to wait for the API response
cy.wait('@getData').then((xhr) => {
    expect(xhr).to.have.property('status', 200);
});
```

::: info
This [best practice](https://docs.cypress.io/guides/references/best-practices#Unnecessary-Waiting) is also mentioned in Cypress best practices as well. Actually, it can be considered a general best practice to avoid flakiness.
:::

## Cypress commands and their queue

::: danger
Using vanilla JavaScript logic alongside cypress commands without further caution
:::

::: tip
If you need vanilla Javascript in your test, wrap it in a Cypress `then` or build a custom command to get it queued.
:::

Cypress commands are asynchronous and get queued for execution at a later time. During execution, subjects are yielded from one command to the next, and a lot of helpful Cypress code runs between each command to ensure everything is in order.

This won't happen with Vanilla JS, though. It will be executed immediately. In the worst case, this difference can cause timing issues. So always wrap your vanilla JavaScript code into Cypress commands or `then` in order to make use of Cypress command queue.

::: warning
Concerning Cypress `then`: Even though Cypress commands look like promises, they aren't completely the same. Head over to the [Cypress docs](https://docs.cypress.io/guides/core-concepts/introduction-to-cypress#Commands-Are-Not-Promises) for more information.
:::

---

---
url: /docs/products/paas/shopware-paas/blackfire.md
---

::: info
**Platform.sh** is now **Upsun**. You may still encounter references to Platform.sh in code, documentation, or older materials. These references are equivalent to Upsun.
:::

# Blackfire Continuous Observability Solution

Blackfire is bundled with every Enterprise Shopware PaaS project without any additional fees.\
All the people invited to the project can access Blackfire, and all environments can be monitored.

The APM will show you when, where, and why performance issues happen.

Here are the main Blackfire features:

* Monitoring (Live metrics from your app): identify slow transactions, background jobs, services or third-party calls
* Deterministic Profiling (Deep, runtime code analysis): get function-call level metrics and spot root causes of bottlenecks
* Continuous Profiling (Combines profiling and monitoring with minimal overhead): easily identify hotspots, optimize resource usage, and compare timeframes to visually identify the flaky parts of your application
* Testing (Performance budget control): verify code behavior and performance
* Alerting (Warnings upon abnormal behaviors)
* Recommendations (Actionable insights and expert advice): benefit from unique, cutting-edge issue detection with documented resolution recommendations
* CI/CD integration (Automated testing and regression prevention): add Blackfire to any testing pipeline and existing tests, or start from scratch with our Open-Source crawler, tester, and scraper

## Access

You'll find the link to access Blackfire on the Shopware PaaS Console at the environment level.
Once you click on the link, you'll be redirected to the Upsun authentication portal.

If this is your first authentication, please use your usual Shopware PaaS email and follow the "reset password" workflow so you can set your Upsun password.

## Onboarding Guide

We encourage you to look at our [self-onboarding guide](https://docs.blackfire.io/onboarding/index). It includes extensive documentation and videos to help use and understand Blackfire.

## Deterministic Profiling

We recommend you install the [Firefox Blackfire extension](https://addons.mozilla.org/en-US/firefox/addon/blackfire/) or the [Chrome Blackfire extension](https://chromewebstore.google.com/detail/blackfire-profiler/miefikpgahefdbcgoiicnmpbeeomffld?hl=en) so you can trigger profiles of targeted transactions or group of transactions.

![Blackfire profile](../../../assets/blackfire-profile.png)

---

---
url: /docs/v6.6/products/paas/shopware-paas/blackfire.md
---

# Blackfire Continuous Observability Solution

Blackfire is bundled with every Enterprise Shopware PaaS project without any additional fees.\
All the people invited to the project can access Blackfire, and all environments can be monitored.

The APM will show you when, where, and why performance issues happen.

Here are the main Blackfire features:

* Monitoring (Live metrics from your app): identify slow transactions, background jobs, services or third-party calls
* Deterministic Profiling (Deep, runtime code analysis): get function-call level metrics and spot root causes of bottlenecks
* Continuous Profiling (Combines profiling and monitoring with minimal overhead): easily identify hotspots, optimize resource usage, and compare timeframes to visually identify the flaky parts of your application
* Testing (Performance budget control): verify code behavior and performance
* Alerting (Warnings upon abnormal behaviors)
* Recommendations (Actionable insights and expert advice): benefit from unique, cutting-edge issue detection with documented resolution recommendations
* CI/CD integration (Automated testing and regression prevention): add Blackfire to any testing pipeline and existing tests, or start from scratch with our Open-Source crawler, tester, and scraper

## Access

You'll find the link to access Blackfire on the Shopware PaaS Console at the environment level.
Once you click on the link, you'll be redirected to the Platform.sh authentication portal.

If this is your first authentication, please use your usual Shopware PaaS email and follow the "reset password" workflow so you can set your Platform.sh password.

## Onboarding Guide

We encourage you to look at our [self-onboarding guide](https://docs.blackfire.io/onboarding/index). It includes extensive documentation and videos to help use and understand Blackfire.

## Deterministic Profiling

We recommend you install the [Firefox Blackfire extension](https://addons.mozilla.org/en-US/firefox/addon/blackfire/) or the [Chrome Blackfire extension](https://chromewebstore.google.com/detail/blackfire-profiler/miefikpgahefdbcgoiicnmpbeeomffld?hl=en) so you can trigger profiles of targeted transactions or group of transactions.

![Blackfire profile](../../../assets/blackfire-profile.png)

---

---
url: /docs/products/paas/shopware-paas/composable-frontends/blackfire.md
---

# Blackfire Continuous Profiling of Nuxt.js

It's possible to enable [Blackfire Continuous Profiling](https://www.blackfire.io/continuous-profiler/) on a frontend based on Nuxt.js.

1. Install the Blackfire Node.js Lib: `npm install @blackfireio/node-tracing`
2. Add the environment variable `BLACKFIRE_ENABLE=1`
3. Add `./server/plugins/blackfire.ts`:

```ts
// server/plugins/blackfire.ts
export default defineNitroPlugin(async () => {
  if (process.env.BLACKFIRE_ENABLE !== '1') return;

  try {
    // Works in ESM: dynamically import and handle both default/named exports
    const mod = await import('@blackfireio/node-tracing');
    const Blackfire: any = (mod as any).default || mod;

    Blackfire.start({
      appName:
        process.env.BLACKFIRE_APP_NAME || 'shopware-frontend',
      // durationMillis: 45000,
      // cpuProfileRate: 100,
      // labels: { service: 'frontend', framework: 'nuxt3' },
    });

    console.info('[blackfire] node-tracing started');
  } catch (e) {
    console.error('[blackfire] failed to start node-tracing', e);
  }
});
```

---

---
url: /frontends/introduction/templates/blank-template.md
---
# Blank Template

The blank template contains no UI or markup - it's just a blank Nuxt3 application with pre-installed dependencies, so you can start working on your project right away.

## Setup & run

Alternatively, set up the vue-blank template manually by running the following commands in a new directory:

```bash
npx tiged shopware/frontends/templates/vue-blank vue-blank && cd vue-blank
npm i && npm run dev
```

## Configure

The blank template is pre-configured to connect to a public Shopware backend, so you can follow our [building guides](../) right away.

In order to connect it to your own store backend, you need to edit the `nuxt.config.ts` file and add a configuration details:

```ts
/* ... */
export default defineNuxtConfig({
  runtimeConfig: {
    // shopware: {
    /**
     * SSR Shopware Endpoint
     * More here: https://developer.shopware.com/frontends/introduction/templates/custom-vue-project.html#shopware-endpoint-on-the-ssr-mode
     */
    //   endpoint: ""
    // },
    public: {
      shopware: {
        endpoint: "https://your-business.shopware.store",
        accessToken: "access-token-from-settings",
      },
    },
  },
});
```

## What next?

---

---
url: /frontends/integrations/payments/braintree.md
---

# Braintree Integration

:::tip Advanced Guide - prior knowledge required
In order to follow this guide properly, we recommend that you get familiar with the payment flow and payment API concepts first.

* [Payment Flow in Shopware 6](https://developer.shopware.com/docs/concepts/commerce/checkout-concept/payments)
* [Payment API](https://shopware.stoplight.io/docs/store-api/8218801e50fe5-handling-the-payment)
  :::

This guide shows how to integrate **Braintree Credit Card** payments using the [Shopware Braintree App](https://github.com/shopware/braintree-app) in a headless frontend.

## Prerequisites

* Shopware 6 instance with the [Braintree App](https://github.com/shopware/braintree-app) installed and configured
* Braintree payment method enabled in your sales channel
* Customer account with valid billing/shipping address

## Install dependencies

```bash
npm install braintree-web-drop-in
```

## Integration Flow

The Braintree App integration requires three steps:

1. Get a client token from Shopware's App System
2. Initialize the Braintree Drop-in UI
3. Create order and handle payment with the nonce

## Step 1: Get Client Token

First, obtain an app token from Shopware, then exchange it for a Braintree client token.

```ts
const { apiClient } = useShopwareContext();
const { sessionContext } = useSessionContext();

// Get app token from Shopware Store-API
const tokenResponse = await apiClient.invoke(
  "generateJWTAppSystemAppServer post /app-system/{name}/generate-token",
  { pathParams: { name: "SwagBraintreeApp" } },
);
const { token, shopId } = tokenResponse.data;

// Get Braintree client config from the app server
const currencyId = sessionContext.value?.currency?.id;
const salesChannelId = sessionContext.value?.salesChannel?.id;

const configResponse = await fetch(
  `https://braintree.shopware.com/api/client/config?shop-id=${shopId}&currency-id=${currencyId}&sales-channel-id=${salesChannelId}`,
  {
    method: "POST",
    headers: {
      "shopware-app-token": token,
      "shopware-app-shop-id": shopId,
    },
  },
);
const { clientToken } = await configResponse.json();
```

:::warning Important
Use the `shopware-app-token` header, **NOT** `Authorization: Bearer`. Using the wrong header format will result in 500 errors.
:::

## Step 2: Initialize Braintree Drop-in

```ts
import dropin from "braintree-web-drop-in";

const instance = await dropin.create({
  authorization: clientToken,
  container: "#dropin-container",
  dataCollector: true, // Required for deviceData (fraud detection)
  card: {
    cardholderName: {
      required: true,
    },
  },
});
```

## Step 3: Create Order and Handle Payment

When the user submits payment, get the nonce from the Drop-in, create the order, then call `/handle-payment` with the Braintree data.

```ts
const { createOrder } = useCheckout();
const { apiClient } = useShopwareContext();

async function onPaymentSubmit() {
  // Get nonce from Braintree Drop-in
  const { nonce, deviceData } = await instance.requestPaymentMethod();

  // Create order (no braintree params here)
  const order = await createOrder();

  // Handle payment WITH Braintree data
  await apiClient.invoke("handlePaymentMethod post /handle-payment", {
    body: {
      orderId: order.id,
      finishUrl: `${window.location.origin}/checkout/finish`,
      errorUrl: `${window.location.origin}/checkout/error`,
      braintreeNonce: nonce,
      braintreeDeviceData: deviceData,
    },
  });
}
```

:::warning Important
Pass `braintreeNonce` and `braintreeDeviceData` to `/handle-payment`, **NOT** to `/checkout/order`.
:::

## Test Cards

For Braintree sandbox testing:

| Card Type | Number              | Expiry     | CVV |
| --------- | ------------------- | ---------- | --- |
| Visa      | 4111 1111 1111 1111 | Any future | Any |

## Working Example

See the complete working example in the Composable Frontends repository:

[Braintree Credit Card Example](https://github.com/shopware/frontends/tree/main/examples/braintree-credit-card)

## Resources

* [Shopware Braintree App](https://github.com/shopware/braintree-app)
* [Braintree App Wiki - Headless Integration](https://github.com/shopware/braintree-app/wiki/3.-Headless-integration)
* [Braintree Web Drop-in](https://github.com/braintree/braintree-web-drop-in)
* [Braintree Developer Docs](https://developer.paypal.com/braintree/docs)

---

---
url: /docs/products/digital-sales-rooms/customization/branding.md
---

::: warning
All customization instructions will refer to changes made within your customization layer folder.
:::

# Branding Customization

## Favicon

* Create `public` folder inside your layer (if missing).

* Place your favicon inside the `public` folder and ensure it is named `favicon.ico`.

## Web application title

* Create `nuxt.config.ts` inside your layer (if missing).

* Replace "Your app name" with your app's name and add the following code:

```js
app: {
  head: {
    title: 'Your app name'
  }
}
```

## Theme color

* Create `uno.config.ts` inside your layer (if missing).

* For example, to change the primary color to `#000000`, add the following code:

```js
theme: {
  colors: {
    primary: {
      DEFAULT: '#000000'
    }
  }
}
```

* Refer to the `uno.config.ts` file in the dsr layer to understand the key structure for overriding colors.

---

---
url: /docs/products/sales-agent/customization/branding.md
---

::: warning
All customization instructions will refer to changes made within your customization layer folder.
:::

# Branding Customization

## Favicon

* Create `public` folder inside your layer (if missing).

* Place your favicon inside the `public` folder and ensure it is named `favicon.ico`.

## Web application title

* Create `nuxt.config.ts` inside your layer (if missing).

* Replace "Your app name" with your app's name and add the following code:

```js
app: {
  head: {
    title: 'Your app name'
  }
}
```

## Theme color

Sales Agent utilizes the Shopware [Meteor Component Library](https://shopware.design/get-started/installation.html), which provides a comprehensive CSS variable system to manage themes. The default theme is aligned with their design system, ensuring consistency across applications. This package offers both a [light theme](https://github.com/shopware/meteor/blob/main/packages/tokens/deliverables/administration/light.css) and a [dark theme](https://github.com/shopware/meteor/blob/main/packages/tokens/deliverables/administration/dark.css), allowing you to explore and utilize the CSS variable system effectively.

### Customizing Theme Colors

To tailor the theme to your brand's identity, you can override the default CSS variables. By defining custom values in your own CSS file, you can seamlessly adapt the visual aspects of the application:

```css
/* main.css */
:root {
  --color-interaction-primary-default: #80A1BA; /* Add your primary color */
  /* Add more customizations as needed */
}
```

### Integrating Custom Styles in Nuxt.js

To apply these customizations in your application, import the CSS file into your Nuxt configuration. This will ensure that your branding colors take effect across the app:

```javascript
// nuxt.config.ts
export default defineNuxtConfig({
  css: ["./main.css"], // Include your custom CSS file
});
```

By doing so, you maintain the flexibility of the Shopware system while aligning it with your unique brand style, providing a cohesive user experience.

---

---
url: /docs/v6.6/products/digital-sales-rooms/customization/branding.md
---

::: warning
All customization instructions will refer to changes made within your customization layer folder.
:::

# Branding Customization

## Favicon

* Create `public` folder inside your layer (if missing).

* Place your favicon inside the `public` folder and ensure it is named `favicon.ico`.

## Web application title

* Create `nuxt.config.ts` inside your layer (if missing).

* Replace "Your app name" with your app's name and add the following code:

```js
app: {
  head: {
    title: 'Your app name'
  }
}
```

## Theme color

* Create `uno.config.ts` inside your layer (if missing).

* E.g. to change the primary color to `#000000`, add the following code:

```js
theme: {
  colors: {
    primary: {
      DEFAULT: '#000000'
    }
  }
}
```

* Refer to the `uno.config.ts` file in the dsr layer to understand the key structure for overriding colors.

---

---
url: /frontends/guides/page-elements/breadcrumbs.md
---

# Breadcrumbs managing

In this chapter you will learn how to

* Build breadcrumbs for static page
* Build dynamic breadcrumbs for category/product page

### Quick reference

* [useBreadcrumbs](../../packages/composables/useBreadcrumbs) is a composable used for a breadcrumbs management with sharable state
* [getCategoryBreadcrumbs](../../packages/helpers.html#getcategorybreadcrumbs) is a helper used for converting `Category` to the `Breadcrumb` object
* [getCmsBreadcrumbs](../../packages/helpers#getcmsbreadcrumbs) is a helper used for building breadcrumbs for `Landing Pages`

## Building breadcrumbs for a static page

```ts
useBreadcrumbs([
  {
    name: "Shopware",
    path: "/shopware",
  },
]);
```

## Building breadcrumbs for a category/product page

```ts
// props.navigationId is a page id

const { buildDynamicBreadcrumbs } = useBreadcrumbs();
buildDynamicBreadcrumbs(props.navigationId);
```

## Building breadcrumbs for CMS pages - without additional request

Each CMS page contains the `Category` with `breadcrumb` array, which contains a list of names, like:

```
breadcrumb: ["Home", "Main navigation ", "Summer Party"]
```

we can convert current `string` array to the `Breadcrumb` object using [getCategoryBreadcrumbs](../../packages/helpers.html#getcategorybreadcrumbs) helper, and then pass it to [useBreadcrumbs](../../packages/composables/useBreadcrumbs) composable.

```ts
import { getCategoryBreadcrumbs } from "@shopware/helpers";

let breadcrumbs = getCategoryBreadcrumbs(
  productResponse.value?.product?.seoCategory,
);
useBreadcrumbs(breadcrumbs);
```

## Clearing breadcrumbs list

It's important to clear breadcrumbs list when you leave the page, otherwise you'll see breadcrumbs from the previous page if your not setting them on that page.

```ts
const { clearBreadcrumbs } = useBreadcrumbs();

onBeforeRouteLeave(() => {
  clearBreadcrumbs();
});
```

## Displaying Breadcrumbs

Breadcrumbs are stored in sharable variable `breadcrumbs` in [useBreadcrumbs](../../packages/composables/useBreadcrumbs) composable.

```vue
<script setup lang="ts">
const { breadcrumbs } = useBreadcrumbs();
</script>
<template>
  <nav>
    <ol>
      <li v-for="(breadcrumb, index) in breadcrumbs" :key="breadcrumb.path">
        <NuxtLink v-if="breadcrumb.path" :to="breadcrumb.path">
          {{ breadcrumb.name }}
        </NuxtLink>
        <span v-else>
          {{ breadcrumb.name }}
        </span>
        <div v-if="index < breadcrumbs.length - 1"></div>
      </li>
    </ol>
  </nav>
</template>
```

---

---
url: /frontends/guides/features/broadcasting.md
---

# Broadcasting

The Broadcast Channel API allows simple communication between browsing contexts (e.g., different tabs, iframes, or workers) on the same origin.

For Vue app we are recommending to use `useBroadcastChannel` from `VueUse` [package](https://vueuse.org/core/useBroadcastChannel/)

## Enabling Broadcasting in Vue-Demo Template

By default, the broadcasting feature is disabled in the Vue-Demo template. To enable broadcasting, follow these steps:

1. Open the `nuxt.config.ts` file in your project.
2. Locate the broadcasting configuration setting.
3. Set the `broadcasting` property to `true` as shown below:

```typescript
export default defineNuxtConfig({
  // Other configurations...
  runtimeConfig: {
    broadcasting: false,
  },
});
```

For more information, please visit the [troubleshooting page](https://developer.shopware.com/frontends/resources/troubleshooting.html#broadcasting-and-bfcache-compatibility)

## Synchronizing changes between tabs

In our demo store template we provide example of usage broadcasting for synchronizing changes between tabs.
We rely on the data fetched by the API client and send them to broadcast channel for synchronization.
This way:

* session data
* cart data
  are synchronized between tabs.

```ts [useBroadcastChannelSync.ts]
import type { Schemas } from "#shopware";

export function useSyncChannel<Entity>(
  name: string,
): [Ref<Entity | undefined>, (data: Entity) => void] {
  const { data, post } = useBroadcastChannel<Entity, Entity>({
    name,
  });

  return [data, post];
}

function isEntity<T extends { apiAlias: string }>(
  data: T,
  apiAlias: T["apiAlias"],
): data is T {
  return data?.apiAlias === apiAlias;
}

/**
 * Sync basic state like session/cart data between tabs
 */
export const useBroadcastChannelSync = createSharedComposable(() => {
  const { apiClient } = useShopwareContext();

  // Synchronize CART data
  const { refreshCart } = useCart();
  const [cartData, notifyCartDataChanged] =
    useSyncChannel<Schemas["Cart"]>("shopware-cart");
  watch([cartData], () => {
    refreshCart(cartData.value);
  });

  // Synchronize SESSION data
  const { setContext } = useSessionContext();
  const [sessionData, notifySessionDataChanged] = useSyncChannel<
    Schemas["SalesChannelContext"]
  >("shopware-session-data");
  watch([sessionData], () => {
    if (sessionData.value) {
      setContext(sessionData.value);
    }
  });

  // Listen for API responses and update the shared state
  apiClient.hook("onSuccessResponse", (response) => {
    // for cart
    if (isEntity<Schemas["Cart"]>(<Schemas["Cart"]>response._data, "cart")) {
      notifyCartDataChanged(<Schemas["Cart"]>response._data);
    }
    // for session data
    else if (
      isEntity<Schemas["SalesChannelContext"]>(
        <Schemas["SalesChannelContext"]>response._data,
        "sales_channel_context",
      )
    ) {
      notifySessionDataChanged(<Schemas["SalesChannelContext"]>response._data);
    }
  });
});
```

---

---
url: /docs/v6.6/products/cli/project-commands/build.md
---

# Build a complete Project

Usually, when you want to deploy your project, you have to run `composer install` and compile the assets of the project. Shopware CLI provides a single command which does all of this for you.

::: warning
This command modifies the given directory and deletes files. Make sure you have committed all your changes before running this command.
:::

```bash
shopware-cli project ci <path>
```

## What does it do?

* It runs `composer install` (by default, only installs the production dependencies, use `--with-dev-dependencies` to install the dev dependencies as well)
* Looks for missing assets of extensions and only compiles the missing assets to speed up the build process
* Deletes unnecessary files like `node_modules` and many more to save disk space
* Deletes source code of compiled assets to save disk space
* Merges snippets of extensions to speed up Administration

## Using private Composer repositories

If you want to use `packages.shopware.com` as a private Composer repository, make sure you have set `SHOPWARE_PACKAGES_TOKEN` environment variable to your Composer token. This can be found in your Shopware Account.

For other private Composer repositories, you can use the `auth.json` file in the root of your project or set `COMPOSER_AUTH` environment variable with the content of the `auth.json` file.

For more information, see the [Composer documentation](https://getcomposer.org/doc/articles/authentication-for-private-packages.md).

## Reducing JavaScript in Storefront

Shopware's default `browserlist` still supports older browsers like Internet Explorer 11. If you want to reduce JavaScript polyfill and CSS prefixes, you can adjust the `browserlist` configuration in the `.shopware-project.yml` file.

```yaml
build:
  # Browserlist configuration for Storefront
  browserslist: 'defaults'
```

You can check [here which browsers would be affected](https://browsersl.ist/#q=defaults).

## Configuration options

You can configure the build process with a `.shopware-project.yml` file. The following options are available:

```yaml
build:
  # Browserlist configuration for Storefront
  browserslist: 'defaults'
  # Paths that should be deleted
  cleanup_paths:
    - 'node_modules'
  # At the end of the process, bin/console asset:install is executed, this can be disabled here
  disable_asset_copy: false
  # Exclude the following extensions from the build process
  exclude_extensions:
    - 'SwagExample'
  # Keep the extension Administration and Storefront source code
  keep_extension_source: false
  # Keep the source maps of the compiled assets
  keep_source_maps: false
  # Delete after bin/console asset:install all assets in the extensions, so only live in public folder.
  # This only works when the assets are served directly from the public folder.
  remove_extension_assets: false
  # Allows to force building an extension even when the assets existing. A use-case could be if you used composer patches for a specific extension.
  force_extension_build:
    - name: 'SomePlugin'
```

## Supporting bundles

Plugins and Apps are automatically detected by Shopware CLI. Custom bundles (classes that extend bundle class from Shopware) cannot be automatically detected as Shopware CLI does not execute any PHP code.
Therefore you need to add the path of the custom bundle to your project `composer.json`:

```json
{
    "extra": {
        "shopware-bundles": {
            // The key is the relative path from project root to the bundle
            "src/MyBundle": {}
        }
    }
}
```

If your bundle folder names does not match your bundle name, you can use the `name` key to map the folder to the bundle name.

```json
{
    "extra": {
        "shopware-bundles": {
            "src/MyBundle": {
                "name": "MyFancyBundle"
            }
        }
    }
}
```

### Bundle packaged in own composer package

If your bundle is a own composer package, make sure your composer type is `shopware-bundle` and that you have set a `shopware-bundle-name` in the extra part of the config like this:

```json
{
    "name": "my-vendor/my-bundle",
    "type": "shopware-bundle",
    "extra": {
        "shopware-bundle-name": "MyBundle"
    }
}
```

With this Composer type, `shopware-cli extension build` also works for your bundle, if you want to distribute compiled assets.

## Example Docker Image

This is an example Dockerfile which builds a Shopware project and copies the source code to the `/var/www/html` folder.

```dockerfile
#syntax=docker/dockerfile:1.4

# pin versions
FROM shopware/docker-base:8.3 AS base-image
FROM shopware/shopware-cli:latest-php-8.3 AS shopware-cli

# build

FROM shopware-cli AS build

ARG SHOPWARE_PACKAGES_TOKEN

ADD . /src
WORKDIR /src

RUN --mount=type=secret,id=composer_auth,dst=/src/auth.json \
    --mount=type=cache,target=/root/.composer \
    --mount=type=cache,target=/root/.npm \
    /usr/local/bin/entrypoint.sh shopware-cli project ci /src

FROM base-image

COPY --from=build --chown=82 --link /src /var/www/html
```

Besides Docker, it is also a perfect fit for any deployment variant.

---

---
url: /docs/products/tools/cli/project-commands/build.md
---

# Build a Complete Project

Usually, when you want to deploy your project, you have to run `composer install` and compile the project's assets. Shopware CLI provides a single command that does all of this for you.

::: warning
This command modifies the given directory and deletes files. Make sure you have committed all your changes before running this command.
:::

```bash
shopware-cli project ci <path>
```

One of the most-used commands in the Shopware CLI. After cloning a repository, this command prepares a complete artifact that can be deployed with all dependencies installed and assets compiled. It is widely used in PaaS and SaaS deployments.

## What does it do?

* It runs `composer install` (by default, only installs the production dependencies, use `--with-dev-dependencies` to install the dev dependencies as well)
* Looks for missing assets of extensions and only compiles the missing assets to speed up the build process
* Deletes unnecessary files like `node_modules` and many more to save disk space
* Deletes source code of compiled assets to save disk space
* Merges snippets of extensions to speed up Administration
* Writes a CycloneDX 1.7 SBOM (`sbom.cdx.json`) from `composer.lock`

If you only need the SBOM and not a full CI build, use [`shopware-cli project sbom`](sbom.md) instead.

* Generates a Software Bill of Materials (SBOM) listing all deployed dependencies

## CI system

The CI system is detected automatically from the environment, so you don't need to configure anything.

If you want to override the detection — for example, to disable CI-specific output — pass `--ci`:

```bash
shopware-cli project ci <path> --ci none
```

Accepted values: `github`, `gitlab`, `none`.

## Using private Composer repositories

If you want to use `packages.shopware.com` as a private Composer repository, make sure you have set the `SHOPWARE_PACKAGES_TOKEN` environment variable to your Composer token. This can be found in your Shopware Account.

For other private Composer repositories, you can use the `auth.json` file in the root of your project or set the `COMPOSER_AUTH` environment variable with the content of the `auth.json` file.

For more information, see the [Composer documentation](https://getcomposer.org/doc/articles/authentication-for-private-packages.md).

## Reducing JavaScript in the Storefront

Shopware's default `browserlist` still supports older browsers, such as Internet Explorer 11. If you want to reduce JavaScript polyfill and CSS prefixes, you can adjust the `browserlist` configuration in the `.shopware-project.yml` file.

```yaml
build:
  # Browserlist configuration for Storefront
  browserslist: 'defaults'
```

You can check [here which browsers would be affected](https://browsersl.ist/#q=defaults).

## MJML Email Template Compilation

Starting with Shopware CLI 0.6.32, the `project ci` command can compile MJML email templates during the build process
for projects using the [FroshPlatformTemplateMail](https://github.com/FriendsOfShopware/FroshPlatformTemplateMail) plugin.
[MJML](https://mjml.io) is a markup language designed to reduce the pain of coding responsive emails by providing
semantic components that compile to responsive HTML.

### Prerequisites

This feature is designed specifically for projects that use the **FroshPlatformTemplateMail** plugin. The primary purpose of this plugin is to manage email templates as source files in your codebase, rather than storing them in the database. This approach enables:

* **Version control**: Email templates can be tracked in Git alongside your code
* **Deployment consistency**: Templates are deployed with your code, ensuring consistency across environments
* **MJML support**: Optionally write templates in MJML (Mailjet Markup Language) format for responsive emails
* **Build-time compilation**: Since templates are in source files, they can be compiled during the build process

Having email templates in source files is essential for the shopware-cli MJML compilation feature to work, as it processes these files during the build phase.

### Why compile MJML during build-time?

By default, FroshPlatformTemplateMail compiles MJML templates at runtime when emails are sent. The shopware-cli build-time compilation offers several advantages:

* **Early error detection**: Catch MJML syntax errors during CI/CD instead of when sending emails
* **Better performance**: Eliminate runtime compilation overhead
* **Improved reliability**: Remove potential runtime failures in production
* **Reduced dependencies**: No need for MJML compilation services in production

### Configuration

Enable MJML compilation in your `.shopware-project.yml` file:

```yaml
build:
  mjml:
    # Enable MJML compilation during build-time
    enabled: true
    # Directories to search for MJML templates (defaults to custom/plugins and custom/static-plugins if not specified)
    searchPaths:
      - custom/plugins
      - custom/static-plugins
```

### How it works

When MJML compilation is enabled:

1. The CLI searches for `html.mjml` files in the configured search paths (defaults to `custom/plugins` and `custom/static-plugins`)
2. Each `html.mjml` file is compiled to HTML and saved as `html.twig`
3. The original `html.mjml` files are removed after successful compilation to prevent runtime re-compilation attempts
4. Any compilation errors are reported and cause the build to fail, ensuring broken templates don't reach production

### Requirements

MJML compilation requires the `mjml` package to be installed via NPM in your build environment. The CLI uses local compilation to convert MJML templates to HTML.

## Software Bill of Materials (SBOM)

The `project ci` command automatically generates a Software Bill of Materials (SBOM) file containing a list of all dependencies installed in your project. This file is useful for:

* **Docker images**: Container scanning tools can read SBOM files to identify dependencies and check for vulnerabilities
* **Security scanning**: Understand exactly which packages and versions are deployed in production
* **Compliance tracking**: Document all software components in your deployment artifact
* **Supply chain security**: Maintain a record of what's included in each release

The SBOM is included in the build artifact automatically and can be consumed by tools like Grype and other container security scanners.

## Build Hooks

Build hooks let you run custom shell commands at specific stages of the CI build process. This is useful for tasks like generating configuration files, running custom build steps, or integrating with external tools.

### Available hooks

| Hook            | Execution point                         |
|-----------------|-----------------------------------------|
| `pre` | Before the build process starts         |
| `pre-composer` | Before `composer install` is executed   |
| `post-composer` | After `composer install` completes      |
| `pre-assets` | Before asset building begins            |
| `post-assets` | After asset building completes          |
| `post` | After the entire build process finishes |

### Configuration

Define hooks in your `.shopware-project.yml` file:

```yaml
build:
  hooks:
    pre:
      - 'echo "Starting build"'
    pre-composer:
      - 'cp .env.ci .env'
    post-composer:
      - 'bin/console secrets:decrypt-to-local --force'
    pre-assets:
      - 'npm install --prefix custom/plugins/MyPlugin'
    post-assets:
      - 'rm -rf node_modules'
    post:
      - 'echo "Build complete"'
```

Each hook accepts an array of shell commands. Commands are executed sequentially using `sh -c`, and the build fails immediately if any hook command exits with a non-zero status.

### Environment variables

The following environment variable is available in all hooks:

| Variable       | Description                                 |
|----------------|---------------------------------------------|
| `PROJECT_ROOT` | Absolute path to the project root directory |

All existing environment variables from the parent process are also inherited, so any CI/CD variables (e.g., `SHOPWARE_PACKAGES_TOKEN`) are accessible within hooks.

## Configuration options

You can configure the build process with a `.shopware-project.yml` file. The following options are available:

```yaml
compatibility_date: '2026-02-11'

build:
  # Browserlist configuration for Storefront
  browserslist: 'defaults'
  # Paths that should be deleted
  cleanup_paths:
    - 'node_modules'
  # At the end of the process, bin/console asset:install is executed, this can be disabled here
  disable_asset_copy: false
  # Exclude the following extensions from the build process
  exclude_extensions:
    - 'SwagExample'
  # Keep the extension Administration and Storefront source code
  keep_extension_source: false
  # Keep the source maps of the compiled assets
  keep_source_maps: false
  # After bin/console asset:install, remove all asset files from the extension directories so that assets only exist in the public folder.
  # Note: This option should only be enabled if assets are served directly from the public folder.
  remove_extension_assets: false
  # Allows force building an extension even when the assets exist. A use case could be using composer patches for a specific extension.
  force_extension_build:
    - name: 'SomePlugin'
  # Shopware bundles to include in the build
  bundles:
    - path: src/MyBundle
    - path: src/MyFancyBundle
      name: MyGreatFancyBundle
  # MJML compilation configuration (see the MJML section above for details)
  mjml:
    enabled: false
    searchPaths:
      - custom/plugins
      - custom/static-plugins
  # Build hooks (see the Build Hooks section above for details)
  hooks:
    pre: []
    post: []
    pre-composer: []
    post-composer: []
    pre-assets: []
    post-assets: []
```

## Compatibility date

You can define a `compatibility_date` in `.shopware-project.yml`:

```yaml
compatibility_date: '2026-02-11'
```

The `compatibility_date` lets Shopware CLI introduce behavior changes without breaking existing projects by default. New or potentially breaking changes are activated only for configurations that opt in with a date at or after the feature's rollout date.

* Format: `YYYY-MM-DD`
* If the field is missing, Shopware CLI uses `2026-02-11` as a fallback
* When missing, Shopware CLI logs a warning during config loading

## Supporting bundles

Shopware CLI automatically detects plugins and Apps. Custom bundles (classes that extend the bundle class from Shopware) cannot be automatically detected as Shopware CLI does not execute any PHP code.
Use .shopware-project.yml to declare bundles. The alternative declaration in the project's composer.json is deprecated and no longer recommended.

### Declaring bundles in `.shopware-project.yml`

The recommended approach is to declare bundles in the `build` section of your `.shopware-project.yml`:

```yaml
build:
  bundles:
    - path: src/MyBundle
    - path: src/MyFancyBundle
      name: MyGreatFancyBundle  # optional: override the bundle name (defaults to the directory name)
```

The `path` is relative to the project root. The `name` field is optional, and when omitted, the bundle name defaults to the directory basename.

### Declaring bundles in `composer.json` (deprecated)

:::danger
**Deprecated:** Declaring bundles via `composer.json` is deprecated and will be removed in a future version. Please migrate to the `.shopware-project.yml` approach described above. Shopware CLI will emit a deprecation warning when bundles are configured this way.
:::

Alternatively, you can add the bundle path to the `extra` section of your `composer.json`:

```json5
{
    "extra": {
        "shopware-bundles": {
            // The key is the relative path from the project root to the bundle
            "src/MyBundle": {}
 }
 }
}
```

If your bundle folder name does not match your bundle name, you can use the `name` key:

```json
{
    "extra": {
        "shopware-bundles": {
            "src/MyBundle": {
                "name": "MyFancyBundle"
 }
 }
 }
}
```

Both sources are merged automatically. If the same bundle path appears in both, it is only processed once.

### Bundle packaged in its own composer package

If your bundle is its own composer package, make sure your composer type is `shopware-bundle` and that you have set a `shopware-bundle-name` in the extra part of the config like this:

```json
{
    "name": "my-vendor/my-bundle",
    "type": "shopware-bundle",
    "extra": {
        "shopware-bundle-name": "MyBundle"
 }
}
```

With this Composer type, `shopware-cli extension build` also works for your bundle if you want to distribute compiled assets.

## Example Docker Image

This is an example Dockerfile that builds a Shopware project and copies the source code to the `/var/www/html` folder.

```dockerfile
#syntax=docker/dockerfile:1.4

# pin versions
FROM ghcr.io/shopware/docker-base:8.3 AS base-image
FROM ghcr.io/shopware/shopware-cli:latest-php-8.3 AS shopware-cli

# build

FROM shopware-cli AS build

ARG SHOPWARE_PACKAGES_TOKEN

ADD . /src
WORKDIR /src

RUN --mount=type=secret,id=composer_auth,dst=/src/auth.json \
 --mount=type=cache,target=/root/.composer \
 --mount=type=cache,target=/root/.npm \
 /usr/local/bin/entrypoint.sh shopware-cli project ci /src

FROM base-image

COPY --from=build --chown=82 --link /src /var/www/html
```

Besides Docker, it is also a perfect fit for any deployment variant.

---

---
url: /docs/guides/plugins/apps/create-admin-extension.md
---

# Build an Admin UI App Locally

## Overview

This guide shows how to create a Shopware app that adds an Administration module backed by a local frontend development server. Use this setup when you want to:

* add a custom module to the Administration
* build an app-based Admin UI locally
* iterate on the frontend without setting up an app backend first

If you need app registration, signing, webhooks, or Admin API credentials, continue with [App registration & backend setup](../apps/lifecycle/app-registration-setup.md).

## What this guide covers

In this setup:

* the app is defined through `manifest.xml`
* Shopware discovers the app from `custom/apps`
* the Administration module loads from a local dev server such as [Vite](https://vite.dev/)
* no app backend is required just to render the Admin UI module in this local setup

## Prerequisites

* a local Shopware instance
* access to the Administration at `http://localhost:8000/admin`
* shell access to the PHP container for `bin/console`
* Node.js 22 on the host system

Use Node 22:

```bash
nvm install 22
nvm use 22
node -v
```

::: info
If you are on a newer Node version, switch to Node 22 before creating the frontend project.
:::

## 1. Create the app folder

From the Shopware project root, create the app directory under `custom/apps`:

```bash
mkdir -p custom/apps/MyAdminTestApp
```

The folder name must match the app name defined in the manifest.

Scaffolding via `npm init @shopware/app` may not work in all environments. Creating the app manually avoids registry login issues and is sufficient for this local Admin UI setup.

## 2. Create the manifest

Create `custom/apps/MyAdminTestApp/manifest.xml` with a valid `<meta>` block and an `<admin>` block. `<author>` and `<copyright>` are **required**. If either is missing, `bin/console app:refresh` fails.

Example (adjust names if you use a different folder):

```xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        <name>MyAdminTestApp</name>
        <label>My Admin Test App</label>
        <version>1.0.0</version>
        <author>Your Name</author>
        <copyright>(c) Your Name</copyright>
    </meta>
    <admin>
        <module name="my-admin-test-app"
                source="http://host.docker.internal:5173"
                parent="sw-extension">
            <label>Admin Test</label>
        </module>
    </admin>
</manifest>
```

## 3. Refresh and install the app

Run the following commands from the Shopware project root inside the PHP container:

```bash
bin/console app:refresh
bin/console app:install --activate MyAdminTestApp
bin/console app:list
```

If Shopware asks whether the app may communicate with external hosts such as `host.docker.internal`, confirm this when you intend to load the Admin module from your local development server.

::: info
If the app appears in `app:list` as inactive, activate it in the Administration under **Extensions → My Extensions → Apps**, or run `bin/console app:activate MyAdminTestApp`.
:::

## 4. Create the frontend project

From the Shopware project root on the host, create a frontend project for the Admin UI:

```bash
mkdir -p admin-frontend
cd admin-frontend
npm create vite@latest .
```

At the prompt, provide these choices during setup:

* framework: `Vanilla`
* variant: `JavaScript`
* Vite 8 beta: `no` (unless you need it)

Then install the Shopware Admin Extension SDK:

```bash
npm install
npm install @shopware-ag/admin-extension-sdk
```

## 5. Start the development server

Start the Vite development server with host binding enabled, so the Docker container can reach it:

```bash
npm run dev -- --host
```

By default, Vite uses `port 5173`. Keep that port in sync with the `source` URL in the manifest:

```xml
source="http://host.docker.internal:5173"
```

::: info
Keep the frontend project inside the Shopware project directory if your Docker setup relies on bind mounts.
:::

## 6. Open the app in Administration

Sign in to the Administration at `http://localhost:8000/admin`. Then:

* go to **Extensions → My Extensions → Apps**
* make sure `MyAdminTestApp` is active
* open the module from **Extensions**

At this point, Shopware loads the Admin module from your local Vite server.

## Troubleshooting

| Issue | What to check |
|-------|---------------|
| `app:list` shows no apps | Run `bin/console app:refresh`. Confirm `custom/apps/<Name>` exists inside the container. |
| `app:refresh` fails | Check that `<author>` and `<copyright>` are present and not empty. |
| App does not appear in **My Extensions** | Confirm the folder name matches `<meta><name>` and refresh the app registry again. |
| App appears but is inactive | Activate it in **Extensions → My Extensions → Apps** or run `bin/console app:activate MyAdminTestApp`. |
| Blank iframe | Make sure Vite is running, exposed with `--host`, and using the same port as the `source` URL in `manifest.xml`. From the container, test access to `http://host.docker.internal:5173`. |
| `host.docker.internal` does not work on Linux | Your Docker setup may require additional host mapping or network configuration. |

## Next steps

* [App registration & backend setup](../apps/lifecycle/app-registration-setup.md)
* [App signature verification](../apps/lifecycle/app-signature-verification.md)
* [Webhooks](../apps/lifecycle/webhook.md)

---

---
url: /docs/products/paas/shopware-paas/build-deploy.md
---

# Build and Deploy

Now that we have set up the repository, we are ready to push changes to your PaaS environment.

The key concept is that your PaaS project is a git repository. Every time you push to that repository, a new version of your store will be created from the source code and deployed. Different environments (e.g., dev-previews, staging, and production) are mapped by corresponding branches.

## Push main branch

To push your latest changes, run the following commands from your terminal:

```bash{3}
git add .
git commit -m "Applied new configuration"
git push -u shopware main
```

First, we stage all changes and then add them as a new commit. Then, we push them to our `shopware` origin (remember, the one for our PaaS environment) on the `main` branch.

This will trigger a new build with a subsequent deploy consisting of the following steps:

| Build                                         | Deploy                                          |
|-----------------------------------------------|-------------------------------------------------|
| Configuration validation                      | Hold app requests                               |
| Build container image                         | Unmount live containers                         |
| Installing dependencies                       | Mount file systems                              |
| Run [build hook](./setup-template#build-hook) | Run [deploy hook](./setup-template#deploy-hook) |
| Building app image                            | Serve requests                                  |

After both steps have been executed successfully (you will get extensive logging about the process), you will be able to see the deployed store on a link presented at the end of the deployment.

## First deployment

The first time the site is deployed, Shopware's command line installer will run and initialize Shopware. It will not run again unless the `install.lock` file is removed. **Do not remove that file unless you want the installer to run on the next deploy.**

The installer will create an administrator account with the default credentials.

| username | password   |
|----------|------------|
| `admin`  | `shopware` |

Make sure to change this password immediately in your Administration account settings. Not doing so is a security risk.

## Composer authentication

You must authenticate yourself to install extensions from the Shopware store via composer. In your local development environment, this is possible by creating an `auth.json` file that contains your auth token. However, this file shouldn't be committed to the repository.

The following command adds your authentication token to the secure environment variable storage of Shopware Paas. This variable (contains the content which would otherwise be in `auth.json`) will be available during the build step and be automatically picked up by the composer.

```bash
shopware variable:create --level project --name env:COMPOSER_AUTH --json true --visible-runtime false --sensitive true --visible-build true --value '{"bearer": {"packages.shopware.com": "%place your key here%"}}'
```

Make sure to replace `%place your key here%` with your actual token. You can find your token by clicking 'Install with Composer' in your Shopware Account.

## Extending Shopware - plugins and apps

The PaaS recipe uses the [Composer plugin loader](../../../guides/hosting/installation-updates/cluster-setup#composer-plugin-loader), which expects all extensions being installed via Composer.

## Manually trigger rebuilds

Sometimes, you might want to trigger a rebuild and deploy of your environment without pushing new code to your project. To do this for your main environment, create a `REBUILD_DATE` environment variable. This triggers a build right away to propagate the variable.

```bash
shopware variable:create --environment main --level environment --prefix env --name REBUILD_DATE --value "$(date)" --visible-build true
```

To force a rebuild at any time, update the variable with a new value:

```bash
shopware variable:update --environment main --value "$(date)" "env:REBUILD_DATE"
```

This forces your application to be built even if no code has changed.

---

---
url: /docs/v6.5/products/paas/build-deploy.md
---

# Build and Deploy

Now that we have set up the repository, we are ready to push changes to your PaaS environment.

The key concept is that your PaaS project is a git repository. Every time you push to that repository, a new version of your store will be created from the source code and deployed. Different environments (e.g., dev-previews, staging, and production) are mapped by corresponding branches.

## Push main branch

To push your latest changes, run the following commands from your terminal:

```bash{3}
git add .
git commit -m "Applied new configuration"
git push -u shopware main
```

First, we stage all changes and then add them as a new commit. Then, we push them to our `shopware` origin (remember, the one for our PaaS environment) on the `main` branch.

This will trigger a new build with a subsequent deploy consisting of the following steps:

| Build | Deploy |
| --- | --- |
| Configuration validation | Hold app requests |
| Build container image | Unmount live containers |
| Installing dependencies | Mount file systems |
| Run [build hook](./setup-template#build-hook) | Run [deploy hook](./setup-template#deploy-hook) |
| Building app image | Serve requests |

After both steps have been executed successfully (you will get extensive logging about the process), you will be able to see the deployed store on a link presented at the end of the deployment.

## First deployment

The first time the site is deployed, Shopware's command line installer will run and initialize Shopware. It will not run again unless the `install.lock` file is removed. **Do not remove that file unless you want the installer to run on the next deploy.**

The installer will create an administrator account with the default credentials.

| username | password |
|---|---|
| `admin` | `shopware` |

Make sure to change this password immediately in your Administration account settings. Not doing so is a security risk.

### Manual steps

After the first deploy, some steps must be done manually before the environment is entirely up and running.

#### JWT keys

The JWT keys, used for the Administration authentication, need to be generated for your project. The keys will be stored securely in the Shopware Paas environment variable storage and should not be committed to the Git repository or be available on the file system.

To generate the keys and add them to the storage, run the following command:

```bash
shopware ssh --app=app "bin/console system:generate-jwt-secret --use-env" |\
grep -E "^JWT_(PUBLIC|PRIVATE)_KEY=" |\
while read line ; do \
shopware variable:create --sensitive 1 --level project --name env:$(echo $line | cut -d "=" -f 1) --value $(echo $line | cut -d "=" -f 2-); \
done
```

Run this command from your project directory so the `shopware` command knows which project to update.

The command connects to the application server to generate the JWT keys. It then sets the `JWT_PUBLIC_KEY` and `JWT_PRIVATE_KEY` as private environment variables.

Finally, execute the `shopware redeploy` command to proceed with the build-and-deploy process.

##### Shopware config

By default, Shopware looks for the JWT keys on the file system. The configuration must be updated to use the keys in the environment variables.

If you use the Shopware Flex Paas template, [the configuration](https://github.com/shopware/recipes/blob/main/shopware/paas-meta/6.4/config/packages/paas.yaml) will be applied automatically.

```yaml
 shopware:
   api:
     jwt_key:
       private_key_path: '%env(base64:JWT_PRIVATE_KEY)%'
       public_key_path: '%env(base64:JWT_PUBLIC_KEY)%'  
```

#### Theme assets

It is a known issue that after the first deployment, theme assets are not compiled during the deployment. For that reason, your store will look unstyled. The [Theme Build](./theme-build) section explains how to resolve that issue.

## Composer authentication

You must authenticate yourself to install extensions from the Shopware store via composer. In your local development environment, this is possible by creating an `auth.json` file that contains your auth token. However, this file shouldn't be committed to the repository.

The following command adds your authentication token to the secure environment variable storage of Shopware Paas. This variable (contains the content which would otherwise be in `auth.json`) will be available during the build step and be automatically picked up by the composer.

```bash
shopware variable:create --level project --name env:COMPOSER_AUTH --json true --visible-runtime false --sensitive true --visible-build true --value '{"bearer": {"packages.shopware.com": "%place your key here%"}}'
```

Make sure to replace `%place your key here%` with your actual token. You can find your token by clicking 'Install with Composer' in your Shopware Account.

## Extending Shopware - plugins and apps

The PaaS recipe uses the [Composer plugin loader](../../guides/hosting/installation-updates/cluster-setup#composer-plugin-loader).

## Manually trigger rebuilds

Sometimes, you might want to trigger a rebuild and deploy of your environment without pushing new code to your project. To do this for your main environment, create a `REBUILD_DATE` environment variable. This triggers a build right away to propagate the variable.

```bash
shopware variable:create --environment main --level environment --prefix env --name REBUILD_DATE --value "$(date)" --visible-build true
```

To force a rebuild at any time, update the variable with a new value:

```bash
shopware variable:update --environment main --value "$(date)" "env:REBUILD_DATE"
```

This forces your application to be built even if no code has changed.

---

---
url: /docs/v6.6/products/paas/shopware-paas/build-deploy.md
---

# Build and Deploy

Now that we have set up the repository, we are ready to push changes to your PaaS environment.

The key concept is that your PaaS project is a git repository. Every time you push to that repository, a new version of your store will be created from the source code and deployed. Different environments (e.g., dev-previews, staging, and production) are mapped by corresponding branches.

## Push main branch

To push your latest changes, run the following commands from your terminal:

```bash{3}
git add .
git commit -m "Applied new configuration"
git push -u shopware main
```

First, we stage all changes and then add them as a new commit. Then, we push them to our `shopware` origin (remember, the one for our PaaS environment) on the `main` branch.

This will trigger a new build with a subsequent deploy consisting of the following steps:

| Build                                         | Deploy                                          |
|-----------------------------------------------|-------------------------------------------------|
| Configuration validation                      | Hold app requests                               |
| Build container image                         | Unmount live containers                         |
| Installing dependencies                       | Mount file systems                              |
| Run [build hook](./setup-template#build-hook) | Run [deploy hook](./setup-template#deploy-hook) |
| Building app image                            | Serve requests                                  |

After both steps have been executed successfully (you will get extensive logging about the process), you will be able to see the deployed store on a link presented at the end of the deployment.

## First deployment

The first time the site is deployed, Shopware's command line installer will run and initialize Shopware. It will not run again unless the `install.lock` file is removed. **Do not remove that file unless you want the installer to run on the next deploy.**

The installer will create an administrator account with the default credentials.

| username | password   |
|----------|------------|
| `admin`  | `shopware` |

Make sure to change this password immediately in your Administration account settings. Not doing so is a security risk.

## Composer authentication

You must authenticate yourself to install extensions from the Shopware store via composer. In your local development environment, this is possible by creating an `auth.json` file that contains your auth token. However, this file shouldn't be committed to the repository.

The following command adds your authentication token to the secure environment variable storage of Shopware Paas. This variable (contains the content which would otherwise be in `auth.json`) will be available during the build step and be automatically picked up by the composer.

```bash
shopware variable:create --level project --name env:COMPOSER_AUTH --json true --visible-runtime false --sensitive true --visible-build true --value '{"bearer": {"packages.shopware.com": "%place your key here%"}}'
```

Make sure to replace `%place your key here%` with your actual token. You can find your token by clicking 'Install with Composer' in your Shopware Account.

## Extending Shopware - plugins and apps

The PaaS recipe uses the [Composer plugin loader](../../../guides/hosting/installation-updates/cluster-setup#composer-plugin-loader).

## Manually trigger rebuilds

Sometimes, you might want to trigger a rebuild and deploy of your environment without pushing new code to your project. To do this for your main environment, create a `REBUILD_DATE` environment variable. This triggers a build right away to propagate the variable.

```bash
shopware variable:create --environment main --level environment --prefix env --name REBUILD_DATE --value "$(date)" --visible-build true
```

To force a rebuild at any time, update the variable with a new value:

```bash
shopware variable:update --environment main --value "$(date)" "env:REBUILD_DATE"
```

This forces your application to be built even if no code has changed.

---

---
url: >-
  /docs/resources/references/adr/2026-04-16-storefront-component-build-time-scss.md
---

# Build-time SCSS compilation for Storefront components

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2026-04-16-storefront-component-build-time-scss.md)
:::

## Context

* The Storefront component system introduces theme-agnostic Twig UX components that can be contributed by the Storefront, plugins, and apps.
* The existing SCSS compilation pipeline runs inside PHP (`ThemeCompiler` via `scssphp/scssphp`) as part of `theme:compile`. It was designed for the monolithic per-theme stylesheet (`all.css`) and is tightly coupled to the theme lifecycle.
* Running component SCSS through the PHP compiler would mean component styles are recompiled on every `theme:compile`, even when the component source has not changed.
* The PHP compiler does not have access to the same Sass load paths, Node.js ecosystem packages, or modern Sass features that are available in the JS build toolchain.
* Compiling component SCSS inside the PHP compiler would also require the compiler to know which component files belong to which bundle, adding more complexity to the theme system.
* For apps, component source files are only available inside the app's zip archive. Resolving them through the PHP compiler would require downloading and unpacking the zip on every `theme:compile` just to discover and process SCSS files.

## Decision

* Component SCSS is compiled at **build time** by Vite (the same toolchain already used to compile component JavaScript), not by the PHP theme compiler.
* Each bundle's `Resources/views/components/**/*.scss` files are compiled to individual CSS files and placed in `Resources/public/storefront/components/` alongside their JS counterparts.
* The compiled CSS files are theme-agnostic and are published through Shopware's normal asset flow (`assets:install` to `public/bundles/<bundle>/storefront/components`). Theme compile reads bundle-local Vite build meta files and provides CSS information for components in the import map saved in the theme runtime config.
* Theme customisation that previously relied on injecting SCSS variables at compile time (e.g. `$sw-color-brand-primary`) is replaced by **native CSS custom properties** (`var(--sw-color-brand-primary)`). The current active theme's configuration is written as a `<style>` block of `--sw-*` custom properties into the storefront page template at render time.

## Consequences

* **Component SCSS cannot use SCSS theme variables** (`$sw-*`). Components that need runtime-configurable values must use CSS custom properties (`var(--sw-*)`). SCSS abstracts from Bootstrap or the Shopware skin layer (mixins, functions, fixed design tokens) remain fully available.
* **Component SCSS cannot use runtime feature-flag state**. Feature flags are runtime information, while component SCSS is compiled at build time. Conditional styling that depends on feature flags must be handled at runtime (for example via markup/classes/data attributes or JavaScript), not via SCSS feature checks.
* Component CSS is compiled once per deployment, not on every `theme:compile`. A build step (`composer build:js:storefront` or the individual component build) must run whenever component SCSS source changes.
* Developers adding a new bundle with components must ensure their component stylesheets do not depend on SCSS variables that are only resolved at theme-compile time.
* Extensions (plugins and apps) must ship the pre-compiled CSS files as part of their release artifact. The compiled output from `Resources/public/storefront/components/` must be included in the extension files so that they can be copied without requiring a build step on the merchant's server.

---

---
url: /docs/guides/hosting/installation-updates/deployments/build-w-o-db.md
---

# Building Administration and Storefront Assets Without a Database

It is common to prebuild assets in professional deployments to deploy the build artifact assets to the production environment. This task is mostly done by a CI job that doesn't have access to the production database. Shopware needs access to the database to look up the installed extensions/load the configured theme variables. To be able to build the assets without a database, we can use static dumped files. All extensions need to be required by Composer to be able to be loaded by the `ComposerPluginLoader`.

::: warning
This guide requires Shopware 6.4.4.0 or higher.
:::

## Compiling the Administration without database

By default, Shopware builds the Administration without extensions if there is no database connection. To include the extensions without a database, you will need to use the `ComposerPluginLoader`. This determines the used plugins by looking up the installed project dependencies. To get this working, the plugin needs to be required in the system using `composer req [package/name]`.

There is a file `bin/ci` which uses the `ComposerPluginLoader` and can be used instead of `bin/console`.
Using this, you can dump the plugins for the Administration with the new file without a database using the command `bin/ci bundle:dump`. It is recommended to call `bin/ci` instead of `bin/console` in the `bin/*.js` scripts, which can be achieved by setting the environment variable `CI=1`.

## Compiling the Storefront without database

To compile the Storefront theme, you will need the theme variables from the database. To allow compiling it without a database, it is possible to dump the variables to the private file system of Shopware. This file system interacts with the local folder `files/theme-config` by default, but for it to be compiled, it should be shared such that settings are shared across deployments. This can be achieved, for example, by using a [storage adapter like s3](../../infrastructure/filesystem.md). The configuration can be dumped using the command `bin/console theme:dump`, or it happens automatically when changing theme settings or assigning a new theme.

This means that you still **need a dumped configuration from a system with a working database setup**. You then need to copy these files to your setup without a database and follow the steps below.

By default, Shopware still tries to load configurations from the database. In the next step, you will need to change the loader to `StaticFileConfigLoader`. To change that, you will need to create a new file, `config/packages/storefront.yaml` with the following content:

```yaml
storefront:
   theme:
       config_loader_id: Shopware\Storefront\Theme\ConfigLoader\StaticFileConfigLoader
       available_theme_provider: Shopware\Storefront\Theme\ConfigLoader\StaticFileAvailableThemeProvider
       theme_path_builder_id: Shopware\Storefront\Theme\MD5ThemePathBuilder
```

This will force the theme compiler to use the static dumped file instead of looking into the database.

::: info
Warnings about Database errors can still occur but will be caught and should be ignored in this case.
:::

The dumped files should be found in the directory `files/theme-config`

### Example

directory (files/theme-config):

```text
a729322c1f4e4b4e851137c807b4f363.json
index.json
```

index.json

```json
{"99ef1e95716d43d7be78e9d9921c7163":"a729322c1f4e4b4e851137c807b4f363"}
```

```json
{
  "extensions": [],
  "themeConfig": {
    "fields": {
      "sw-color-brand-primary": {
        "type": "color",
        "value": "#ff0000",
        "editable": true,
        "block": "themeColors",
        "order": 100
      },
      "sw-color-brand-secondary": {
        "type": "color",
        "value": "#3d444d",
        "editable": true,
        "block": "themeColors",
        "order": 200
      },
      "sw-border-color": {
        "type": "color",
        "value": "#798490",
        "editable": true,
        "block": "themeColors",
        "order": 300
      },
      "sw-background-color": {
        "type": "color",
        "value": "#fff",
        "editable": true,
        "block": "themeColors",
        "order": 400
      },
      "sw-color-success": {
        "type": "color",
        "value": "#3cc261",
        "editable": true,
        "block": "statusColors",
        "order": 100
      },
      "sw-color-info": {
        "type": "color",
        "value": "#26b6cf",
        "editable": true,
        "block": "statusColors",
        "order": 200
      },
      "sw-color-warning": {
        "type": "color",
        "value": "#ffbd5d",
        "editable": true,
        "block": "statusColors",
        "order": 300
      },
      "sw-color-danger": {
        "type": "color",
        "value": "#e52427",
        "editable": true,
        "block": "statusColors",
        "order": 400
      },
      "sw-font-family-base": {
        "type": "fontFamily",
        "value": "'Inter', sans-serif",
        "editable": true,
        "block": "typography",
        "order": 100
      },
      "sw-text-color": {
        "type": "color",
        "value": "#2b3136",
        "editable": true,
        "block": "typography",
        "order": 200
      },
      "sw-font-family-headline": {
        "type": "fontFamily",
        "value": "'Inter', sans-serif",
        "editable": true,
        "block": "typography",
        "order": 300
      },
      "sw-headline-color": {
        "type": "color",
        "value": "#2b3136",
        "editable": true,
        "block": "typography",
        "order": 400
      },
      "sw-color-price": {
        "type": "color",
        "value": "#2b3136",
        "editable": true,
        "block": "eCommerce",
        "order": 100
      },
      "sw-color-buy-button": {
        "type": "color",
        "value": "#0b539b",
        "editable": true,
        "block": "eCommerce",
        "order": 200
      },
      "sw-color-buy-button-text": {
        "type": "color",
        "value": "#fff",
        "editable": true,
        "block": "eCommerce",
        "order": 300
      },
      "sw-logo-desktop": {
        "type": "media",
        "value": "http:\/\/shopware.local\/media\/64\/17\/g0\/1678462492\/demostore-logo.png",
        "editable": true,
        "block": "media",
        "order": 100,
        "fullWidth": true
      },
      "sw-logo-tablet": {
        "type": "media",
        "value": "http:\/\/shopware.local\/media\/64\/17\/g0\/1678462492\/demostore-logo.png",
        "editable": true,
        "block": "media",
        "order": 200,
        "fullWidth": true
      },
      "sw-logo-mobile": {
        "type": "media",
        "value": "http:\/\/shopware.local\/media\/64\/17\/g0\/1678462492\/demostore-logo.png",
        "editable": true,
        "block": "media",
        "order": 300,
        "fullWidth": true
      },
      "sw-logo-share": {
        "type": "media",
        "value": "",
        "editable": true,
        "block": "media",
        "order": 400
      },
      "sw-logo-favicon": {
        "type": "media",
        "value": "http:\/\/shopware.local\/media\/d3\/f5\/b7\/1678462492\/favicon.png",
        "editable": true,
        "block": "media",
        "order": 500
      }
    },
    "sw-color-brand-primary": {
      "extensions": [],
      "name": "sw-color-brand-primary",
      "type": "color",
      "value": "#0b539b",
      "editable": true,
      "block": "themeColors",
      "section": null,
      "tab": null,
      "order": 100,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-brand-secondary": {
      "extensions": [],
      "name": "sw-color-brand-secondary",
      "type": "color",
      "value": "#3d444d",
      "editable": true,
      "block": "themeColors",
      "section": null,
      "tab": null,
      "order": 200,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-border-color": {
      "extensions": [],
      "name": "sw-border-color",
      "type": "color",
      "value": "#798490",
      "editable": true,
      "block": "themeColors",
      "section": null,
      "tab": null,
      "order": 300,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-background-color": {
      "extensions": [],
      "name": "sw-background-color",
      "type": "color",
      "value": "#fff",
      "editable": true,
      "block": "themeColors",
      "section": null,
      "tab": null,
      "order": 400,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-success": {
      "extensions": [],
      "name": "sw-color-success",
      "type": "color",
      "value": "#3cc261",
      "editable": true,
      "block": "statusColors",
      "section": null,
      "tab": null,
      "order": 100,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-info": {
      "extensions": [],
      "name": "sw-color-info",
      "type": "color",
      "value": "#26b6cf",
      "editable": true,
      "block": "statusColors",
      "section": null,
      "tab": null,
      "order": 200,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-warning": {
      "extensions": [],
      "name": "sw-color-warning",
      "type": "color",
      "value": "#ffbd5d",
      "editable": true,
      "block": "statusColors",
      "section": null,
      "tab": null,
      "order": 300,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-danger": {
      "extensions": [],
      "name": "sw-color-danger",
      "type": "color",
      "value": "#e52427",
      "editable": true,
      "block": "statusColors",
      "section": null,
      "tab": null,
      "order": 400,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-font-family-base": {
      "extensions": [],
      "name": "sw-font-family-base",
      "type": "fontFamily",
      "value": "'Inter', sans-serif",
      "editable": true,
      "block": "typography",
      "section": null,
      "tab": null,
      "order": 100,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-text-color": {
      "extensions": [],
      "name": "sw-text-color",
      "type": "color",
      "value": "#2b3136",
      "editable": true,
      "block": "typography",
      "section": null,
      "tab": null,
      "order": 200,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-font-family-headline": {
      "extensions": [],
      "name": "sw-font-family-headline",
      "type": "fontFamily",
      "value": "'Inter', sans-serif",
      "editable": true,
      "block": "typography",
      "section": null,
      "tab": null,
      "order": 300,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-headline-color": {
      "extensions": [],
      "name": "sw-headline-color",
      "type": "color",
      "value": "#2b3136",
      "editable": true,
      "block": "typography",
      "section": null,
      "tab": null,
      "order": 400,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-price": {
      "extensions": [],
      "name": "sw-color-price",
      "type": "color",
      "value": "#2b3136",
      "editable": true,
      "block": "eCommerce",
      "section": null,
      "tab": null,
      "order": 100,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-buy-button": {
      "extensions": [],
      "name": "sw-color-buy-button",
      "type": "color",
      "value": "#0b539b",
      "editable": true,
      "block": "eCommerce",
      "section": null,
      "tab": null,
      "order": 200,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-buy-button-text": {
      "extensions": [],
      "name": "sw-color-buy-button-text",
      "type": "color",
      "value": "#fff",
      "editable": true,
      "block": "eCommerce",
      "section": null,
      "tab": null,
      "order": 300,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-logo-desktop": {
      "extensions": [],
      "name": "sw-logo-desktop",
      "type": "media",
      "value": "18f45736ef6a4beea22d867573bd1af6",
      "editable": true,
      "block": "media",
      "section": null,
      "tab": null,
      "order": 100,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": true
    },
    "sw-logo-tablet": {
      "extensions": [],
      "name": "sw-logo-tablet",
      "type": "media",
      "value": "18f45736ef6a4beea22d867573bd1af6",
      "editable": true,
      "block": "media",
      "section": null,
      "tab": null,
      "order": 200,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": true
    },
    "sw-logo-mobile": {
      "extensions": [],
      "name": "sw-logo-mobile",
      "type": "media",
      "value": "18f45736ef6a4beea22d867573bd1af6",
      "editable": true,
      "block": "media",
      "section": null,
      "tab": null,
      "order": 300,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": true
    },
    "sw-logo-share": {
      "extensions": [],
      "name": "sw-logo-share",
      "type": "media",
      "value": "",
      "editable": true,
      "block": "media",
      "section": null,
      "tab": null,
      "order": 400,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-logo-favicon": {
      "extensions": [],
      "name": "sw-logo-favicon",
      "type": "media",
      "value": "7bf586ac4343480292ebd5f349e16607",
      "editable": true,
      "block": "media",
      "section": null,
      "tab": null,
      "order": 500,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    }
  },
  "name": "Swag Dev Theme",
  "previewMedia": "custom\/apps\/SwagDevTheme\/Resources\/app\/storefront\/src\/assets\/images\/showroomPreview.png",
  "author": "Shopware AG",
  "isTheme": true,
  "styleFiles": [
    {
      "extensions": [],
      "filepath": "@Storefront",
      "resolveMapping": []
    }
  ],
  "scriptFiles": [
    {
      "extensions": [],
      "filepath": "@Storefront",
      "resolveMapping": []
    }
  ],
  "storefrontEntryFilepath": null,
  "basePath": "custom\/apps\/SwagDevTheme\/Resources",
  "assetPaths": [
    "custom\/apps\/SwagDevTheme\/Resources\/app\/storefront\/src\/assets"
  ],
  "viewInheritance": [
    "@Storefront",
    "@SwagCustomizedProducts",
    "@SwagPayPal",
    "@SwagAmazonPay",
    "@SwagCmsExtensions",
    "@SwagB2bPlatform",
    "@SwagDevTheme",
    "@Plugins"
  ],
  "iconSets": {
    "showroom": "app\/storefront\/src\/assets\/icon\/showroom"
  },
  "technicalName": "SwagDevTheme"
}
```

```json
{
  "extensions": [],
  "themeConfig": {
    "blocks": {
      "themeColors": {
        "label": {
          "en-GB": "Theme colours",
          "de-DE": "Theme-Farben"
        }
      },
      "typography": {
        "label": {
          "en-GB": "Typography",
          "de-DE": "Typografie"
        }
      },
      "eCommerce": {
        "label": {
          "en-GB": "E-Commerce",
          "de-DE": "E-Commerce"
        }
      },
      "statusColors": {
        "label": {
          "en-GB": "Status messages",
          "de-DE": "Status-Ausgaben"
        }
      },
      "media": {
        "label": {
          "en-GB": "Media",
          "de-DE": "Medien"
        }
      },
      "unordered": {
        "label": {
          "en-GB": "Misc",
          "de-DE": "Sonstige"
        }
      }
    },
    "fields": {
      "sw-color-brand-primary": {
        "label": {
          "en-GB": "Primary colour",
          "de-DE": "Prim\u00e4rfarbe"
        },
        "type": "color",
        "value": "#ff0000",
        "editable": true,
        "block": "themeColors",
        "order": 100
      },
      "sw-color-brand-secondary": {
        "label": {
          "en-GB": "Secondary colour",
          "de-DE": "Sekund\u00e4rfarbe"
        },
        "type": "color",
        "value": "#3d444d",
        "editable": true,
        "block": "themeColors",
        "order": 200
      },
      "sw-border-color": {
        "label": {
          "en-GB": "Border",
          "de-DE": "Rahmen"
        },
        "type": "color",
        "value": "#798490",
        "editable": true,
        "block": "themeColors",
        "order": 300
      },
      "sw-background-color": {
        "label": {
          "en-GB": "Background",
          "de-DE": "Hintergrund"
        },
        "type": "color",
        "value": "#fff",
        "editable": true,
        "block": "themeColors",
        "order": 400
      },
      "sw-color-success": {
        "label": {
          "en-GB": "Success",
          "de-DE": "Erfolg"
        },
        "type": "color",
        "value": "#3cc261",
        "editable": true,
        "block": "statusColors",
        "order": 100
      },
      "sw-color-info": {
        "label": {
          "en-GB": "Information",
          "de-DE": "Information"
        },
        "type": "color",
        "value": "#26b6cf",
        "editable": true,
        "block": "statusColors",
        "order": 200
      },
      "sw-color-warning": {
        "label": {
          "en-GB": "Notice",
          "de-DE": "Hinweis"
        },
        "type": "color",
        "value": "#ffbd5d",
        "editable": true,
        "block": "statusColors",
        "order": 300
      },
      "sw-color-danger": {
        "label": {
          "en-GB": "Error",
          "de-DE": "Fehler"
        },
        "type": "color",
        "value": "#e52427",
        "editable": true,
        "block": "statusColors",
        "order": 400
      },
      "sw-font-family-base": {
        "label": {
          "en-GB": "Fonttype text",
          "de-DE": "Schriftart Text"
        },
        "type": "fontFamily",
        "value": "'Inter', sans-serif",
        "editable": true,
        "block": "typography",
        "order": 100
      },
      "sw-text-color": {
        "label": {
          "en-GB": "Text colour",
          "de-DE": "Textfarbe"
        },
        "type": "color",
        "value": "#2b3136",
        "editable": true,
        "block": "typography",
        "order": 200
      },
      "sw-font-family-headline": {
        "label": {
          "en-GB": "Fonttype headline",
          "de-DE": "Schriftart \u00dcberschrift"
        },
        "type": "fontFamily",
        "value": "'Inter', sans-serif",
        "editable": true,
        "block": "typography",
        "order": 300
      },
      "sw-headline-color": {
        "label": {
          "en-GB": "Headline colour",
          "de-DE": "\u00dcberschriftfarbe"
        },
        "type": "color",
        "value": "#2b3136",
        "editable": true,
        "block": "typography",
        "order": 400
      },
      "sw-color-price": {
        "label": {
          "en-GB": "Price",
          "de-DE": "Preis"
        },
        "type": "color",
        "value": "#2b3136",
        "editable": true,
        "block": "eCommerce",
        "order": 100
      },
      "sw-color-buy-button": {
        "label": {
          "en-GB": "Buy button",
          "de-DE": "Kaufen-Button"
        },
        "type": "color",
        "value": "#0b539b",
        "editable": true,
        "block": "eCommerce",
        "order": 200
      },
      "sw-color-buy-button-text": {
        "label": {
          "en-GB": "Buy button text",
          "de-DE": "Kaufen-Button Text"
        },
        "type": "color",
        "value": "#fff",
        "editable": true,
        "block": "eCommerce",
        "order": 300
      },
      "sw-logo-desktop": {
        "label": {
          "en-GB": "Desktop",
          "de-DE": "Desktop"
        },
        "helpText": {
          "en-GB": "Displayed on viewport sizes above 991px and as a fallback on smaller viewports, if no other logo is set.",
          "de-DE": "Wird bei Ansichten \u00fcber 991px angezeigt und als Alternative bei kleineren Aufl\u00f6sungen, f\u00fcr die kein anderes Logo eingestellt ist."
        },
        "type": "media",
        "value": "http:\/\/shopware.local\/media\/64\/17\/g0\/1678462492\/demostore-logo.png",
        "editable": true,
        "block": "media",
        "order": 100,
        "fullWidth": true
      },
      "sw-logo-tablet": {
        "label": {
          "en-GB": "Tablet",
          "de-DE": "Tablet"
        },
        "helpText": {
          "en-GB": "Displayed between a viewport of 767px to 991px",
          "de-DE": "Wird zwischen einem viewport von 767px bis 991px angezeigt"
        },
        "type": "media",
        "value": "http:\/\/shopware.local\/media\/64\/17\/g0\/1678462492\/demostore-logo.png",
        "editable": true,
        "block": "media",
        "order": 200,
        "fullWidth": true
      },
      "sw-logo-mobile": {
        "label": {
          "en-GB": "Mobile",
          "de-DE": "Mobil"
        },
        "helpText": {
          "en-GB": "Displayed up to a viewport of 767px",
          "de-DE": "Wird bis zu einem Viewport von 767px angezeigt"
        },
        "type": "media",
        "value": "http:\/\/shopware.local\/media\/64\/17\/g0\/1678462492\/demostore-logo.png",
        "editable": true,
        "block": "media",
        "order": 300,
        "fullWidth": true
      },
      "sw-logo-share": {
        "label": {
          "en-GB": "App & share icon",
          "de-DE": "App- & Share-Icon"
        },
        "type": "media",
        "value": "",
        "editable": true,
        "block": "media",
        "order": 400
      },
      "sw-logo-favicon": {
        "label": {
          "en-GB": "Favicon",
          "de-DE": "Favicon"
        },
        "type": "media",
        "value": "http:\/\/shopware.local\/media\/d3\/f5\/b7\/1678462492\/favicon.png",
        "editable": true,
        "block": "media",
        "order": 500
      }
    },
    "sw-color-brand-primary": {
      "extensions": [],
      "name": "sw-color-brand-primary",
      "label": {
        "en-GB": "Primary colour",
        "de-DE": "Prim\u00e4rfarbe"
      },
      "helpText": null,
      "type": "color",
      "value": "#0b539b",
      "editable": true,
      "block": "themeColors",
      "section": null,
      "tab": null,
      "order": 100,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-brand-secondary": {
      "extensions": [],
      "name": "sw-color-brand-secondary",
      "label": {
        "en-GB": "Secondary colour",
        "de-DE": "Sekund\u00e4rfarbe"
      },
      "helpText": null,
      "type": "color",
      "value": "#3d444d",
      "editable": true,
      "block": "themeColors",
      "section": null,
      "tab": null,
      "order": 200,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-border-color": {
      "extensions": [],
      "name": "sw-border-color",
      "label": {
        "en-GB": "Border",
        "de-DE": "Rahmen"
      },
      "helpText": null,
      "type": "color",
      "value": "#798490",
      "editable": true,
      "block": "themeColors",
      "section": null,
      "tab": null,
      "order": 300,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-background-color": {
      "extensions": [],
      "name": "sw-background-color",
      "label": {
        "en-GB": "Background",
        "de-DE": "Hintergrund"
      },
      "helpText": null,
      "type": "color",
      "value": "#fff",
      "editable": true,
      "block": "themeColors",
      "section": null,
      "tab": null,
      "order": 400,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-success": {
      "extensions": [],
      "name": "sw-color-success",
      "label": {
        "en-GB": "Success",
        "de-DE": "Erfolg"
      },
      "helpText": null,
      "type": "color",
      "value": "#3cc261",
      "editable": true,
      "block": "statusColors",
      "section": null,
      "tab": null,
      "order": 100,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-info": {
      "extensions": [],
      "name": "sw-color-info",
      "label": {
        "en-GB": "Information",
        "de-DE": "Information"
      },
      "helpText": null,
      "type": "color",
      "value": "#26b6cf",
      "editable": true,
      "block": "statusColors",
      "section": null,
      "tab": null,
      "order": 200,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-warning": {
      "extensions": [],
      "name": "sw-color-warning",
      "label": {
        "en-GB": "Notice",
        "de-DE": "Hinweis"
      },
      "helpText": null,
      "type": "color",
      "value": "#ffbd5d",
      "editable": true,
      "block": "statusColors",
      "section": null,
      "tab": null,
      "order": 300,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-danger": {
      "extensions": [],
      "name": "sw-color-danger",
      "label": {
        "en-GB": "Error",
        "de-DE": "Fehler"
      },
      "helpText": null,
      "type": "color",
      "value": "#e52427",
      "editable": true,
      "block": "statusColors",
      "section": null,
      "tab": null,
      "order": 400,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-font-family-base": {
      "extensions": [],
      "name": "sw-font-family-base",
      "label": {
        "en-GB": "Fonttype text",
        "de-DE": "Schriftart Text"
      },
      "helpText": null,
      "type": "fontFamily",
      "value": "'Inter', sans-serif",
      "editable": true,
      "block": "typography",
      "section": null,
      "tab": null,
      "order": 100,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-text-color": {
      "extensions": [],
      "name": "sw-text-color",
      "label": {
        "en-GB": "Text colour",
        "de-DE": "Textfarbe"
      },
      "helpText": null,
      "type": "color",
      "value": "#2b3136",
      "editable": true,
      "block": "typography",
      "section": null,
      "tab": null,
      "order": 200,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-font-family-headline": {
      "extensions": [],
      "name": "sw-font-family-headline",
      "label": {
        "en-GB": "Fonttype headline",
        "de-DE": "Schriftart \u00dcberschrift"
      },
      "helpText": null,
      "type": "fontFamily",
      "value": "'Inter', sans-serif",
      "editable": true,
      "block": "typography",
      "section": null,
      "tab": null,
      "order": 300,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-headline-color": {
      "extensions": [],
      "name": "sw-headline-color",
      "label": {
        "en-GB": "Headline colour",
        "de-DE": "\u00dcberschriftfarbe"
      },
      "helpText": null,
      "type": "color",
      "value": "#2b3136",
      "editable": true,
      "block": "typography",
      "section": null,
      "tab": null,
      "order": 400,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-price": {
      "extensions": [],
      "name": "sw-color-price",
      "label": {
        "en-GB": "Price",
        "de-DE": "Preis"
      },
      "helpText": null,
      "type": "color",
      "value": "#2b3136",
      "editable": true,
      "block": "eCommerce",
      "section": null,
      "tab": null,
      "order": 100,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-buy-button": {
      "extensions": [],
      "name": "sw-color-buy-button",
      "label": {
        "en-GB": "Buy button",
        "de-DE": "Kaufen-Button"
      },
      "helpText": null,
      "type": "color",
      "value": "#0b539b",
      "editable": true,
      "block": "eCommerce",
      "section": null,
      "tab": null,
      "order": 200,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-buy-button-text": {
      "extensions": [],
      "name": "sw-color-buy-button-text",
      "label": {
        "en-GB": "Buy button text",
        "de-DE": "Kaufen-Button Text"
      },
      "helpText": null,
      "type": "color",
      "value": "#fff",
      "editable": true,
      "block": "eCommerce",
      "section": null,
      "tab": null,
      "order": 300,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-logo-desktop": {
      "extensions": [],
      "name": "sw-logo-desktop",
      "label": {
        "en-GB": "Desktop",
        "de-DE": "Desktop"
      },
      "helpText": {
        "en-GB": "Displayed on viewport sizes above 991px and as a fallback on smaller viewports, if no other logo is set.",
        "de-DE": "Wird bei Ansichten \u00fcber 991px angezeigt und als Alternative bei kleineren Aufl\u00f6sungen, f\u00fcr die kein anderes Logo eingestellt ist."
      },
      "type": "media",
      "value": "18f45736ef6a4beea22d867573bd1af6",
      "editable": true,
      "block": "media",
      "section": null,
      "tab": null,
      "order": 100,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": true
    },
    "sw-logo-tablet": {
      "extensions": [],
      "name": "sw-logo-tablet",
      "label": {
        "en-GB": "Tablet",
        "de-DE": "Tablet"
      },
      "helpText": {
        "en-GB": "Displayed between a viewport of 767px to 991px",
        "de-DE": "Wird zwischen einem viewport von 767px bis 991px angezeigt"
      },
      "type": "media",
      "value": "18f45736ef6a4beea22d867573bd1af6",
      "editable": true,
      "block": "media",
      "section": null,
      "tab": null,
      "order": 200,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": true
    },
    "sw-logo-mobile": {
      "extensions": [],
      "name": "sw-logo-mobile",
      "label": {
        "en-GB": "Mobile",
        "de-DE": "Mobil"
      },
      "helpText": {
        "en-GB": "Displayed up to a viewport of 767px",
        "de-DE": "Wird bis zu einem Viewport von 767px angezeigt"
      },
      "type": "media",
      "value": "18f45736ef6a4beea22d867573bd1af6",
      "editable": true,
      "block": "media",
      "section": null,
      "tab": null,
      "order": 300,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": true
    },
    "sw-logo-share": {
      "extensions": [],
      "name": "sw-logo-share",
      "label": {
        "en-GB": "App & share icon",
        "de-DE": "App- & Share-Icon"
      },
      "helpText": null,
      "type": "media",
      "value": "",
      "editable": true,
      "block": "media",
      "section": null,
      "tab": null,
      "order": 400,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-logo-favicon": {
      "extensions": [],
      "name": "sw-logo-favicon",
      "label": {
        "en-GB": "Favicon",
        "de-DE": "Favicon"
      },
      "helpText": null,
      "type": "media",
      "value": "7bf586ac4343480292ebd5f349e16607",
      "editable": true,
      "block": "media",
      "section": null,
      "tab": null,
      "order": 500,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    }
  },
  "name": "Swag Dev Theme",
  "previewMedia": "custom\/apps\/SwagDevTheme\/Resources\/app\/storefront\/src\/assets\/images\/showroomPreview.png",
  "author": "Shopware AG",
  "isTheme": true,
  "styleFiles": [
    {
      "extensions": [],
      "filepath": "@Storefront",
      "resolveMapping": []
    }
  ],
  "scriptFiles": [
    {
      "extensions": [],
      "filepath": "@Storefront",
      "resolveMapping": []
    }
  ],
  "storefrontEntryFilepath": null,
  "basePath": "custom\/apps\/SwagDevTheme\/Resources",
  "assetPaths": [
    "custom\/apps\/SwagDevTheme\/Resources\/app\/storefront\/src\/assets"
  ],
  "viewInheritance": [
    "@Storefront",
    "@SwagCustomizedProducts",
    "@SwagPayPal",
    "@SwagAmazonPay",
    "@SwagCmsExtensions",
    "@SwagB2bPlatform",
    "@SwagDevTheme",
    "@Plugins"
  ],
  "iconSets": {
    "showroom": "app\/storefront\/src\/assets\/icon\/showroom"
  },
  "technicalName": "SwagDevTheme"
}
```

### Partially compiling the Storefront

You can also build just the JavaScript bundle using `CI=1 SHOPWARE_SKIP_THEME_COMPILE=true PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true shopware-cli project storefront-build` (without the need for the above loader) in your CI. After that, run `bin/console theme:dump` on your production system when the database is available. This will happen automatically if theme variables are changed via the admin panel.

## Cache directory and hash implications

When using `bin/ci` or `ComposerPluginLoader`, the cache directory name includes a hash computed from active plugins. Since `ComposerPluginLoader` marks all Composer-installed plugins as active, while `DbalKernelPluginLoader` (used by web requests) respects the database `active` column, the cache hashes can differ.

This means:

* Cache warmed with `bin/ci` uses a hash based on all Composer-installed plugins being active
* Production web requests use a hash based on the actual database plugin state
* If any plugin is deactivated in the database, web requests create a new cache directory

To ensure cache is properly cleared across all configurations, use `cache:clear:all` instead of `cache:clear` in deployment scripts.

---

---
url: /docs/v6.5/guides/hosting/installation-updates/deployments/build-w-o-db.md
---

# Building assets of Administration and Storefront without a Database

It is common to prebuild assets in professional deployments to deploy the build artifact assets to the production environment. This task is mostly done by a CI job that doesn't have access to the production database. Shopware needs access to the database to look up the installed extensions/load the configured theme variables. To be able to build the assets without a database, we can use static dumped files. All extensions need to be required by Composer to be able to be loaded by the `ComposerPluginLoader`.

::: warning
This guide requires Shopware 6.4.4.0 or higher.
:::

## Compiling the Administration without database

By default, Shopware builds the Administration without extensions if there is no database connection. To include the extensions without a database, you will need to use the `ComposerPluginLoader`. This determines the used plugins by looking up the installed project dependencies. To get this working, the plugin needs to be required in the system using `composer req [package/name]`.

There is a file `bin/ci` which uses the `ComposerPluginLoader` and can be used instead of `bin/console`.
Using this, you can dump the plugins for the Administration with the new file without a database using the command `bin/ci bundle:dump`. It is recommended to call `bin/ci` instead of `bin/console` in the `bin/*.js` scripts, which can be achieved by setting the environment variable `CI=1`.

## Compiling the Storefront without database

To compile the Storefront theme, you will need the theme variables from the database. To allow compiling it without a database, it is possible to dump the variables to the private file system of Shopware. This file system interacts with the local folder `files/theme-config` by default, but for it to be compiled, it should be shared such that settings are shared across deployments. This can be achieved, for example, by using a [storage adapter like s3](../../infrastructure/filesystem). The configuration can be dumped using the command `bin/console theme:dump`, or it happens automatically when changing theme settings or assigning a new theme.

This means that you still **need a dumped configuration from a system with a working database setup**. You then need to copy these files to your setup without a database and follow the steps below.

By default, Shopware still tries to load configurations from the database. In the next step, you will need to change the loader to `StaticFileConfigLoader`. To change that, you will need to create a new file, `config/packages/storefront.yaml` with the following content:

```yaml
storefront:
   theme:
       config_loader_id: Shopware\Storefront\Theme\ConfigLoader\StaticFileConfigLoader
       available_theme_provider: Shopware\Storefront\Theme\ConfigLoader\StaticFileAvailableThemeProvider
       theme_path_builder_id: Shopware\Storefront\Theme\MD5ThemePathBuilder
```

This will force the theme compiler to use the static dumped file instead of looking into the database.

::: info
Warnings about Database errors can still occur but will be caught and should be ignored in this case.
:::

The dumped files should be found in the directory `files/theme-config`

### Example

directory (files/theme-config):

```text
a729322c1f4e4b4e851137c807b4f363.json
index.json
```

index.json

```json
{"99ef1e95716d43d7be78e9d9921c7163":"a729322c1f4e4b4e851137c807b4f363"}
```

```json
{
  "extensions": [],
  "themeConfig": {
    "blocks": {
      "themeColors": {
        "label": {
          "en-GB": "Theme colours",
          "de-DE": "Theme-Farben"
        }
      },
      "typography": {
        "label": {
          "en-GB": "Typography",
          "de-DE": "Typografie"
        }
      },
      "eCommerce": {
        "label": {
          "en-GB": "E-Commerce",
          "de-DE": "E-Commerce"
        }
      },
      "statusColors": {
        "label": {
          "en-GB": "Status messages",
          "de-DE": "Status-Ausgaben"
        }
      },
      "media": {
        "label": {
          "en-GB": "Media",
          "de-DE": "Medien"
        }
      },
      "unordered": {
        "label": {
          "en-GB": "Misc",
          "de-DE": "Sonstige"
        }
      }
    },
    "fields": {
      "sw-color-brand-primary": {
        "label": {
          "en-GB": "Primary colour",
          "de-DE": "Prim\u00e4rfarbe"
        },
        "type": "color",
        "value": "#ff0000",
        "editable": true,
        "block": "themeColors",
        "order": 100
      },
      "sw-color-brand-secondary": {
        "label": {
          "en-GB": "Secondary colour",
          "de-DE": "Sekund\u00e4rfarbe"
        },
        "type": "color",
        "value": "#3d444d",
        "editable": true,
        "block": "themeColors",
        "order": 200
      },
      "sw-border-color": {
        "label": {
          "en-GB": "Border",
          "de-DE": "Rahmen"
        },
        "type": "color",
        "value": "#798490",
        "editable": true,
        "block": "themeColors",
        "order": 300
      },
      "sw-background-color": {
        "label": {
          "en-GB": "Background",
          "de-DE": "Hintergrund"
        },
        "type": "color",
        "value": "#fff",
        "editable": true,
        "block": "themeColors",
        "order": 400
      },
      "sw-color-success": {
        "label": {
          "en-GB": "Success",
          "de-DE": "Erfolg"
        },
        "type": "color",
        "value": "#3cc261",
        "editable": true,
        "block": "statusColors",
        "order": 100
      },
      "sw-color-info": {
        "label": {
          "en-GB": "Information",
          "de-DE": "Information"
        },
        "type": "color",
        "value": "#26b6cf",
        "editable": true,
        "block": "statusColors",
        "order": 200
      },
      "sw-color-warning": {
        "label": {
          "en-GB": "Notice",
          "de-DE": "Hinweis"
        },
        "type": "color",
        "value": "#ffbd5d",
        "editable": true,
        "block": "statusColors",
        "order": 300
      },
      "sw-color-danger": {
        "label": {
          "en-GB": "Error",
          "de-DE": "Fehler"
        },
        "type": "color",
        "value": "#e52427",
        "editable": true,
        "block": "statusColors",
        "order": 400
      },
      "sw-font-family-base": {
        "label": {
          "en-GB": "Fonttype text",
          "de-DE": "Schriftart Text"
        },
        "type": "fontFamily",
        "value": "'Inter', sans-serif",
        "editable": true,
        "block": "typography",
        "order": 100
      },
      "sw-text-color": {
        "label": {
          "en-GB": "Text colour",
          "de-DE": "Textfarbe"
        },
        "type": "color",
        "value": "#2b3136",
        "editable": true,
        "block": "typography",
        "order": 200
      },
      "sw-font-family-headline": {
        "label": {
          "en-GB": "Fonttype headline",
          "de-DE": "Schriftart \u00dcberschrift"
        },
        "type": "fontFamily",
        "value": "'Inter', sans-serif",
        "editable": true,
        "block": "typography",
        "order": 300
      },
      "sw-headline-color": {
        "label": {
          "en-GB": "Headline colour",
          "de-DE": "\u00dcberschriftfarbe"
        },
        "type": "color",
        "value": "#2b3136",
        "editable": true,
        "block": "typography",
        "order": 400
      },
      "sw-color-price": {
        "label": {
          "en-GB": "Price",
          "de-DE": "Preis"
        },
        "type": "color",
        "value": "#2b3136",
        "editable": true,
        "block": "eCommerce",
        "order": 100
      },
      "sw-color-buy-button": {
        "label": {
          "en-GB": "Buy button",
          "de-DE": "Kaufen-Button"
        },
        "type": "color",
        "value": "#0b539b",
        "editable": true,
        "block": "eCommerce",
        "order": 200
      },
      "sw-color-buy-button-text": {
        "label": {
          "en-GB": "Buy button text",
          "de-DE": "Kaufen-Button Text"
        },
        "type": "color",
        "value": "#fff",
        "editable": true,
        "block": "eCommerce",
        "order": 300
      },
      "sw-logo-desktop": {
        "label": {
          "en-GB": "Desktop",
          "de-DE": "Desktop"
        },
        "helpText": {
          "en-GB": "Displayed on viewport sizes above 991px and as a fallback on smaller viewports, if no other logo is set.",
          "de-DE": "Wird bei Ansichten \u00fcber 991px angezeigt und als Alternative bei kleineren Aufl\u00f6sungen, f\u00fcr die kein anderes Logo eingestellt ist."
        },
        "type": "media",
        "value": "http:\/\/shopware.local\/media\/64\/17\/g0\/1678462492\/demostore-logo.png",
        "editable": true,
        "block": "media",
        "order": 100,
        "fullWidth": true
      },
      "sw-logo-tablet": {
        "label": {
          "en-GB": "Tablet",
          "de-DE": "Tablet"
        },
        "helpText": {
          "en-GB": "Displayed between a viewport of 767px to 991px",
          "de-DE": "Wird zwischen einem viewport von 767px bis 991px angezeigt"
        },
        "type": "media",
        "value": "http:\/\/shopware.local\/media\/64\/17\/g0\/1678462492\/demostore-logo.png",
        "editable": true,
        "block": "media",
        "order": 200,
        "fullWidth": true
      },
      "sw-logo-mobile": {
        "label": {
          "en-GB": "Mobile",
          "de-DE": "Mobil"
        },
        "helpText": {
          "en-GB": "Displayed up to a viewport of 767px",
          "de-DE": "Wird bis zu einem Viewport von 767px angezeigt"
        },
        "type": "media",
        "value": "http:\/\/shopware.local\/media\/64\/17\/g0\/1678462492\/demostore-logo.png",
        "editable": true,
        "block": "media",
        "order": 300,
        "fullWidth": true
      },
      "sw-logo-share": {
        "label": {
          "en-GB": "App & share icon",
          "de-DE": "App- & Share-Icon"
        },
        "type": "media",
        "value": "",
        "editable": true,
        "block": "media",
        "order": 400
      },
      "sw-logo-favicon": {
        "label": {
          "en-GB": "Favicon",
          "de-DE": "Favicon"
        },
        "type": "media",
        "value": "http:\/\/shopware.local\/media\/d3\/f5\/b7\/1678462492\/favicon.png",
        "editable": true,
        "block": "media",
        "order": 500
      }
    },
    "sw-color-brand-primary": {
      "extensions": [],
      "name": "sw-color-brand-primary",
      "label": {
        "en-GB": "Primary colour",
        "de-DE": "Prim\u00e4rfarbe"
      },
      "helpText": null,
      "type": "color",
      "value": "#0b539b",
      "editable": true,
      "block": "themeColors",
      "section": null,
      "tab": null,
      "order": 100,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-brand-secondary": {
      "extensions": [],
      "name": "sw-color-brand-secondary",
      "label": {
        "en-GB": "Secondary colour",
        "de-DE": "Sekund\u00e4rfarbe"
      },
      "helpText": null,
      "type": "color",
      "value": "#3d444d",
      "editable": true,
      "block": "themeColors",
      "section": null,
      "tab": null,
      "order": 200,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-border-color": {
      "extensions": [],
      "name": "sw-border-color",
      "label": {
        "en-GB": "Border",
        "de-DE": "Rahmen"
      },
      "helpText": null,
      "type": "color",
      "value": "#798490",
      "editable": true,
      "block": "themeColors",
      "section": null,
      "tab": null,
      "order": 300,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-background-color": {
      "extensions": [],
      "name": "sw-background-color",
      "label": {
        "en-GB": "Background",
        "de-DE": "Hintergrund"
      },
      "helpText": null,
      "type": "color",
      "value": "#fff",
      "editable": true,
      "block": "themeColors",
      "section": null,
      "tab": null,
      "order": 400,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-success": {
      "extensions": [],
      "name": "sw-color-success",
      "label": {
        "en-GB": "Success",
        "de-DE": "Erfolg"
      },
      "helpText": null,
      "type": "color",
      "value": "#3cc261",
      "editable": true,
      "block": "statusColors",
      "section": null,
      "tab": null,
      "order": 100,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-info": {
      "extensions": [],
      "name": "sw-color-info",
      "label": {
        "en-GB": "Information",
        "de-DE": "Information"
      },
      "helpText": null,
      "type": "color",
      "value": "#26b6cf",
      "editable": true,
      "block": "statusColors",
      "section": null,
      "tab": null,
      "order": 200,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-warning": {
      "extensions": [],
      "name": "sw-color-warning",
      "label": {
        "en-GB": "Notice",
        "de-DE": "Hinweis"
      },
      "helpText": null,
      "type": "color",
      "value": "#ffbd5d",
      "editable": true,
      "block": "statusColors",
      "section": null,
      "tab": null,
      "order": 300,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-danger": {
      "extensions": [],
      "name": "sw-color-danger",
      "label": {
        "en-GB": "Error",
        "de-DE": "Fehler"
      },
      "helpText": null,
      "type": "color",
      "value": "#e52427",
      "editable": true,
      "block": "statusColors",
      "section": null,
      "tab": null,
      "order": 400,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-font-family-base": {
      "extensions": [],
      "name": "sw-font-family-base",
      "label": {
        "en-GB": "Fonttype text",
        "de-DE": "Schriftart Text"
      },
      "helpText": null,
      "type": "fontFamily",
      "value": "'Inter', sans-serif",
      "editable": true,
      "block": "typography",
      "section": null,
      "tab": null,
      "order": 100,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-text-color": {
      "extensions": [],
      "name": "sw-text-color",
      "label": {
        "en-GB": "Text colour",
        "de-DE": "Textfarbe"
      },
      "helpText": null,
      "type": "color",
      "value": "#2b3136",
      "editable": true,
      "block": "typography",
      "section": null,
      "tab": null,
      "order": 200,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-font-family-headline": {
      "extensions": [],
      "name": "sw-font-family-headline",
      "label": {
        "en-GB": "Fonttype headline",
        "de-DE": "Schriftart \u00dcberschrift"
      },
      "helpText": null,
      "type": "fontFamily",
      "value": "'Inter', sans-serif",
      "editable": true,
      "block": "typography",
      "section": null,
      "tab": null,
      "order": 300,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-headline-color": {
      "extensions": [],
      "name": "sw-headline-color",
      "label": {
        "en-GB": "Headline colour",
        "de-DE": "\u00dcberschriftfarbe"
      },
      "helpText": null,
      "type": "color",
      "value": "#2b3136",
      "editable": true,
      "block": "typography",
      "section": null,
      "tab": null,
      "order": 400,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-price": {
      "extensions": [],
      "name": "sw-color-price",
      "label": {
        "en-GB": "Price",
        "de-DE": "Preis"
      },
      "helpText": null,
      "type": "color",
      "value": "#2b3136",
      "editable": true,
      "block": "eCommerce",
      "section": null,
      "tab": null,
      "order": 100,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-buy-button": {
      "extensions": [],
      "name": "sw-color-buy-button",
      "label": {
        "en-GB": "Buy button",
        "de-DE": "Kaufen-Button"
      },
      "helpText": null,
      "type": "color",
      "value": "#0b539b",
      "editable": true,
      "block": "eCommerce",
      "section": null,
      "tab": null,
      "order": 200,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-buy-button-text": {
      "extensions": [],
      "name": "sw-color-buy-button-text",
      "label": {
        "en-GB": "Buy button text",
        "de-DE": "Kaufen-Button Text"
      },
      "helpText": null,
      "type": "color",
      "value": "#fff",
      "editable": true,
      "block": "eCommerce",
      "section": null,
      "tab": null,
      "order": 300,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-logo-desktop": {
      "extensions": [],
      "name": "sw-logo-desktop",
      "label": {
        "en-GB": "Desktop",
        "de-DE": "Desktop"
      },
      "helpText": {
        "en-GB": "Displayed on viewport sizes above 991px and as a fallback on smaller viewports, if no other logo is set.",
        "de-DE": "Wird bei Ansichten \u00fcber 991px angezeigt und als Alternative bei kleineren Aufl\u00f6sungen, f\u00fcr die kein anderes Logo eingestellt ist."
      },
      "type": "media",
      "value": "18f45736ef6a4beea22d867573bd1af6",
      "editable": true,
      "block": "media",
      "section": null,
      "tab": null,
      "order": 100,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": true
    },
    "sw-logo-tablet": {
      "extensions": [],
      "name": "sw-logo-tablet",
      "label": {
        "en-GB": "Tablet",
        "de-DE": "Tablet"
      },
      "helpText": {
        "en-GB": "Displayed between a viewport of 767px to 991px",
        "de-DE": "Wird zwischen einem viewport von 767px bis 991px angezeigt"
      },
      "type": "media",
      "value": "18f45736ef6a4beea22d867573bd1af6",
      "editable": true,
      "block": "media",
      "section": null,
      "tab": null,
      "order": 200,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": true
    },
    "sw-logo-mobile": {
      "extensions": [],
      "name": "sw-logo-mobile",
      "label": {
        "en-GB": "Mobile",
        "de-DE": "Mobil"
      },
      "helpText": {
        "en-GB": "Displayed up to a viewport of 767px",
        "de-DE": "Wird bis zu einem Viewport von 767px angezeigt"
      },
      "type": "media",
      "value": "18f45736ef6a4beea22d867573bd1af6",
      "editable": true,
      "block": "media",
      "section": null,
      "tab": null,
      "order": 300,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": true
    },
    "sw-logo-share": {
      "extensions": [],
      "name": "sw-logo-share",
      "label": {
        "en-GB": "App & share icon",
        "de-DE": "App- & Share-Icon"
      },
      "helpText": null,
      "type": "media",
      "value": "",
      "editable": true,
      "block": "media",
      "section": null,
      "tab": null,
      "order": 400,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-logo-favicon": {
      "extensions": [],
      "name": "sw-logo-favicon",
      "label": {
        "en-GB": "Favicon",
        "de-DE": "Favicon"
      },
      "helpText": null,
      "type": "media",
      "value": "7bf586ac4343480292ebd5f349e16607",
      "editable": true,
      "block": "media",
      "section": null,
      "tab": null,
      "order": 500,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    }
  },
  "name": "Swag Dev Theme",
  "previewMedia": "custom\/apps\/SwagDevTheme\/Resources\/app\/storefront\/src\/assets\/images\/showroomPreview.png",
  "author": "Shopware AG",
  "isTheme": true,
  "styleFiles": [
    {
      "extensions": [],
      "filepath": "@Storefront",
      "resolveMapping": []
    }
  ],
  "scriptFiles": [
    {
      "extensions": [],
      "filepath": "@Storefront",
      "resolveMapping": []
    }
  ],
  "storefrontEntryFilepath": null,
  "basePath": "custom\/apps\/SwagDevTheme\/Resources",
  "assetPaths": [
    "custom\/apps\/SwagDevTheme\/Resources\/app\/storefront\/src\/assets"
  ],
  "viewInheritance": [
    "@Storefront",
    "@SwagCustomizedProducts",
    "@SwagPayPal",
    "@SwagAmazonPay",
    "@SwagCmsExtensions",
    "@SwagB2bPlatform",
    "@SwagDevTheme",
    "@Plugins"
  ],
  "iconSets": {
    "showroom": "app\/storefront\/src\/assets\/icon\/showroom"
  },
  "technicalName": "SwagDevTheme"
}
```

### Partially compiling the Storefront

You can also build just the Javascript bundle using `CI=1 SHOPWARE_SKIP_THEME_COMPILE=true PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true bin/build-storefront.sh` (without the need for the above loader) in your CI. After that, run `bin/console theme:dump` on your production system when the database is available. This will happen automatically if theme variables are changed via the admin panel.

---

---
url: /docs/v6.6/guides/hosting/installation-updates/deployments/build-w-o-db.md
---

# Building assets of Administration and Storefront without a Database

It is common to prebuild assets in professional deployments to deploy the build artifact assets to the production environment. This task is mostly done by a CI job that doesn't have access to the production database. Shopware needs access to the database to look up the installed extensions/load the configured theme variables. To be able to build the assets without a database, we can use static dumped files. All extensions need to be required by Composer to be able to be loaded by the `ComposerPluginLoader`.

::: warning
This guide requires Shopware 6.4.4.0 or higher.
:::

## Compiling the Administration without database

By default, Shopware builds the Administration without extensions if there is no database connection. To include the extensions without a database, you will need to use the `ComposerPluginLoader`. This determines the used plugins by looking up the installed project dependencies. To get this working, the plugin needs to be required in the system using `composer req [package/name]`.

There is a file `bin/ci` which uses the `ComposerPluginLoader` and can be used instead of `bin/console`.
Using this, you can dump the plugins for the Administration with the new file without a database using the command `bin/ci bundle:dump`. It is recommended to call `bin/ci` instead of `bin/console` in the `bin/*.js` scripts, which can be achieved by setting the environment variable `CI=1`.

## Compiling the Storefront without database

To compile the Storefront theme, you will need the theme variables from the database. To allow compiling it without a database, it is possible to dump the variables to the private file system of Shopware. This file system interacts with the local folder `files/theme-config` by default, but for it to be compiled, it should be shared such that settings are shared across deployments. This can be achieved, for example, by using a [storage adapter like s3](../../infrastructure/filesystem). The configuration can be dumped using the command `bin/console theme:dump`, or it happens automatically when changing theme settings or assigning a new theme.

This means that you still **need a dumped configuration from a system with a working database setup**. You then need to copy these files to your setup without a database and follow the steps below.

By default, Shopware still tries to load configurations from the database. In the next step, you will need to change the loader to `StaticFileConfigLoader`. To change that, you will need to create a new file, `config/packages/storefront.yaml` with the following content:

```yaml
storefront:
   theme:
       config_loader_id: Shopware\Storefront\Theme\ConfigLoader\StaticFileConfigLoader
       available_theme_provider: Shopware\Storefront\Theme\ConfigLoader\StaticFileAvailableThemeProvider
       theme_path_builder_id: Shopware\Storefront\Theme\MD5ThemePathBuilder
```

This will force the theme compiler to use the static dumped file instead of looking into the database.

::: info
Warnings about Database errors can still occur but will be caught and should be ignored in this case.
:::

The dumped files should be found in the directory `files/theme-config`

### Example

directory (files/theme-config):

```text
a729322c1f4e4b4e851137c807b4f363.json
index.json
```

index.json

```json
{"99ef1e95716d43d7be78e9d9921c7163":"a729322c1f4e4b4e851137c807b4f363"}
```

```json
{
  "extensions": [],
  "themeConfig": {
    "blocks": {
      "themeColors": {
        "label": {
          "en-GB": "Theme colours",
          "de-DE": "Theme-Farben"
        }
      },
      "typography": {
        "label": {
          "en-GB": "Typography",
          "de-DE": "Typografie"
        }
      },
      "eCommerce": {
        "label": {
          "en-GB": "E-Commerce",
          "de-DE": "E-Commerce"
        }
      },
      "statusColors": {
        "label": {
          "en-GB": "Status messages",
          "de-DE": "Status-Ausgaben"
        }
      },
      "media": {
        "label": {
          "en-GB": "Media",
          "de-DE": "Medien"
        }
      },
      "unordered": {
        "label": {
          "en-GB": "Misc",
          "de-DE": "Sonstige"
        }
      }
    },
    "fields": {
      "sw-color-brand-primary": {
        "label": {
          "en-GB": "Primary colour",
          "de-DE": "Prim\u00e4rfarbe"
        },
        "type": "color",
        "value": "#ff0000",
        "editable": true,
        "block": "themeColors",
        "order": 100
      },
      "sw-color-brand-secondary": {
        "label": {
          "en-GB": "Secondary colour",
          "de-DE": "Sekund\u00e4rfarbe"
        },
        "type": "color",
        "value": "#3d444d",
        "editable": true,
        "block": "themeColors",
        "order": 200
      },
      "sw-border-color": {
        "label": {
          "en-GB": "Border",
          "de-DE": "Rahmen"
        },
        "type": "color",
        "value": "#798490",
        "editable": true,
        "block": "themeColors",
        "order": 300
      },
      "sw-background-color": {
        "label": {
          "en-GB": "Background",
          "de-DE": "Hintergrund"
        },
        "type": "color",
        "value": "#fff",
        "editable": true,
        "block": "themeColors",
        "order": 400
      },
      "sw-color-success": {
        "label": {
          "en-GB": "Success",
          "de-DE": "Erfolg"
        },
        "type": "color",
        "value": "#3cc261",
        "editable": true,
        "block": "statusColors",
        "order": 100
      },
      "sw-color-info": {
        "label": {
          "en-GB": "Information",
          "de-DE": "Information"
        },
        "type": "color",
        "value": "#26b6cf",
        "editable": true,
        "block": "statusColors",
        "order": 200
      },
      "sw-color-warning": {
        "label": {
          "en-GB": "Notice",
          "de-DE": "Hinweis"
        },
        "type": "color",
        "value": "#ffbd5d",
        "editable": true,
        "block": "statusColors",
        "order": 300
      },
      "sw-color-danger": {
        "label": {
          "en-GB": "Error",
          "de-DE": "Fehler"
        },
        "type": "color",
        "value": "#e52427",
        "editable": true,
        "block": "statusColors",
        "order": 400
      },
      "sw-font-family-base": {
        "label": {
          "en-GB": "Fonttype text",
          "de-DE": "Schriftart Text"
        },
        "type": "fontFamily",
        "value": "'Inter', sans-serif",
        "editable": true,
        "block": "typography",
        "order": 100
      },
      "sw-text-color": {
        "label": {
          "en-GB": "Text colour",
          "de-DE": "Textfarbe"
        },
        "type": "color",
        "value": "#2b3136",
        "editable": true,
        "block": "typography",
        "order": 200
      },
      "sw-font-family-headline": {
        "label": {
          "en-GB": "Fonttype headline",
          "de-DE": "Schriftart \u00dcberschrift"
        },
        "type": "fontFamily",
        "value": "'Inter', sans-serif",
        "editable": true,
        "block": "typography",
        "order": 300
      },
      "sw-headline-color": {
        "label": {
          "en-GB": "Headline colour",
          "de-DE": "\u00dcberschriftfarbe"
        },
        "type": "color",
        "value": "#2b3136",
        "editable": true,
        "block": "typography",
        "order": 400
      },
      "sw-color-price": {
        "label": {
          "en-GB": "Price",
          "de-DE": "Preis"
        },
        "type": "color",
        "value": "#2b3136",
        "editable": true,
        "block": "eCommerce",
        "order": 100
      },
      "sw-color-buy-button": {
        "label": {
          "en-GB": "Buy button",
          "de-DE": "Kaufen-Button"
        },
        "type": "color",
        "value": "#0b539b",
        "editable": true,
        "block": "eCommerce",
        "order": 200
      },
      "sw-color-buy-button-text": {
        "label": {
          "en-GB": "Buy button text",
          "de-DE": "Kaufen-Button Text"
        },
        "type": "color",
        "value": "#fff",
        "editable": true,
        "block": "eCommerce",
        "order": 300
      },
      "sw-logo-desktop": {
        "label": {
          "en-GB": "Desktop",
          "de-DE": "Desktop"
        },
        "helpText": {
          "en-GB": "Displayed on viewport sizes above 991px and as a fallback on smaller viewports, if no other logo is set.",
          "de-DE": "Wird bei Ansichten \u00fcber 991px angezeigt und als Alternative bei kleineren Aufl\u00f6sungen, f\u00fcr die kein anderes Logo eingestellt ist."
        },
        "type": "media",
        "value": "http:\/\/shopware.local\/media\/64\/17\/g0\/1678462492\/demostore-logo.png",
        "editable": true,
        "block": "media",
        "order": 100,
        "fullWidth": true
      },
      "sw-logo-tablet": {
        "label": {
          "en-GB": "Tablet",
          "de-DE": "Tablet"
        },
        "helpText": {
          "en-GB": "Displayed between a viewport of 767px to 991px",
          "de-DE": "Wird zwischen einem viewport von 767px bis 991px angezeigt"
        },
        "type": "media",
        "value": "http:\/\/shopware.local\/media\/64\/17\/g0\/1678462492\/demostore-logo.png",
        "editable": true,
        "block": "media",
        "order": 200,
        "fullWidth": true
      },
      "sw-logo-mobile": {
        "label": {
          "en-GB": "Mobile",
          "de-DE": "Mobil"
        },
        "helpText": {
          "en-GB": "Displayed up to a viewport of 767px",
          "de-DE": "Wird bis zu einem Viewport von 767px angezeigt"
        },
        "type": "media",
        "value": "http:\/\/shopware.local\/media\/64\/17\/g0\/1678462492\/demostore-logo.png",
        "editable": true,
        "block": "media",
        "order": 300,
        "fullWidth": true
      },
      "sw-logo-share": {
        "label": {
          "en-GB": "App & share icon",
          "de-DE": "App- & Share-Icon"
        },
        "type": "media",
        "value": "",
        "editable": true,
        "block": "media",
        "order": 400
      },
      "sw-logo-favicon": {
        "label": {
          "en-GB": "Favicon",
          "de-DE": "Favicon"
        },
        "type": "media",
        "value": "http:\/\/shopware.local\/media\/d3\/f5\/b7\/1678462492\/favicon.png",
        "editable": true,
        "block": "media",
        "order": 500
      }
    },
    "sw-color-brand-primary": {
      "extensions": [],
      "name": "sw-color-brand-primary",
      "label": {
        "en-GB": "Primary colour",
        "de-DE": "Prim\u00e4rfarbe"
      },
      "helpText": null,
      "type": "color",
      "value": "#0b539b",
      "editable": true,
      "block": "themeColors",
      "section": null,
      "tab": null,
      "order": 100,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-brand-secondary": {
      "extensions": [],
      "name": "sw-color-brand-secondary",
      "label": {
        "en-GB": "Secondary colour",
        "de-DE": "Sekund\u00e4rfarbe"
      },
      "helpText": null,
      "type": "color",
      "value": "#3d444d",
      "editable": true,
      "block": "themeColors",
      "section": null,
      "tab": null,
      "order": 200,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-border-color": {
      "extensions": [],
      "name": "sw-border-color",
      "label": {
        "en-GB": "Border",
        "de-DE": "Rahmen"
      },
      "helpText": null,
      "type": "color",
      "value": "#798490",
      "editable": true,
      "block": "themeColors",
      "section": null,
      "tab": null,
      "order": 300,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-background-color": {
      "extensions": [],
      "name": "sw-background-color",
      "label": {
        "en-GB": "Background",
        "de-DE": "Hintergrund"
      },
      "helpText": null,
      "type": "color",
      "value": "#fff",
      "editable": true,
      "block": "themeColors",
      "section": null,
      "tab": null,
      "order": 400,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-success": {
      "extensions": [],
      "name": "sw-color-success",
      "label": {
        "en-GB": "Success",
        "de-DE": "Erfolg"
      },
      "helpText": null,
      "type": "color",
      "value": "#3cc261",
      "editable": true,
      "block": "statusColors",
      "section": null,
      "tab": null,
      "order": 100,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-info": {
      "extensions": [],
      "name": "sw-color-info",
      "label": {
        "en-GB": "Information",
        "de-DE": "Information"
      },
      "helpText": null,
      "type": "color",
      "value": "#26b6cf",
      "editable": true,
      "block": "statusColors",
      "section": null,
      "tab": null,
      "order": 200,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-warning": {
      "extensions": [],
      "name": "sw-color-warning",
      "label": {
        "en-GB": "Notice",
        "de-DE": "Hinweis"
      },
      "helpText": null,
      "type": "color",
      "value": "#ffbd5d",
      "editable": true,
      "block": "statusColors",
      "section": null,
      "tab": null,
      "order": 300,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-danger": {
      "extensions": [],
      "name": "sw-color-danger",
      "label": {
        "en-GB": "Error",
        "de-DE": "Fehler"
      },
      "helpText": null,
      "type": "color",
      "value": "#e52427",
      "editable": true,
      "block": "statusColors",
      "section": null,
      "tab": null,
      "order": 400,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-font-family-base": {
      "extensions": [],
      "name": "sw-font-family-base",
      "label": {
        "en-GB": "Fonttype text",
        "de-DE": "Schriftart Text"
      },
      "helpText": null,
      "type": "fontFamily",
      "value": "'Inter', sans-serif",
      "editable": true,
      "block": "typography",
      "section": null,
      "tab": null,
      "order": 100,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-text-color": {
      "extensions": [],
      "name": "sw-text-color",
      "label": {
        "en-GB": "Text colour",
        "de-DE": "Textfarbe"
      },
      "helpText": null,
      "type": "color",
      "value": "#2b3136",
      "editable": true,
      "block": "typography",
      "section": null,
      "tab": null,
      "order": 200,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-font-family-headline": {
      "extensions": [],
      "name": "sw-font-family-headline",
      "label": {
        "en-GB": "Fonttype headline",
        "de-DE": "Schriftart \u00dcberschrift"
      },
      "helpText": null,
      "type": "fontFamily",
      "value": "'Inter', sans-serif",
      "editable": true,
      "block": "typography",
      "section": null,
      "tab": null,
      "order": 300,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-headline-color": {
      "extensions": [],
      "name": "sw-headline-color",
      "label": {
        "en-GB": "Headline colour",
        "de-DE": "\u00dcberschriftfarbe"
      },
      "helpText": null,
      "type": "color",
      "value": "#2b3136",
      "editable": true,
      "block": "typography",
      "section": null,
      "tab": null,
      "order": 400,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-price": {
      "extensions": [],
      "name": "sw-color-price",
      "label": {
        "en-GB": "Price",
        "de-DE": "Preis"
      },
      "helpText": null,
      "type": "color",
      "value": "#2b3136",
      "editable": true,
      "block": "eCommerce",
      "section": null,
      "tab": null,
      "order": 100,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-buy-button": {
      "extensions": [],
      "name": "sw-color-buy-button",
      "label": {
        "en-GB": "Buy button",
        "de-DE": "Kaufen-Button"
      },
      "helpText": null,
      "type": "color",
      "value": "#0b539b",
      "editable": true,
      "block": "eCommerce",
      "section": null,
      "tab": null,
      "order": 200,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-color-buy-button-text": {
      "extensions": [],
      "name": "sw-color-buy-button-text",
      "label": {
        "en-GB": "Buy button text",
        "de-DE": "Kaufen-Button Text"
      },
      "helpText": null,
      "type": "color",
      "value": "#fff",
      "editable": true,
      "block": "eCommerce",
      "section": null,
      "tab": null,
      "order": 300,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-logo-desktop": {
      "extensions": [],
      "name": "sw-logo-desktop",
      "label": {
        "en-GB": "Desktop",
        "de-DE": "Desktop"
      },
      "helpText": {
        "en-GB": "Displayed on viewport sizes above 991px and as a fallback on smaller viewports, if no other logo is set.",
        "de-DE": "Wird bei Ansichten \u00fcber 991px angezeigt und als Alternative bei kleineren Aufl\u00f6sungen, f\u00fcr die kein anderes Logo eingestellt ist."
      },
      "type": "media",
      "value": "18f45736ef6a4beea22d867573bd1af6",
      "editable": true,
      "block": "media",
      "section": null,
      "tab": null,
      "order": 100,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": true
    },
    "sw-logo-tablet": {
      "extensions": [],
      "name": "sw-logo-tablet",
      "label": {
        "en-GB": "Tablet",
        "de-DE": "Tablet"
      },
      "helpText": {
        "en-GB": "Displayed between a viewport of 767px to 991px",
        "de-DE": "Wird zwischen einem viewport von 767px bis 991px angezeigt"
      },
      "type": "media",
      "value": "18f45736ef6a4beea22d867573bd1af6",
      "editable": true,
      "block": "media",
      "section": null,
      "tab": null,
      "order": 200,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": true
    },
    "sw-logo-mobile": {
      "extensions": [],
      "name": "sw-logo-mobile",
      "label": {
        "en-GB": "Mobile",
        "de-DE": "Mobil"
      },
      "helpText": {
        "en-GB": "Displayed up to a viewport of 767px",
        "de-DE": "Wird bis zu einem Viewport von 767px angezeigt"
      },
      "type": "media",
      "value": "18f45736ef6a4beea22d867573bd1af6",
      "editable": true,
      "block": "media",
      "section": null,
      "tab": null,
      "order": 300,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": true
    },
    "sw-logo-share": {
      "extensions": [],
      "name": "sw-logo-share",
      "label": {
        "en-GB": "App & share icon",
        "de-DE": "App- & Share-Icon"
      },
      "helpText": null,
      "type": "media",
      "value": "",
      "editable": true,
      "block": "media",
      "section": null,
      "tab": null,
      "order": 400,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    },
    "sw-logo-favicon": {
      "extensions": [],
      "name": "sw-logo-favicon",
      "label": {
        "en-GB": "Favicon",
        "de-DE": "Favicon"
      },
      "helpText": null,
      "type": "media",
      "value": "7bf586ac4343480292ebd5f349e16607",
      "editable": true,
      "block": "media",
      "section": null,
      "tab": null,
      "order": 500,
      "sectionOrder": null,
      "blockOrder": null,
      "tabOrder": null,
      "custom": null,
      "scss": null,
      "fullWidth": null
    }
  },
  "name": "Swag Dev Theme",
  "previewMedia": "custom\/apps\/SwagDevTheme\/Resources\/app\/storefront\/src\/assets\/images\/showroomPreview.png",
  "author": "Shopware AG",
  "isTheme": true,
  "styleFiles": [
    {
      "extensions": [],
      "filepath": "@Storefront",
      "resolveMapping": []
    }
  ],
  "scriptFiles": [
    {
      "extensions": [],
      "filepath": "@Storefront",
      "resolveMapping": []
    }
  ],
  "storefrontEntryFilepath": null,
  "basePath": "custom\/apps\/SwagDevTheme\/Resources",
  "assetPaths": [
    "custom\/apps\/SwagDevTheme\/Resources\/app\/storefront\/src\/assets"
  ],
  "viewInheritance": [
    "@Storefront",
    "@SwagCustomizedProducts",
    "@SwagPayPal",
    "@SwagAmazonPay",
    "@SwagCmsExtensions",
    "@SwagB2bPlatform",
    "@SwagDevTheme",
    "@Plugins"
  ],
  "iconSets": {
    "showroom": "app\/storefront\/src\/assets\/icon\/showroom"
  },
  "technicalName": "SwagDevTheme"
}
```

### Partially compiling the Storefront

You can also build just the Javascript bundle using `CI=1 SHOPWARE_SKIP_THEME_COMPILE=true PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true bin/build-storefront.sh` (without the need for the above loader) in your CI. After that, run `bin/console theme:dump` on your production system when the database is available. This will happen automatically if theme variables are changed via the admin panel.

---

---
url: /docs/v6.6/products/cli/extension-commands/build.md
---

# Building extensions and creating archives

Extensions consist of PHP Changes, JavaScript and CSS. To release an extension to the Shopware Store or upload it to a Shopware 6 instance without having to rebuild Storefront and Administration, your extension needs to provide the compiled assets.

## Building an extension

Shopware CLI allows you to easily build the assets of an extension. To build an extension, you can use the following command:

```bash
shopware-cli extension build <path>
```

Shopware CLI reads the `shopware/core` requirement from `composer.json` or `manifest.xml` and builds the assets using the lowest compatible Shopware version. This ensures the extension remains usable across multiple Shopware versions. If the selected version is incorrect, you can override it using a `.shopware-extension.yml` file.

```yaml
# .shopware-extension.yml
build:
  shopwareVersionConstraint: '6.6.9.0'
```

This only affects the build process and not on the installation of the extension. For full control you can also specify the environment variable `SHOPWARE_PROJECT_ROOT` pointing to a Shopware 6 project, and it will use that Shopware to build the extension assets.

## Additional bundles

If your plugin consists of multiple bundles, usually when you have implemented `getAdditionalBundles` in your `Plugin` class, you have to provide the path to the bundle you want to build in the config:

```yaml
# .shopware-extension.yml
build:
  extraBundles:
    # Assumes the bundle name is the same as the directory name
    - path: src/Foo
    # Explicitly specify the bundle name
    - path: src/Foo
      name: Foo
```

## Extension as bundle

If your extension is not a plugin but itself a bundle, make sure your composer type is `shopware-bundle` and that you have set a `shopware-bundle-name` in the `extra` part of the composer definition like this:

```json
{
    "name": "my-vendor/my-bundle",
    "type": "shopware-bundle",
    "extra": {
        "shopware-bundle-name": "MyBundle"
    }
}
```

Now you can use `shopware-cli extension build <path>` to build the assets and distribute them together with your bundle.
Also `shopware-cli project ci` detects know automatically this bundle and builds the assets for it.

## Using esbuild for JavaScript Bundling

::: warning
Building with esbuild works completely standalone without the Shopware codebase. This means if you import files from Shopware, you have to copy it to your extension.
:::

Esbuild can be used for JavaScript bundling, offering a significantly faster alternative to the standard Shopware bundling process, as it eliminates the need to involve Shopware for asset building.

```yaml
# .shopware-extension.yml
build:
  zip:
    assets:
      # Use esbuild for Administration
      enable_es_build_for_admin: true
      # Use esbuild for Storefront
      enable_es_build_for_storefront: true
```

## Creating an archive

To create an archive of an extension, you can use the following command:

```bash
shopware-cli extension zip <path>
```

The command copies the extension to a temporary directory, builds the assets, deletes unnecessary files and creates a zip archive of the extension. The archive is placed in the current working directory.

**By default, the command picks the latest released git tag**, use the `--disable-git` flag to disable this behavior and use the current source code. Besides disabling it completely, you can also specify a specific tag or commit using `--git-commit`.

### Bundling composer dependencies

Before Shopware 6.5, bundling the composer dependencies into the zip file is required. Shopware CLI automatically runs `composer install` and removes duplicate composer dependencies to avoid conflicts.

To disable this behavior, you can adjust the configuration:

```yaml
# .shopware-extension.yml
build:
  zip:
    composer:
      enabled: false
```

This is automatically disabled for plugins targeting Shopware 6.5 and above and `executeComposerCommands` should be used instead.

### Delete files before zipping

Shopware CLI deletes a lot of known files before zipping the extension. If you want to delete more files, you can adjust the configuration:

```yaml
# .shopware-extension.yml
build:
  zip:
    pack:
      excludes:
        paths:
          - <path>
```

### JavaScript Build optimization

If you bring additional NPM packages, make sure that you added only runtime dependencies to `dependencies` inside `package.json` and tooling to `devDependencies` and enabled `npm_strict` in the configuration:

```yaml
# .shopware-extension.yml
build:
  zip:
    assets:
      npm_strict: true
```

This skips unnecessary `npm install` and `npm ci` commands and only installs the runtime dependencies.

### Release mode

If you are building an archive for distribution, you can enable the release mode with the flag `--release`. This will remove the App secret from the `manifest.xml` and generate changelog files if enabled.

The changelog generation can be enabled with the configuration:

```yaml
# .shopware-extension.yml
changelog:
  enabled: true
```

It generates the changelog by utilizing the commits between the last tag and the current commit. Additionally, it can be configured to filter commits and build the changelog differently.

```yaml
changelog:
  enabled: true
  # only the commits matching to this regex will be used
  pattern: '^NEXT-\d+'
  # variables allow extracting metadata out of the commit message
  variables:
    ticket: '^(NEXT-\d+)\s'
  # go template for the changelog, it loops over all commits
  template: |
    {{range .Commits}}- [{{ .Message }}](https://issues.shopware.com/issues/{{ .Variables.ticket }})
    {{end}}
```

This example checks that all commits in the changelog needs to start with `NEXT-` in the beginning. The `variables` section allows extracting metadata out of the commit message. The `template` is a go template which loops over all commits and generates the changelog.
With the combination of `pattern`, `variables` and `template` we link the commit message to the Shopware ticket system.

### Overwrites

Extension configuration can be overwritten during the zipping process, allowing changes to aspects such as the version and app-related settings.

Replaces the version in `composer.json` or `manifest.xml` with the given version:

```yaml
shopware-cli extension zip --overwrite-version=1.0.0 <path>
```

Replaces all external URLs in `manifest.xml` to that given URL:

```yaml
shopware-cli extension zip --overwrite-app-backend-url=https://example.com <path>
```

Replaces the App secret in `manifest.xml` with the given secret:

```yaml
shopware-cli extension zip --overwrite-app-backend-secret=MySecret <path>
```

---

---
url: /docs/products/tools/cli/extension-commands/build.md
---

# Building Extensions and Creating Archives

Extensions consist of PHP Changes, JavaScript, and CSS. To release an extension to the Shopware Store or upload it to a Shopware 6 instance without having to rebuild Storefront and Administration, your extension needs to provide the compiled assets.

## Building an extension

Shopware CLI allows you to easily build the assets of an extension. To build an extension, you can use the following command:

```bash
shopware-cli extension build <path>
```

Shopware CLI reads the `shopware/core` requirement from `composer.json` or `manifest.xml` and builds the assets using the lowest compatible Shopware version. This ensures the extension remains usable across multiple Shopware versions. If the selected version is incorrect, you can override it using a `.shopware-extension.yml` file.

```yaml
# .shopware-extension.yml
build:
  shopwareVersionConstraint: '6.6.9.0'
```

This only affects the build process and not on the installation of the extension. For full control you can also specify the environment variable `SHOPWARE_PROJECT_ROOT` pointing to a Shopware 6 project, and it will use that Shopware to build the extension assets.

## Additional bundles

If your plugin consists of multiple bundles, usually when you have implemented `getAdditionalBundles` in your `Plugin` class, you have to provide the path to the bundle you want to build in the config:

```yaml
# .shopware-extension.yml
build:
  extraBundles:
    # Assumes the bundle name is the same as the directory name
    - path: src/Foo
    # Explicitly specify the bundle name
    - path: src/Foo
      name: Foo
```

## Extension as bundle

If your extension is not a plugin but itself a bundle, make sure your Composer type is `shopware-bundle` and that you have set a `shopware-bundle-name` in the `extra` part of the composer definition like this:

```json
{
    "name": "my-vendor/my-bundle",
    "type": "shopware-bundle",
    "extra": {
        "shopware-bundle-name": "MyBundle"
    }
}
```

Now you can use `shopware-cli extension build <path>` to build the assets and distribute them together with your bundle.
Also `shopware-cli project ci` detects know automatically this bundle and builds the assets for it.

## Using esbuild for JavaScript bundling

::: warning
Building with esbuild works completely standalone without the Shopware codebase. This means if you import files from Shopware, you have to copy it to your extension.
:::

An esbuild bundle can be used for JavaScript bundling, offering a significantly faster alternative to the standard Shopware bundling process, as it eliminates the need to involve Shopware for asset building.

```yaml
# .shopware-extension.yml
build:
  zip:
    assets:
      # Use esbuild for Administration
      enable_es_build_for_admin: true
      # Use esbuild for Storefront
      enable_es_build_for_storefront: true
```

### Content-addressable assets and Vite manifest

When building with esbuild, Shopware CLI emits content-hashed variants of the
compiled JS and CSS files (e.g. `<name>-<hash>.js`) alongside files without hashes in the same directories.

* **Shopware 6.7+**: The generated `.vite/manifest.json` and `.vite/entrypoints.json` reference the hashed filenames, so browser and CDN caches are invalidated automatically whenever the extension assets change. Note that an existing `.vite/manifest.json` is overwritten on each esbuild build.
* **Shopware < 6.7**: The files without hashes are kept for backward compatibility and continue to be loaded as before.

No configuration is required. This happens automatically when esbuild is enabled.

## Creating an archive

To create an archive of an extension, you can use the following command:

```bash
shopware-cli extension package <path>
```

The command copies the extension to a temporary directory, builds the assets, deletes unnecessary files and creates a ZIP archive of the extension. The archive is placed in the current working directory.

**By default, the command picks the latest released git tag**, use the `--disable-git` flag to disable this behavior and use the current source code. Besides disabling it completely, you can also specify a specific tag or commit using `--git-commit`.

### Bundling Composer dependencies

Before Shopware 6.5, bundling the Composer dependencies into the ZIP file is required. Shopware CLI automatically runs `composer install` and removes duplicate Composer dependencies to avoid conflicts.

To disable this behavior, you can adjust the configuration:

```yaml
# .shopware-extension.yml
build:
  zip:
    composer:
      enabled: false
```

This is automatically disabled for plugins targeting Shopware 6.5 and above and `executeComposerCommands` should be used instead.

### Delete files before packaging

Shopware CLI deletes a lot of known files before packaging the extension into a ZIP file. If you want to delete more files, you can adjust the configuration:

```yaml
# .shopware-extension.yml
build:
  zip:
    pack:
      excludes:
        paths:
          - <path>
```

### JavaScript build optimization

If you bring additional NPM packages, make sure that you added only runtime dependencies to `dependencies` inside `package.json` and tooling to `devDependencies` and enabled `npm_strict` in the configuration:

```yaml
# .shopware-extension.yml
build:
  zip:
    assets:
      npm_strict: true
```

This skips unnecessary `npm install` and `npm ci` commands and only installs the runtime dependencies.

### Checksums

When creating an archive using `shopware-cli extension package`, a `checksum.json` file is automatically generated. This file contains checksums for all files in the extension, which can be used to verify the integrity of the extension after installation.

If you want to exclude certain files or paths from the checksum calculation, you can configure this in your `.shopware-extension.yml` file:

```yaml
# .shopware-extension.yml
build:
  zip:
    checksum:
      ignore:
        - <path>
        - <another_path>
```

For example, to exclude the `src/Resources/config/services.php` file from checksum calculation:

```yaml
# .shopware-extension.yml
build:
  zip:
    checksum:
      ignore:
        - src/Resources/config/services.php
```

To verify the checksum of installed extensions, you can use the [FroshTools](https://github.com/FriendsOfShopware/FroshTools#froshextensionchecksumcheck---check-extension-file-integrity) plugin which provides a checksum verification feature for all extensions.

### Release mode

When building an extension for distribution to the Shopware Store or installation in a Shopware instance, enable release mode with the `--release` flag:

```bash
shopware-cli extension package <path> --release
```

Release mode:

* Removes secrets: Strips out sensitive data that may have been committed during development (credentials, API keys, app secrets)
* Generates changelog: Automatically creates changelog files from Git commits (if enabled in configuration)

This is important when distributing extensions because developers often commit configuration files with secrets during development that shouldn't be included in the final package.

The changelog generation can be enabled with the configuration:

```yaml
# .shopware-extension.yml
changelog:
  enabled: true
```

It generates the changelog by utilizing the commits between the last tag and the current commit. Additionally, it can be configured to filter commits and build the changelog differently.

```yaml
changelog:
  enabled: true
  # only the commits matching to this regex will be used
  pattern: '^NEXT-\d+'
  # variables allow extracting metadata out of the commit message
  variables:
    ticket: '^(NEXT-\d+)\s'
  # go template for the changelog, it loops over all commits
  template: |
    {{range .Commits}}- [{{ .Message }}](https://issues.shopware.com/issues/{{ .Variables.ticket }})
    {{end}}
```

This example checks that all commits in the changelog needs to start with `NEXT-` in the beginning. The `variables` section allows extracting metadata out of the commit message. The `template` is a go template which loops over all commits and generates the changelog.
With the combination of `pattern`, `variables` and `template` we link the commit message to the Shopware ticket system.

### Overwrites

Extension configuration can be overwritten during the packaging process, allowing changes to aspects such as the version and app-related settings.

Replaces the version in `composer.json` or `manifest.xml` with the given version:

```yaml
shopware-cli extension package --overwrite-version=1.0.0 <path>
```

Replaces all external URLs in `manifest.xml` to that given URL:

```yaml
shopware-cli extension package --overwrite-app-backend-url=https://example.com <path>
```

Replaces the App secret in `manifest.xml` with the given secret:

```yaml
shopware-cli extension package --overwrite-app-backend-secret=MySecret <path>
```

---

---
url: /docs/concepts/framework/translations/built-in-translation-system.md
---

# Built-in Translation Handling

## Overview

The built-in translation system allows you to install and update translations that are not shipped with Shopware by
default.
It provides the same set of translations as the **Language Pack** plugin and is planned to fully replace it.

> **Note:** The Language Pack plugin is deprecated and will be removed with Shopware version **6.8.0.0**.
> If you are currently using the Language Pack plugin, please refer to
> the [Migration guide](../../../guides/upgrades-migrations/language-pack-migration.md) for instructions
> on switching to the new system.

## Where do the translations come from?

Translations are fetched from a public GitHub
repository: [shopware/translations](https://github.com/shopware/translations).
This repository is managed using [Crowdin](https://crowdin.com/project/shopware6) and contains translations for Shopware
as well as for some official plugins. The repository syncs with Crowdin every day to ensure that the latest translations
are always available.

## How to install and update translations?

To use the built-in translation system, you can use the following console commands:

### Install translations

The `translation:install` command is used to download and install translations for Shopware and its plugins from the
configured GitHub repository. It allows you to specify which locales to install, whether to install all available
locales, and whether to skip activation of the installed translations.
Re-installing an already installed locale will override its translations.

```bash
$ php bin/console translation:install [--all, --locales, --skip-activation]

# example
$ php bin/console translation:install --locales=fr-FR,pl-PL --skip-activation
```

### Update command

The `translation:update` command is used to update existing translations for Shopware and its plugins from the
configured GitHub repository.

```bash
$ php bin/console translation:update
```

## Language activation

By default, installed translations are automatically activated, making them available for use in Shopware.
If you want to install translations without activating them, you can use the `--skip-activation` option with the
`translation:install` command.
The `active` flag in the `language` table indicates whether a language is active or not. If a language is not active, it
will not be available for selection in the storefront.

## How does the system recognize new updates?

The `translations` repository
includes [metadata](https://github.com/shopware/translations/blob/main/crowdin-metadata.json)
that provides information about the translations, such as available locales, last update timestamps, and completion
percentages for each language. The `updatedAt` field in the metadata is used to determine if a translation needs to be
updated. Installing or updating translations will create or update a `crowdin-metadata.lock` file on your private
filesystem which stores the last known update timestamps for each locale.
This file is used to compare the last update timestamps of installed locales with the ones in the metadata file to
determine if an update is necessary.

## Loading priority

When loading translations, the system follows a defined priority order to resolve conflicts:

1. Database translations – These have the highest priority. You can define them to override all other translations.
2. Country-specific translations (e.g. `en-GB`, `en-US` or `de-DE`) – These can be provided for country-dependent
   translations or dialects as small patch files. For more information about the language-layer changes, you can have a
   look at its documentation.
3. Country-agnostic translations (`en` and `de`) – These are shipped with Shopware and its plugins. They ensure that the
   system always has a reliable fallback language and provide a consistent developer experience without requiring you to wait until your translations are accepted at [translate.shopware.com](https://crowdin.com/project/shopware6). For more details on selecting a fallback language and structuring your snippet files, see the [Fallback Languages guide](fallback-language-selection.md).
4. Built-in translation system – Finally, the translations installed via the built-in translation system are applied.

## Built-in translation system and Flysystem

The built-in translation system relies on Flysystem for storage abstraction. This allows great flexibility when working
with translations, as Flysystem supports multiple storage backends. For example, external systems can configure the
translation storage to use:

* Local file system (default)
* Cloud storage services such as Amazon S3, Google Cloud Storage, or Azure Blob Storage
* Custom storage adapters that integrate with other systems

This means you can adapt translation storage to your infrastructure needs, whether you want to keep everything local or
centralize it in a cloud-based storage solution.

## Translation configuration

This configuration file is in YAML format and defines how translations for Shopware core and plugins are managed and
retrieved.
It specifies the repository sources, supported plugins and languages, and more.
You can find the configuration file at `src/Core/System/Resources/translation.yaml`.

### Fields

#### `repository-url`

**Type:** `string`
**Example:**

```yaml
repository-url: https://raw.githubusercontent.com/shopware/translations/main/translations
```

**Description:**
The base URL of the translation repository. Translation files for different languages and plugins are fetched from here.

***

#### `metadata-url`

**Type:** `string`
**Example:**

```yaml
metadata-url: https://raw.githubusercontent.com/shopware/translations/main/crowdin-metadata.json
```

**Description:**
The URL for [metadata information](#how-does-the-system-recognize-new-updates) about the translations.

***

#### `plugins`

**Type:** `array[string]`
**Example:**

```yaml
plugins: [
  'PluginPublisher',
  'SwagB2bPlatform',
  'SwagCmsExtensions'
]
```

**Description:**
A list of supported plugins for which translations are available.

***

#### `excluded-locales`

**Type:** `array[string]`
**Example:**

```yaml
excluded-locales: [ 'de-DE', 'en-GB' ]
```

**Description:**
A list of language locales to be excluded from translation processing. German (Germany) and English (UK) are excluded by
default since they are shipped with Shopware. The exclusion applies to plugins too.

***

#### `plugin-mapping`

**Type:** `array[object]`
**Example:**

```yaml
plugin-mapping:
  - plugin: 'SwagPublisher'
    name: 'PluginPublisher'
```

**Fields:**

* `plugin` (`string`): The internal plugin identifier (e.g., directory or code name).
* `name` (`string`): The corresponding plugin name in the translation repository.

**Description:**
Allows mapping between internal plugin identifiers and repository names in case they differ.

***

#### `languages`

**Type:** `array[object]`
**Example:**

```yaml
languages:
  - name: 'Français'
    locale: 'fr-FR'
```

**Fields:**

* `name` (`string`): Human-readable language name (preferably in the native script).
* `locale` (`string`): Language code according to [IETF BCP 47](https://www.rfc-editor.org/info/bcp47), restricted to [ISO 639-1 (2-letter) language codes](https://en.wikipedia.org/wiki/ISO_639-1), used by
  Shopware for translations.

**Description:**
Defines the set of supported languages for which translations should be retrieved. Each entry specifies a display name
and a locale code.

***

## How to extend or modify the configuration handling

### Configuration override

You can change the configuration from a standard Symfony configuration file in `config/packages` through the
`shopware.translation` section, without touching `translation.yaml` or writing any PHP:

```yaml
# config/packages/translation.yaml
shopware:
    translation:
        repository_url: 'https://raw.githubusercontent.com/my-org/translations/main/translations'
        plugins:
            - 'MyCustomPlugin'
```

Any option left unset falls back to the shipped default. The list options (`plugins`, `excluded_locales`,
`plugin_mapping`, `languages`) replace the shipped default instead of merging into it, so provide the full list, or an
empty list (`[]`) to clear it. Configuration keys use `snake_case`, whereas the shipped `translation.yaml` uses the
dash-separated keys documented above. Both describe the same fields.

### TranslationConfigLoader

If you need behavior that configuration cannot express, for example values computed at runtime, you can decorate the
loader. The `TranslationConfigLoader` (`src/Core/System/Snippet/Service/TranslationConfigLoader.php`) is part of the
Shopware core and is responsible for loading and validating the `translation.yaml` file. It provides a
`TranslationConfig` object that contains all configured fields, ensures that URLs are valid, languages and plugins are
properly structured, and plugin mappings are resolved. Errors such as missing files or invalid configuration values are
raised as `SnippetException`.

To change its behavior, services should depend on the abstract class `AbstractTranslationConfigLoader`, and custom
decorators can override methods like `load()` while delegating to the original loader. The concrete
`TranslationConfigLoader` is `@internal`, so decorate the `AbstractTranslationConfigLoader` service ID, not the concrete
class.

For the complete list of extension points across the translation system, see the
[Extension points](extension-points.md) page.

### TranslationConfig

The `TranslationConfig` (`src/Core/System/Snippet/Service/TranslationConfig.php`) is a data structure that holds the
configuration details loaded from the `translation.yaml` file.
You can require it via dependency injection and because of the usage of the `TranslationConfigLoader` with lazy loading,
the configuration is always available when needed.

More information is available in the [Migration Guide](../../../guides/upgrades-migrations/language-pack-migration.md).

---

---
url: /docs/v6.6/guides/plugins/plugins/bundle.md
---

# Bundle

Plugins are based on the Symfony bundle concept, but offer additional features like lifecycle events and the ability to be managed in the Shopware administration.
This is maybe unwanted in some cases, like project critical customizations which should not be managed via the Shopware administration.
In this case, you can use a Symfony bundle instead of a plugin.

## Project Structure

Here's how a typical Shopware 6 project structure looks like when using bundles:

```text
project-root/
├── bin/
│   └── console
├── config/
│   ├── bundles.php
│   ├── packages/
│   └── services.yaml
├── public/
│   ├── index.php
│   └── bundles/
├── src/
│   └── YourBundleName/
│       ├── YourBundleName.php
│       ├── Migration/
│       │   └── Migration1234567890YourMigration.php
│       └── Resources/
│           ├── config/
│           │   ├── services.xml
│           │   └── routes.xml
│           ├── views/
│           │   └── storefront/
│           │       └── page/
│           └── app/
│               ├── storefront/
│               │   └── src/
│               └── administration/
│                   └── src/
├── var/
├── vendor/
├── composer.json
├── composer.lock
└── .shopware-project.yaml
```

The Bundle is typically placed in the `src/` folder of your project, which is the standard location for custom code in a Shopware project. You still will need to register the bundle in the `config/bundles.php` file of your project.

## Choosing the right Bundle class

There are two Bundle classes you can choose from:

* `Shopware\Core\Framework\Bundle`
* `Symfony\Component\HttpKernel\Bundle\Bundle`

The first one is the Shopware bundle class and the second one is the Symfony bundle class.
The Shopware bundle class extends the Symfony bundle class, but offers additional features like acting as theme, bringing JavaScript/CSS files, Migrations, etc.
If you don't need these features, you can use the Symfony bundle class instead.

## Creating a Bundle

By default, The namespace `App\` is registered to the `src` folder in any Shopware project to be used for customizations. We recommend using this namespace, if you like to change the project structure, you can change the `App\` namespace in the `composer.json` file of your project.

```php
// <project root>/src/YourBundleName.php
<?php declare(strict_types=1);

namespace App\YourBundleName;

use Shopware\Core\Framework\Bundle;

class YourBundleName extends Bundle
{
}
```

The bundle class needs to be registered in the `config/bundles.php` file of your project.

```php
// <project root>/config/bundles.php
//...
App\YourBundleName\YourBundleName::class => ['all' => true],
//...
```

## Adding services, twig templates, routes, theme, etc

You can add services, twig templates, routes, etc. to your bundle like you would do in a plugin.
Just create `Resources/config/services.xml` and `Resources/config/routes.xml` files or `Resources/views` for twig templates.
The bundle will be automatically detected and the files will be loaded.

To mark your bundle as a theme, it's enough to implement the `Shopware\Core\Framework\ThemeInterface` interface in your bundle class.
This will automatically register your bundle as a theme and make it available in the Shopware administration.
You can also add a `theme.json` file to define the theme configuration like [described here](../themes/theme-configuration.md).

## Adding migrations

Migrations are not automatically detected in bundles.
To enable migrations, you need to overwrite the `build` method in your bundle class like this:

```php
// <project root>/src/YourBundleName.php
<?php declare(strict_types=1);

namespace App\YourBundleName;

use Shopware\Core\Framework\Bundle;

class YourBundleName extends Bundle
{
    public function build(ContainerBuilder $container): void
    {
        parent::build($container);

        $this->registerMigrationPath($container);
    }
}
```

As Bundles don't have a lifecycle, the migrations are not automatically executed.
You need to execute them manually via the console command:

```bash
bin/console database:migrate <BundleName> --all
```

If you use [Deployment Helper](../../hosting/installation-updates/deployments/deployment-helper.md), you can add it to the `.shopware-project.yaml` file like this:

```yaml
deployment:
    hooks:
        pre-update: |
            bin/console database:migrate <BundleName> --all
```

## Integration into Shopware-CLI

Shopware-CLI cannot detect bundles automatically, therefore the assets of the bundles are not built automatically.
You will need to adjust the `composer.json` file of your project to specify the path to the bundle.
This is done by adding the `extra` section to the `composer.json` file:

```json
{
    "extra": {
        "shopware-bundles": {
          "src/<BundleName>": {
            "name": "<BundleName>",
          }
        }
    }
}
```

This will tell Shopware-CLI where the bundle is located and what the name of the bundle is.

---

---
url: /docs/products/nexus/integration.md
---

# Business Central Integration

The Business Central integration allows workflows to perform CRUD operations on supported entities via the Business Central API.

## Supported Entities

The following entities are supported in the system:

* Customers
* Items
* Sales Orders

### Available Operations

All entities support the following operations:

* `getAll` – Retrieve all records
* `getOne` – Retrieve a single record by identifier
* `createOrUpdate` – Create a new record or update an existing one
* `delete` – Remove a record
* `action` – Execute a specific action on the entity

## OData Filter Examples

Business Central queries support OData filtering syntax.

```text
email eq 'john@example.com'
inventory lt 10
status eq 'Open'
externalDocumentNumber eq 'SW-10001'
```

---

---
url: /docs/guides/hosting/performance/caches.md
---

# Cache

There are several caches in Shopware that can be used to optimize performance. This page gives a brief overview and shows how to configure them.

## Overview

The HTTP Cache is a *must-have* for every production system. With an enabled cache, the performance of the shop can be greatly increased.

### How to configure the HTTP cache

Basic HTTP cache configuration takes place in the `.env.local` file.

| Name                          | Description                    |
|:------------------------------|:-------------------------------|
| `SHOPWARE_HTTP_CACHE_ENABLED` | Enables the HTTP cache         |
| `SHOPWARE_HTTP_DEFAULT_TTL`   | Defines the default cache time |

`SHOPWARE_HTTP_DEFAULT_TTL` is deprecated and will be removed in Shopware v6.8.0.0. Use [HTTP Caching Policies](#http-caching-policies) instead to define default cache times.

To provide more detailed control over the HTTP cache behavior, use the [HTTP Caching Policies](#http-caching-policies) feature.

The storage used for HTTP Cache is always the [App Cache](#app-cache), see below how to configure it. If you want to move this out of the application cache, you should use an external reverse proxy cache like [Varnish](https://varnish-cache.org/) or [Fastly](https://www.fastly.com/). For more [see here](../infrastructure/reverse-http-cache.md).

### HTTP Caching Policies

> **Note:** This feature is experimental and subject to change. It will be the default behavior in Shopware v6.8.0.0.
> To use it now, enable the `CACHE_REWORK` feature flag.

Caching policies allow you to define HTTP cache behavior per area (storefront, store\_api) and per route via configuration. Shopware comes with reasonable defaults, but you can customize them.

#### Configuration

##### Defining a policy

By default, Shopware ships with `storefront.cacheable`, `store_api.cacheable` and `no_cache_private` policies.
You can define your own policies:

```yaml
# config/packages/shopware.yaml
shopware:
  http_cache:
    policies:
      custom_policy:
        headers:
          cache_control:
            public: true
            max_age: 600  # browser ttl
            s_maxage: 3600  # reverse proxy ttl
```

Supported `cache_control` directives: `public`, `private`, `no_cache`, `no_store`, `no_transform`, `must_revalidate`, `proxy_revalidate`, `immutable`, `max_age`, `s_maxage`, `stale_while_revalidate`, `stale_if_error`. For more information on these directives, see the [MDN docs](https://developer.mozilla.org/en-US/docs/Web/HTTP/Headers/Cache-Control).

You can redefine existing policies. Note that policy definitions are not merged; redefining an existing policy overrides it completely.

Currently, you can only configure the `cache_control` header.

##### Setting default policies

You can change default `cacheable` and `uncacheable` policies per area (`storefront`, `store_api`):

```yaml
shopware:
  http_cache:
    default_policies:
      store_api: # the area name
        cacheable: custom_policy # policy to use for cacheable responses
```

##### Fine-tuning per route or app hook

You can override default policies per route:

```yaml
shopware:
  http_cache:
    route_policies:
      store-api.product.search: custom_policy
```

App developers can override TTLs from the default policies via script configuration. See [custom endpoints](../../plugins/apps/app-scripts/custom-endpoints.md#set-the-max-age-of-the-cache-item) for details.
You can override this by configuring hook-specific policies using the `route#hook` pattern:

```yaml
shopware:
  http_cache:
    route_policies:
      frontend.script_endpoint#storefront-acme-feature: storefront.my_custom_policy # storefront-acme-feature is the normalized hook name
```

##### Policy precedence

Shopware resolves policies in the following order (highest to lowest priority):

1. `route_policies[route#hook]` - most specific, for script endpoints with hooks (e.g., `frontend.script_endpoint#acme-app-hook`).
2. `route_policies[route]` - route-level override.
3. `default_policies[area].{cacheable|uncacheable}` - area defaults; TTLs (`max-age`, `s-maxage`) can be overridden by values from the request attribute or script configuration.

## How to change the cache storage

The standard Shopware HTTP cache can be exchanged or reconfigured in several ways. The standard cache comes with an `adapter.filesystem`. This is a file-based cache that stores the cache in the `var/cache` directory. This allows Shopware to work out of the box on a single server without any additional configuration. However, this may not be the best solution for a production system, especially if you are using a load balancer or multiple servers. In this case, you should use a shared cache like [Redis](https://redis.io/).

This is a Symfony cache pool configuration and therefore supports all adapters from the [Symfony FrameworkBundle](https://symfony.com/doc/current/cache.html#configuring-cache-with-frameworkbundle).

### Using Redis

Redis is a very fast in-memory key-value store. It is a good choice for caching data that is frequently accessed and does not need to be persisted. Redis can be used as a cache adapter in Shopware. As the cached information is ephemeral and can be recreated, it is not necessary to configure Redis to store the data on disk. For maximum performance, you can configure Redis to use no persistence. Refer to the [Redis docs](https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/) for details.
As key eviction policy, you should use `volatile-lru`. This policy only automatically deletes expired data, as the application explicitly manages the TTL for each cache item. For a detailed overview of Redis key eviction policies, see the [Redis docs](https://redis.io/docs/latest/develop/reference/eviction/).

For `cache.adapter.redis_tag_aware` minimum Shopware 6.5.8.3 is required. Otherwise use `cache.adapter.redis`.

```yaml
# config/packages/cache.yaml
framework:
  cache:
    app: cache.adapter.redis_tag_aware
    system: cache.adapter.redis_tag_aware
    default_redis_provider: redis://localhost
```

Make sure that you have installed the PHP Redis extension before applying this configuration.

The Redis URL can have various formats. The following are all valid:

```text
# With explicit port
redis://localhost:6379

# With authentication
redis://auth@localhost:6379

# With database
redis://localhost:6379/1

# With options
redis://localhost:6379?timeout=1

# With unix socket

redis:///var/run/redis.sock

# With unix socket and authentication
redis://auth@/var/run/redis.sock
```

For more information or other adapters checkout [Symfony FrameworkBundle](https://symfony.com/doc/current/cache.html#configuring-cache-with-frameworkbundle) documentation.

### Cache tags and keys without a TTL

This section explains a common surprise when running Shopware's cache on Redis: the cache instance runs out of memory even though eviction is configured correctly. The short version is that some cache keys never expire, and if too many of them pile up, Redis has nothing left to clean up. Read on for what that means and how to fix it.

#### Background: TTL and eviction

A few Redis basics first, so the rest makes sense:

* **TTL (Time To Live)** is an expiry timer on a key. A cache item written with a TTL of one hour is automatically deleted an hour later. A key with **no TTL** is *persistent* — Redis keeps it until something explicitly deletes it.
* **`maxmemory`** is the memory limit you give Redis. When Redis reaches it, it does not just start rejecting `writes` — first it tries to free space using its **eviction policy**.
* The recommended policy for the cache is **`volatile-lru`**. The `volatile` part is the catch: it will only evict keys that **have a TTL**. Keys without a TTL are off-limits — Redis will never evict them, no matter how full it gets.

So a cache Redis sitting at its `maxmemory` limit is completely normal and healthy. It fills up over time, and `volatile-lru` keeps evicting least recently used keys that have a TTL set to make room for new ones. **Full is fine** — as long as enough of that memory is held by keys *with* a TTL, so Redis always has something it is allowed to evict.

#### The problem: cache tags never expire

Shopware needs to invalidate related cache entries together — for example, when a product changes, every cached page that shows that product must be dropped. This is done with **cache tags**, and it requires the `redis_tag_aware` adapter (configured above).

To make tags work, Symfony keeps a **tag index** in Redis. For each tag (say, `product-123`) it stores a Redis *set* listing every cache key that carries that tag. These index keys contain the `\x01tags\x01` marker in their name.

Here is the catch: **these tag-index keys have no TTL.** Only the cached items themselves expire. Walk through what happens to a single cached page:

1. Shopware caches a product page with a one-hour TTL, and adds its key to the `product-123` tag set so it can be invalidated later.
2. An hour passes. The cached page **expires and is removed** — but its entry in the `product-123` tag set is **not** removed. The set now points at a key that no longer exists. That leftover entry is called an **orphaned tag**.
3. Repeat this millions of times a day on a busy shop, and the tag sets keep growing with orphaned entries — and because they have no TTL, `volatile-lru` can never evict them.

While the tag sets are a small share of total memory, everything is fine: there are plenty of expiring cache items for Redis to evict. The trouble starts when the persistent, no-TTL tag data grows large enough that Redis no longer has *enough* evictable keys to reclaim. At that point Redis cannot free space for new `writes` and starts returning **out-of-memory (OOM) errors** — even though `volatile-lru` is set correctly.

::: warning
The problem is **not** that the cache Redis is full — that is expected and healthy. The problem is having **too many keys without a TTL**, which leaves Redis nothing it is allowed to evict. If your cache instance throws OOM errors, do not just raise `maxmemory` — first check how much memory is held by keys *without* a TTL.
:::

#### How to tell if this is your problem

Signs that point at orphaned tags rather than a genuinely undersized cache:

* Redis reports OOM errors (`OOM command not allowed when used memory > 'maxmemory'`) while the eviction policy is `volatile-lru`.
* Raising `maxmemory` only postpones the problem — it fills up again.
* A large share of the used memory is in keys with **no TTL** (in a healthy cache, almost everything should have a TTL).

You can get a rough read directly from `redis-cli`:

```bash
# How many keys have no expiry set at all?
redis-cli INFO keyspace
# e.g. "db0:keys=1000000,expires=200000,avg_ttl=0"
# -> 800000 keys (1,000,000 - 200,000) have NO TTL. That is a red flag.
```

`keys` is the total number of keys and `expires` is how many of them have a TTL; the difference is the number of persistent keys. If that difference is large, orphaned tag sets are the likely cause.

#### The fix: prune orphaned tags regularly

Symfony does not clean up these tag sets on its own, so you have to remove the orphaned entries yourself, on a schedule. Either of these tools does the job (both iterate with the non-blocking `SCAN` command and are safe to run against production):

* **[FroshTools](https://github.com/FriendsOfShopware/FroshTools)** — a Shopware plugin that adds the `frosh:redis-tag:cleanup` console command. It scans the tag sets and removes members pointing at keys that no longer exist.
* **[shopware-redis-cli-helper](https://github.com/shyim/shopware-redis-cli-helper)** — a standalone command-line tool that does the same job faster. Its `insights` command has a **Persistent** view showing exactly how much memory is held by no-TTL keys (handy to confirm the diagnosis first), and its `cleanup` command prunes the orphaned tags.

Using the standalone helper, for example:

```bash
# 1. Confirm the diagnosis: see how much memory is held by keys without a TTL
shopware-redis-cli-helper --url redis://127.0.0.1:6379/0 insights

# 2. Preview what a cleanup would remove (dry run — changes nothing)
shopware-redis-cli-helper --url redis://127.0.0.1:6379/0 cleanup

# 3. Apply the cleanup for real
shopware-redis-cli-helper --url redis://127.0.0.1:6379/0 cleanup --apply
```

The important part is **step 3 on a schedule** — run the cleanup as a recurring cron job (for example, nightly) rather than once. Orphaned tags accumulate continuously, so a one-off cleanup fixes today's symptom, but the instance will fill up again. A regular prune keeps the no-TTL share small and permanently avoids the OOM errors.

---

---
url: /docs/v6.5/guides/hosting/performance/caches.md
---

# Cache

There are several caches in Shopware that can be used to optimize performance. This page gives a brief overview and shows how to configure them.

## Overview

The HTTP Cache is a *must-have* for every production system. With an enabled cache, the performance of the shop can be greatly increased.

### How to configure the HTTP cache

The HTTP cache configuration takes place completely in the `.env file.` The following configurations are available here:

| Name                          | Description                    |
|:------------------------------|:-------------------------------|
| `SHOPWARE_HTTP_CACHE_ENABLED` | Enables the HTTP cache         |
| `SHOPWARE_HTTP_DEFAULT_TTL`   | Defines the default cache time |

### How to trigger the HTTP cache warmer

To warm up the HTTP cache, you can simply use the console command `http:cache:warm:up`. This command sends a message to the message queue for each sales channel domain to warm it up as fast as possible. It is important that queue workers are started according to our [message queue](../infrastructure/message-queue).

### How to change the cache storage

The standard Shopware HTTP cache can be exchanged or reconfigured in several ways. The standard cache comes with an `adapter.filesystem`. The configuration can be found in the `shopware/src/Core/Framework/Resources/config/packages/framework.yaml` file.

```yaml
framework:
    cache:
        pools:
            cache.http:
                adapter: cache.adapter.filesystem
```

This is a Symfony cache pool configuration and therefore supports all adapters from the [Symfony FrameworkBundle](https://symfony.com/doc/current/cache.html#configuring-cache-with-frameworkbundle).

## App cache

The app cache defines the default cache adapter for Shopware. As you can see in this default configuration, every cache-pool in Shopware uses the adapter defined in the `app` cache as default:

```yaml
framework:
    cache:
        prefix_seed: "%kernel.cache.hash%"
        app: cache.adapter.filesystem
        pools:
            cache.object:
                default_lifetime: 3600
                adapter: cache.app
                tags: cache.tags
            cache.http:
                default_lifetime: 3600
                adapter: cache.app
                tags: cache.tags
            cache.tags:
                adapter: cache.app
```

This is also a Symfony cache configuration and supports all adapters from the [Symfony FrameworkBundle](https://symfony.com/doc/current/cache.html#configuring-cache-with-frameworkbundle).

## Object Cache

The object cache pool is used for caching the data abstraction layer in Shopware and can be configured like any other pool.

## Example: replace some cache with Redis

"[Redis](https://redis.io/) is an open source (BSD licensed), in-memory data structure store, used as a database, cache, and message broker." In this example, we change the default HTTP cache adapter to Redis. It is possible to change every adapter as in this example. A running Redis instance is required for this to work. The configuration can be overridden by creating or editing the file `framework.yaml`

For `cache.adapter.redis_tag_aware` minimum Shopware 6.5.8.3 is required. Otherwise use `cache.adapter.redis`.

```yaml
# config/packages/framework.yaml
framework:
    cache:
        default_redis_provider: 'redis://host:port'
        pools:
            cache.http:
                adapter: cache.adapter.redis_tag_aware
                tags: cache.tags
```

Replace the `host` and `port` with your Redis instance. It is also possible to change the cache adapter for `app`, which would affect every pool since they inherit from `app` by default.

```yaml
framework:
    cache:
        app: cache.adapter.redis_tag_aware
        default_redis_provider: 'redis://host:port'
```

## Twig cache

Twig caches all compiled template files by default. With the `cache` option, a directory can be defined, where twig saves the compiled templates. This path can be overridden by creating or editing a `twig.yaml`:

```yaml
# config/packages/twig.yaml
twig:
    cache: '%kernel.cache_dir%/twig'
```

To know more about caching in twig, look at the [Twig for Developers](https://twig.symfony.com/doc/3.x/api.html#) documentation.

---

---
url: /docs/v6.6/guides/hosting/performance/caches.md
---

# Cache

There are several caches in Shopware that can be used to optimize performance. This page gives a brief overview and shows how to configure them.

## Overview

The HTTP Cache is a *must-have* for every production system. With an enabled cache, the performance of the shop can be greatly increased.

### How to configure the HTTP cache

The HTTP cache configuration takes place completely in the `.env.local` file. The following configurations are available here:

| Name                          | Description                    |
|:------------------------------|:-------------------------------|
| `SHOPWARE_HTTP_CACHE_ENABLED` | Enables the HTTP cache         |
| `SHOPWARE_HTTP_DEFAULT_TTL`   | Defines the default cache time |

The storage used for HTTP Cache is always the [App Cache](#app-cache), see below how to configure it. If you want to move this out of the application cache, you should use an external reverse proxy cache like [Varnish](https://varnish-cache.org/) or [Fastly](https://www.fastly.com/). For more [see here](../infrastructure//reverse-http-cache.md).

## How to change the cache storage

The standard Shopware HTTP cache can be exchanged or reconfigured in several ways. The standard cache comes with an `adapter.filesystem`. This is a file-based cache that stores the cache in the `var/cache` directory. This allows Shopware to work out of the box on a single server without any additional configuration. However, this may not be the best solution for a production system, especially if you are using a load balancer or multiple servers. In this case, you should use a shared cache like [Redis](https://redis.io/).

This is a Symfony cache pool configuration and therefore supports all adapters from the [Symfony FrameworkBundle](https://symfony.com/doc/current/cache.html#configuring-cache-with-frameworkbundle).

### Using Redis

Redis is a very fast in-memory key-value store. It is a good choice for caching data that is frequently accessed and does not need to be persisted. Redis can be used as a cache adapter in Shopware. As the cached information is ephemeral and can be recreated, it is not necessary to configure Redis to store the data on disk. For maximum performance, you can configure Redis to use no persistence. Refer to the [Redis docs](https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/) for details.
As key eviction policy, you should use `volatile-lru`. This policy only automatically deletes expired data, as the application explicitly manages the TTL for each cache item. For a detailed overview of Redis key eviction policies, see the [Redis docs](https://redis.io/docs/latest/develop/reference/eviction/).

For `cache.adapter.redis_tag_aware` minimum Shopware 6.5.8.3 is required. Otherwise use `cache.adapter.redis`.

```yaml
# config/packages/cache.yaml
framework:
  cache:
    app: cache.adapter.redis_tag_aware
    system: cache.adapter.redis_tag_aware
    default_redis_provider: redis://localhost
```

Make sure that you have installed the PHP Redis extension before applying this configuration.

The Redis URL can have various formats. The following are all valid:

```text
# With explicit port
redis://localhost:6379

# With authentication
redis://auth@localhost:6379

# With database
redis://localhost:6379/1

# With options
redis://localhost:6379?timeout=1

# With unix socket

redis:///var/run/redis.sock

# With unix socket and authentication
redis://auth@/var/run/redis.sock
```

For more information or other adapters checkout [Symfony FrameworkBundle](https://symfony.com/doc/current/cache.html#configuring-cache-with-frameworkbundle) documentation.

---

---
url: /docs/resources/references/adr/2025-08-19-cache-layer-for-navigation-loader.md
---

# Cache layer for navigation loader

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2025-08-19-cache-layer-for-navigation-loader.md)
:::

## Context

We see in multiple performance analysis that the navigation loader can be a bottleneck for the performance of the storefront, especially with a huge number of categories in the first levels of the category tree.
The navigation loader is responsible for loading the categories and their children, which are then used to render the navigation in the storefront.
This process can be quite expensive, not just because of the query time on the DB, but also for hydrating the entities into PHP objects.
The other part with a huge performance impact is the rendering performance on twig side for the many nested categories, however that is not part of this ADR.

The navigation loader is used in the storefront for every header and every listing page (when they use the sidebar navigation CMS element).
However, the data that is loaded is always the same for the same sales channel, because we always show/load the category tree for the main navigation of the sales channel to the depth that is configured in the sales channel config.

Adding support for ESI for the header and footer addresses the same fundamental performance issue, however it does not solve the problem for the listing pages, where the sidebar navigation CMS element is used.
Additionally, for ESI to be effective you would need a reverse proxy that supports ESI, and you need to disable compression your responses from your webserver, which could increase your infrastructure costs. So ESI is not a viable solution for every use case.

## Decision

We will implement a cache layer for the navigation loader to improve the performance of the storefront.
To not only safe the query time, but also the hydration time, we will store the categories as PHP serialized objects. That should be fine, because when the structure of the PHP objects changes, that means there is a new platform version, in which case the cache needs to be cleared anyway.
Also in order to be most effective and not store too much data, we will only cache the category tree for the main navigation for every sales channel and up to the depths that is configured in the sales channel, because that info is loaded on every header and every listing page (when they use the sidebar navigation CMS element).
We use the `CacheCompressor` to compress the serialized data before storing it in the cache, which should reduce the size of the cache entries significantly, however it adds some more processing time when reading and writing the cache entries.

This cache layer will work complementary to ESI, because ESI would also cache the rendered HTML of the navigation, the performance impact of ESI will be faster, but category information for the sidebar navigation is still loaded on every listing page, so this change is still beneficial in regard to performance, even when you use ESI.

## Consequences

* The loaded categories for the main navigation will be cached to the level defined in the sales channel config.
* Additional categories that might be loaded because e.g. the currently active category is below the configured depth will be loaded dynamically per request and merged with the default categories.
* The cache needs to be invalidated whenever a category is written or deleted. We use immediate cache invalidation for that, so that the behaviour is as before, even with deactivated HTTP-Cache.
* We encode the information about the `salesChannelId`, `language`, `root category id` and `depth` in the cache key, so that we can cache the categories for different sales channels and languages.
* We will add a `CategoryLevelLoaderCacheKeyEvent` so that plugins can modify the cache key if they dynamically influence which categories should be loaded/shown.

---

---
url: /docs/resources/references/adr/2022-03-25-cache-stampede-protection.md
---

# Cache stampede protection

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-03-25-cache-stampede-protection.md)
:::
The Cache Stampede protection is a mechanism to prevent several users try to update this cache entry at the same time if a cache entry is no longer hot. This mechanism is very useful if there is a lot of load on the store and a cache entry is expired or invalidated. If there is no cache stampede protection on the system, and several users call a category listing at the same time, which is no longer in the cache, then all users would be let through to the database and the server could collapse under the load.

We have now integrated such a protection into all our services using the [`\Symfony\Contracts\Cache\CacheInterface` of symfony](https://symfony.com/blog/new-in-symfony-4-2-cache-stampede-protection). This mechanic is mainly used in our cached store api routes. Another positive side effect is that the code has become much more concise, since much is done within symfony:

## `CachedRuleLoader` before

```php
<?php declare(strict_types=1);

namespace Shopware\Core\Checkout\Cart;

use Psr\Log\LoggerInterface;
use Shopware\Core\Content\Rule\RuleCollection;
use Shopware\Core\Framework\Context;
use Symfony\Component\Cache\Adapter\TagAwareAdapterInterface;

class CachedRuleLoader extends AbstractRuleLoader
{
    public const CACHE_KEY = 'cart_rules';

    private AbstractRuleLoader $decorated;

    private TagAwareAdapterInterface $cache;

    private LoggerInterface $logger;

    public function __construct(AbstractRuleLoader $decorated, TagAwareAdapterInterface $cache, LoggerInterface $logger)
    {
        $this->decorated = $decorated;
        $this->cache = $cache;
        $this->logger = $logger;
    }

    public function getDecorated(): AbstractRuleLoader
    {
        return $this->decorated;
    }

    public function load(Context $context): RuleCollection
    {
        $item = $this->cache->getItem(self::CACHE_KEY);

        try {
            if ($item->isHit() && $item->get()) {
                $this->logger->info('cache-hit: ' . self::CACHE_KEY);

                return $item->get();
            }
        } catch (\Throwable $e) {
            $this->logger->error($e->getMessage());
        }

        $this->logger->info('cache-miss: ' . self::CACHE_KEY);

        $rules = $this->getDecorated()->load($context);

        $item->set($rules);
        $this->cache->save($item);

        return $rules;
    }
}
```

## `CachedRuleLoader` after

```php
<?php declare(strict_types=1);

namespace Shopware\Core\Checkout\Cart;

use Shopware\Core\Content\Rule\RuleCollection;
use Shopware\Core\Framework\Context;
use Symfony\Contracts\Cache\CacheInterface;

class CachedRuleLoader extends AbstractRuleLoader
{
    public const CACHE_KEY = 'cart_rules';

    private AbstractRuleLoader $decorated;

    private CacheInterface $cache;

    public function __construct(AbstractRuleLoader $decorated, CacheInterface $cache)
    {
        $this->decorated = $decorated;
        $this->cache = $cache;
    }

    public function getDecorated(): AbstractRuleLoader
    {
        return $this->decorated;
    }

    public function load(Context $context): RuleCollection
    {
        return $this->cache->get(self::CACHE_KEY, function () use ($context): RuleCollection {
            return $this->decorated->load($context);
        });
    }
}
```

However, since the service itself does not recognize whether it is a cache hit or miss, we have removed the corresponding logging.

---

---
url: /docs/v6.5/resources/references/adr/2022-03-25-cache-stampede-protection.md
---

# Cache stampede protection

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-03-25-cache-stampede-protection.md)
:::
The Cache Stampede protection is a mechanism to prevent several users try to update this cache entry at the same time if a cache entry is no longer hot. This mechanism is very useful if there is a lot of load on the store and a cache entry is expired or invalidated. If there is no cache stampede protection on the system, and several users call a category listing at the same time, which is no longer in the cache, then all users would be let through to the database and the server could collapse under the load.

We have now integrated such a protection into all our services using the [`\Symfony\Contracts\Cache\CacheInterface` of symfony](https://symfony.com/blog/new-in-symfony-4-2-cache-stampede-protection). This mechanic is mainly used in our cached store api routes. Another positive side effect is that the code has become much more concise, since much is done within symfony:

## `CachedRuleLoader` before

```php
<?php declare(strict_types=1);

namespace Shopware\Core\Checkout\Cart;

use Psr\Log\LoggerInterface;
use Shopware\Core\Content\Rule\RuleCollection;
use Shopware\Core\Framework\Context;
use Symfony\Component\Cache\Adapter\TagAwareAdapterInterface;

class CachedRuleLoader extends AbstractRuleLoader
{
    public const CACHE_KEY = 'cart_rules';

    private AbstractRuleLoader $decorated;

    private TagAwareAdapterInterface $cache;

    private LoggerInterface $logger;

    public function __construct(AbstractRuleLoader $decorated, TagAwareAdapterInterface $cache, LoggerInterface $logger)
    {
        $this->decorated = $decorated;
        $this->cache = $cache;
        $this->logger = $logger;
    }

    public function getDecorated(): AbstractRuleLoader
    {
        return $this->decorated;
    }

    public function load(Context $context): RuleCollection
    {
        $item = $this->cache->getItem(self::CACHE_KEY);

        try {
            if ($item->isHit() && $item->get()) {
                $this->logger->info('cache-hit: ' . self::CACHE_KEY);

                return $item->get();
            }
        } catch (\Throwable $e) {
            $this->logger->error($e->getMessage());
        }

        $this->logger->info('cache-miss: ' . self::CACHE_KEY);

        $rules = $this->getDecorated()->load($context);

        $item->set($rules);
        $this->cache->save($item);

        return $rules;
    }
}
```

## `CachedRuleLoader` after

```php
<?php declare(strict_types=1);

namespace Shopware\Core\Checkout\Cart;

use Shopware\Core\Content\Rule\RuleCollection;
use Shopware\Core\Framework\Context;
use Symfony\Contracts\Cache\CacheInterface;

class CachedRuleLoader extends AbstractRuleLoader
{
    public const CACHE_KEY = 'cart_rules';

    private AbstractRuleLoader $decorated;

    private CacheInterface $cache;

    public function __construct(AbstractRuleLoader $decorated, CacheInterface $cache)
    {
        $this->decorated = $decorated;
        $this->cache = $cache;
    }

    public function getDecorated(): AbstractRuleLoader
    {
        return $this->decorated;
    }

    public function load(Context $context): RuleCollection
    {
        return $this->cache->get(self::CACHE_KEY, function () use ($context): RuleCollection {
            return $this->decorated->load($context);
        });
    }
}
```

However, since the service itself does not recognize whether it is a cache hit or miss, we have removed the corresponding logging.

---

---
url: /docs/v6.6/resources/references/adr/2022-03-25-cache-stampede-protection.md
---

# Cache stampede protection

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-03-25-cache-stampede-protection.md)
:::
The Cache Stampede protection is a mechanism to prevent several users try to update this cache entry at the same time if a cache entry is no longer hot. This mechanism is very useful if there is a lot of load on the store and a cache entry is expired or invalidated. If there is no cache stampede protection on the system, and several users call a category listing at the same time, which is no longer in the cache, then all users would be let through to the database and the server could collapse under the load.

We have now integrated such a protection into all our services using the [`\Symfony\Contracts\Cache\CacheInterface` of symfony](https://symfony.com/blog/new-in-symfony-4-2-cache-stampede-protection). This mechanic is mainly used in our cached store api routes. Another positive side effect is that the code has become much more concise, since much is done within symfony:

## `CachedRuleLoader` before

```php
<?php declare(strict_types=1);

namespace Shopware\Core\Checkout\Cart;

use Psr\Log\LoggerInterface;
use Shopware\Core\Content\Rule\RuleCollection;
use Shopware\Core\Framework\Context;
use Symfony\Component\Cache\Adapter\TagAwareAdapterInterface;

class CachedRuleLoader extends AbstractRuleLoader
{
    public const CACHE_KEY = 'cart_rules';

    private AbstractRuleLoader $decorated;

    private TagAwareAdapterInterface $cache;

    private LoggerInterface $logger;

    public function __construct(AbstractRuleLoader $decorated, TagAwareAdapterInterface $cache, LoggerInterface $logger)
    {
        $this->decorated = $decorated;
        $this->cache = $cache;
        $this->logger = $logger;
    }

    public function getDecorated(): AbstractRuleLoader
    {
        return $this->decorated;
    }

    public function load(Context $context): RuleCollection
    {
        $item = $this->cache->getItem(self::CACHE_KEY);

        try {
            if ($item->isHit() && $item->get()) {
                $this->logger->info('cache-hit: ' . self::CACHE_KEY);

                return $item->get();
            }
        } catch (\Throwable $e) {
            $this->logger->error($e->getMessage());
        }

        $this->logger->info('cache-miss: ' . self::CACHE_KEY);

        $rules = $this->getDecorated()->load($context);

        $item->set($rules);
        $this->cache->save($item);

        return $rules;
    }
}
```

## `CachedRuleLoader` after

```php
<?php declare(strict_types=1);

namespace Shopware\Core\Checkout\Cart;

use Shopware\Core\Content\Rule\RuleCollection;
use Shopware\Core\Framework\Context;
use Symfony\Contracts\Cache\CacheInterface;

class CachedRuleLoader extends AbstractRuleLoader
{
    public const CACHE_KEY = 'cart_rules';

    private AbstractRuleLoader $decorated;

    private CacheInterface $cache;

    public function __construct(AbstractRuleLoader $decorated, CacheInterface $cache)
    {
        $this->decorated = $decorated;
        $this->cache = $cache;
    }

    public function getDecorated(): AbstractRuleLoader
    {
        return $this->decorated;
    }

    public function load(Context $context): RuleCollection
    {
        return $this->cache->get(self::CACHE_KEY, function () use ($context): RuleCollection {
            return $this->decorated->load($context);
        });
    }
}
```

However, since the service itself does not recognize whether it is a cache hit or miss, we have removed the corresponding logging.

---

---
url: /docs/guides/plugins/plugins/framework/caching.md
---

# Caching

## Overview

Caching is a technique to store frequently accessed data in a temporary storage layer for faster retrieval, reducing latency and improving performance by avoiding repeated and costly data retrieval operations

While caching enhances performance, it requires careful management of data consistency, cache invalidation strategies, and storage efficiency to prevent serving outdated or incorrect data.

This guide will show you how you can modify the default caching mechanisms to suite your needs. If you are looking for information on how to add your routes to the HTTP-Cache, take a look at [this guide](../../storefront/advanced/add-caching-to-custom-controller.md).

## Cache Layers

The current cache system of Shopware is based on a multi-layer system, in which the individual layers build on each other to improve performance and scalability.
There is the [HTTP-Cache](../../../../../concepts/framework/http_cache.md) on the outer level and then multiple smaller internal "Object Caches" that are used to cache data in the application.

For information on how to configure the different cache layers, please refer to the [caching hosting guide](../../../../hosting/performance/caches.md).

### HTTP-Cache

Before jumping in and adjusting the HTTP-Caching, please familiarize yourself with the general [HTTP-Cache concept](../../../../../concepts/framework/http_cache.md) first.

#### Manipulating the cache key

There are several entry points to manipulate the cache key.

* `Shopware\Core\Framework\Adapter\Cache\Http\Extension\CacheHashRequiredExtension`: used to determine whether the cache hash should be calculated or if the request in running in the default state, and therefore no cache-hash is needed.
* `Shopware\Core\Framework\Adapter\Cache\Event\HttpCacheCookieEvent`: used to calculate the cache hash based on the application state, supports both reverse proxy caches and the default symfony HTTP-cache component.
* `Shopware\Core\Framework\Adapter\Cache\Http\Extension\ResolveCacheRelevantRuleIdsExtension`: used to determine which rule IDs are relevant for the cache hash.
* `Shopware\Core\Framework\Adapter\Cache\Event\HttpCacheKeyEvent`: used to calculate the exact cache key based on the response, only for symfony's default HTTP-cache component.

##### Modifying when the cache hash is calculated

By default, the cache hash is only calculated when the request is not in the default state, which is: no logged in customer, default currency, and an empty cart.
The reason is that the very first request to the application from a client should always be cached in the best case, the state that the application is in then is the "default state", which does not require a cache hash.
You can overwrite the default behaviour and add more conditions where the cache hash needs to be applied, e.g., when you shop needs to be more dynamic e.g. based on campaign query parameters:

```php
class RequireCacheHash implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            CacheHashRequiredExtension::NAME . '.post' => 'onRequireCacheHash',,
        ];
    }

    public function onRequireCacheHash(CacheHashRequiredExtension $extension): void
    {
        if ($extension->request->query->has('campaignId')) {
            $extension->result = true;
        }
    }
}
```

##### Modifying the cache hash

The cache hash is used as the basis for the cache key.
It is calculated based on the application state, which includes the current user, the current language, and so on.
As the cache hash is calculated based on the application state, you have access to the resolved `SalesChannelContext` to determine the cache hash.
It is stored alongside the response as a cookie and thus also provided with all following requests, to allow differentiating the cache based on the application state.
As the cache hash will be carried over to the next request, the computed cache hash can be used inside reverse proxy caches as well as the default symfony HTTP-cache component.

:::info
The cache hash is only computed on every response as soon as the application state differs from the default state, which is: no logged in customer, default currency, and an empty cart.
:::

By default, the cache hash will consist of the following parts:

* `rule-ids`: The matched rule IDs, to reduce possible cache permutations starting with v6.8.0.0, this will only include the rule IDs in `rule areas` that are cache relevant. See the next chapter how to extend this.
* `version-id`: The context version used to load versioned DAL entities.
* `currency-id`: The currency ID of the context.
* `tax-state`: The tax state of the context (gross/net).
* `logged-in`: Whether a customer is logged in in the current state or not.

To modify the cache hash, you can subscribe to the `HttpCacheCookieEvent` event and add your own parts to the cache hash.
This allows you to add more parts to the cache hash, e.g., the current customer's group.
You can also disable the cache for certain conditions, because if that condition is met, the content is so dynamic that caching is not efficiently possible e.g., if the cart is filled.

```php
class HttpCacheCookieListener implements EventSubscriberInterface
{
    public function __construct(
        private readonly CartService $cartService
    ) {
    }
    
    public static function getSubscribedEvents(): array
    {
        return [
            HttpCacheCookieEvent::class => 'onCacheCookie',
        ];
    }

    public function onCacheCookie(HttpCacheCookieEvent $event): void
    {
        // you can add custom parts to the cache hash
        // keep in mind that every possible value will increase the number of possible cache permutations
        // and therefore directly impact cache hit rates, which in turn decreases performance
        $event->add('customer-group', $event->context->getCustomerId());

        // disable cache for filled carts
        $cart = $this->cartService->getCart($event->context->getToken(), $event->context);
        if ($cart->getLineItems()->count() > 0) {
            // you can also explicitly disable caching based on specific conditions
            $event->isCacheable = false;
        }
    }
}
```

Additionally, you can modify the cache hash from the frontend client directly by adding separate cookies with the relevant value.
You can configure custom cookies that are relevant for the cache hash in the `shopware.http_cache.cookies` option:

```yaml
shopware:
    http_cache:
        cookies:
            - 'my-custom-cookie'
```

As soon as the cookie is set, that value will be included in the cache hash.
Essentially, it saves you the effort to implement a custom cache cookie listener as shown above.
This makes it especially suited for headless projects where the frontend implementation is more decoupled from the backend.

##### Marking rule areas as cache relevant

Starting with v6.8.0.0, the cache hash will only include the rule IDs in `rule areas` that are cache relevant.
The reason is that a lot of rules are not relevant for the cache, e.g., rules that only affect pricing or shipping methods.
This greatly reduces the number of possible cache permutations, which in turn improves the cache hit rate.

By default, only the following rule areas are cache relevant:

* `RuleAreas::PRODUCT_AREA`

If you use the rule system in a way that is relevant for the cache (because the response differs based on the rules), you should add your rule area to the list of cache relevant rule areas.
To do so, you need to subscribe to the `ResolveCacheRelevantRuleIdsExtension` event.

```php
class ResolveRuleIds implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            ResolveCacheRelevantRuleIdsExtension::NAME . '.pre' => 'onResolveRuleAreas',
        ];
    }

    public function onResolveRuleAreas(ResolveCacheRelevantRuleIdsExtension $extension): void
    {
        $extension->ruleAreas[] = RuleExtension::MY_CUSTOM_RULE_AREA;
    }
}
```

This implies that you defined the rule area in your custom entities that have an associated rule entity, by using the DAL flag `Shopware\Core\Framework\DataAbstractionLayer\Field\Flag\RuleAreas` on the rule association in the entity extension.

```php
class RuleExtension extends EntityExtension
{
    public const MY_CUSTOM_RULE_AREA = 'custom';

    public function getEntityName(): string
    {
        return RuleDefinition::ENTITY_NAME;
    }

    public function extendFields(FieldCollection $collection): void
    {
        $collection->add(
            (new ManyToManyAssociationField(
                'myPropertyName',
                MyCustomDefinition::class,
                MyMappingDefinition::class,
                RuleDefinition::ENTITY_NAME . '_id',
                MyCustomDefinition::ENTITY_NAME . '_id',
            ))->addFlags(new CascadeDelete(), new RuleAreas(self::MY_CUSTOM_RULE_AREA)),
        );
    }
}
```

For details on how to extend core definitions refer to the [DAL Guide](../../framework/data-handling/add-complex-data-to-existing-entities.md).

##### Modifying the cache keys

You can also modify the exact cache key used to store the response in the [symfony HTTP-Cache](https://symfony.com/doc/current/http_cache.html).
If possible, you should manipulate the cache hash (as already explained above) instead, as that is also used in reverse proxy caches.
You can do so by subscribing to the `HttpCacheKeyEvent` event and add your specific part to the key.

```php
class CacheKeySubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            HttpCacheKeyEvent::class => 'addKeyPart',
        ];
    }
    
    public function addKeyPart(HttpCacheKeyEvent $event): void
    {
        $request = $event->request;
        // Perform checks to determine the key
        $key = $this->determineKey($request);
        $event->add('myCustomKey', $key);
        
        // You can also disable caching for certain conditions
        $event->isCacheable = false;
    }
}
```

:::info
The event is called on any Request; make sure that you don't use expensive operations like Database Queries.

Also, with an external reverse proxy, the cache key might be generated on the proxy and not in your application. In that case, you need to add the key part to the reverse proxy configuration.
:::

#### Adding cache tags

One problem with caching is that you not only need to retrieve the correct data, but also need to have a performant way to invalidate the cache when the data changes.
Only invalidating the caches based on the unique cache key is often not that helpful, because you don't know which cache keys are affected by the change of a specific data set.
Therefore, a tagging system is used alongside the cache keys to make cache invalidations easier and more performant. Every cache entry can be tagged with multiple tags, thus we can invalidate the cache based on the tags.
For example, all pages that contain product data are tagged with product IDs of all products they contain. So if a product is changed, we can invalidate all cache entries that are tagged with the product ID of the changed product.

To add your own cache tags to the HTTP-Cache, you can use the `CacheTagCollector` service.

```php
class MyCustomEntityExtension
{
    public function __construct(
        private readonly CacheTagCollector $cacheTagCollector,
    ) {}
    
    public function loadAdditionalData(): void
    {
        // Load the additional data you need, add it to the response, then add the correct tag to the cache entry
        $this->cacheTagCollector->addTag('my-custom-entity-' . $idOfTheLoadedData);
    }
}
```

#### Invalidating the cache

Adding custom cache tags is only useful if you also use them to invalidate the cache when the data changed.
To invalidate the cache, you need to call the `CacheInvalidator` service and pass the tag you want to invalidate.

```php
class CacheInvalidationSubscriber implements EventSubscriberInterface
{
    public function __construct(private CacheInvalidator $cacheInvalidator)
    {
    }
    
    public static function getSubscribedEvents()
    {
        return [
            // The EntityWrittenContainerEvent is a generic event always thrown when an entities are written. This contains all changed entities
            EntityWrittenContainerEvent::class => 'invalidate'
            ],
        ];
    }
    
    public function invalidate(EntityWrittenContainerEvent $event): void
    {
        // Check if own entity written. In some cases, you want to use the primary keys for further cache invalidation
        $changes = $event->getPrimaryKeys(ExampleDefinition::ENTITY_NAME);
        
        // No example entity changed? Then the cache does not need to be invalidated
        if (empty($changes)) {
            return;
        }

        foreach ($changes as $id) {
            // Invalidate the cache for the changed entity
            $this->cacheInvalidator->invalidate([
                'my-custom-entity-' . $id
            ]);
        }
    }
}
```

##### Overwrite default cache invalidation behaviour

The default tags that shopware adds to the HTTP-Cache are also invalidated automatically when the data changes. This is done by the `CacheInvalidationSubscriber` class, which listens to various events and invalidates the cache based on the tags that are added to the cache entries.
However, the subscriber adheres to an exact invalidation concept, where any data written to the product invalidates cache tags for that specific product, even if the data is not used in the corresponding pages. This might lead to cases where the cache is invalidated too often, and the invalidation can be tweaked to the project's needs. Moreover, due to project-specific variations, it is not feasible to generalize the process.
Therefore, all events it listens to are configured over the service configuration, so that all events, on which the subscriber listens to, can be manipulated via compiler passes.

:::code-group

```php [src/Core/Framework/DependencyInjection/cache.php]
$services->set(CacheInvalidationSubscriber::class)
    ->args([
        service(CacheInvalidator::class),
        service(Connection::class),
        param('shopware.product_stream.indexing'),
    ])
    ->tag('kernel.event_listener', ['event' => CategoryIndexerEvent::class, 'method' => 'invalidateCategoryRouteByCategoryIds', 'priority' => 2000])
    ->tag('kernel.event_listener', ['event' => LandingPageIndexerEvent::class, 'method' => 'invalidateIndexedLandingPages', 'priority' => 2000])
    // ...
;
```

:::

For example, if you want to disable all cache invalidations in a project, you can remove the `kernel.event_listener` tag of the service definition via compiler pass and implement your own cache invalidation.

```php
use Shopware\Core\Content\Product\Events\ProductIndexerEvent;
use Shopware\Core\Content\Product\Events\ProductNoLongerAvailableEvent;
use Shopware\Core\Framework\DependencyInjection\CompilerPass\RemoveEventListener;
use Shopware\Core\Framework\Adapter\Cache\CacheInvalidationSubscriber;

class TweakCacheInvalidation implements CompilerPassInterface
{
    public function process(ContainerBuilder $container): void
    {
        $container
            ->getDefinition(CacheInvalidationSubscriber::class)
            ->clearTag('kernel.event_listener')
    }

}
```

However, suppose only certain parts of the cache invalidation are to be adjusted, finer adjustments to the class can be made using `Shopware\Core\Framework\DependencyInjection\CompilerPass\RemoveEventListener`, in which it is possible to define which event listeners of the service are to be removed.

```php
use Shopware\Core\Content\Product\Events\ProductIndexerEvent;
use Shopware\Core\Content\Product\Events\ProductNoLongerAvailableEvent;
use Shopware\Core\Framework\DependencyInjection\CompilerPass\RemoveEventListener;
use Shopware\Core\Framework\Adapter\Cache\CacheInvalidationSubscriber;

class TweakCacheInvalidation implements CompilerPassInterface
{
    public function process(ContainerBuilder $container): void
    {
        RemoveEventListener::remove(
            $container,
            CacheInvalidationSubscriber::class,
            [
                [ProductIndexerEvent::class, 'invalidateListings'],
                [ProductNoLongerAvailableEvent::class, 'invalidateListings'],
            ]
        );
    }
}
```

### Object Cache

The internal caches are built upon the [Symfony Cache](https://symfony.com/doc/current/components/cache.html) component and are used internally to cache data that is expensive to compute or retrieve.
As the object caches are handled internally, it should not be necessary to control them directly, therefore adding custom tags or manipulating the cache key is not supported for the various object caches.

#### Cache invalidation

However, you can still manually invalidate the object caches, via the same mechanism as you invalidate the HTTP-Cache, the `CacheInvalidator` service.

You can use the `CacheInvalidator` service to invalidate the object caches by passing the tag you want to invalidate.

```php
public function invalidateSystemConfigCache(): void
{
    $this->cacheInvalidator->invalidate([
        CachedSystemConfigLoader::CACHE_TAG
    ]);
}
```

## Delayed Invalidation

By default, the cache invalidation happens delayed (for both http and object caches). This means that the invalidation is not instant, but rather all the tags that should be invalidated are invalidated in a regular interval. For special cases where you need to immediately clear the cache take a look at the [force immediate invalidation](#force-immediate-invalidation) section.
This really benefits the performance of the system, as the invalidation is not done immediately, but rather in a batch process.
Additionally, it prevents cases where sometimes the caches are written and deleted more often than they are read, which only leads to overhead, more resource needs on the caching side and a bad cache-hit rate.

The invalidation of the delayed cache is done via the `shopware.invalidate_cache` task, that runs every 5 minutes (default setting). However, that run interval can be adjusted in the database.
If your caches don't seem to be invalidated at all, please ensure that the scheduled tasks are running correctly.

You can also manually invalidate the cache entries that are marked for delayed invalidation by running the `cache:clear:delayed` command or calling the `CacheInvalidator::invalidateExpired()` method from your plugin or send an API request to the `DELETE /api/_action/cache-delayed` endpoint.
For debug purposes you can also watch the tags that are marked for delayed invalidation by running the `cache:watch:delayed` command.

### Force immediate invalidation

Some changes require that the caches should be invalidated immediately and returning stale content is not acceptable.
In that case you can pass the `force=true` flag to the CacheInvalidator service, which will invalidate the cache immediately.

```php
public function invalidateSystemConfigCache(): void
{
    $this->cacheInvalidator->invalidate([
        CachedSystemConfigLoader::CACHE_TAG
    ], true);
}
```

If you sent an API request with critical information, where the cache should be invalidated immediately, you can set the `sw-force-cache-invalidate` header on your request.

```http
POST /api/product
sw-force-cache-invalidate: 1
```

## Manual cache clear

You can also manually clear the caches when you performed some actions that made a cache invalidation necessary, but where it was not triggered automatically.

To clear all caches, you can execute the `cache:clear:all` command, which clears the HTTP-Cache and the object caches, and removes other kernel cache directories.

The `cache:clear` command on the other hand will only clear the object caches, but won't invalidate the HTTP-Cache.
On the other hand, the `cache:clear:http` command will clear the complete HTTP-Cache, but won't invalidate the object caches.

::: warning
`cache:clear` only clears the cache directory matching the current kernel's configuration. If you run `bin/console cache:clear` but web requests still use stale cache, the CLI and web server may be using different cache directories. This can happen when plugins are in different states (e.g., installed via Composer but not yet activated in the database). Use `cache:clear:all` to clear all cache variants.
:::

::: details How cache:clear works internally
The Symfony `cache:clear` command uses an atomic directory swap to ensure the application always has a valid cache. It first removes any leftover temporary directories, then creates and warms up the new cache in `var/cache/{env}_new/`. Once ready, it renames the current cache directory to a backup and moves the new one into place. Finally, it removes the backup.

This approach ensures zero downtime because the application always has a working cache directory. The swap uses filesystem rename operations which are atomic on most systems. On NFS filesystems, directories are deleted instead of renamed due to limitations with atomic operations.

For more details, see the [Symfony CacheClearCommand source](https://github.com/symfony/symfony/blob/7.4/src/Symfony/Bundle/FrameworkBundle/Command/CacheClearCommand.php).
:::

---

---
url: /frontends/best-practices/caching.md
---

# Caching

Shopware Frontends templates cache at several independent layers. Each one solves a different problem, and they compose: a request can be served from the browser cache, a CDN, an ISR-rendered HTML page, the Shopware backend HTTP cache, or fall through to a fresh Store API call. This page describes the strategies available in a Shopware Frontends project (Nuxt 4 / Vue 3, built on packages such as `@shopware/nuxt-module`, `@shopware/composables`, and `@shopware/api-client`), when to reach for each, and how to configure them.

## Caching at a glance

| Layer                            | What it caches                                                 | Where it runs                      | How you configure it                     |
| -------------------------------- | -------------------------------------------------------------- | ---------------------------------- | ---------------------------------------- |
| Request layer (`cacheableReads`) | Anonymous Store API reads, routed through cacheable GET routes | Composables -> HTTP infrastructure | `shopware: { cacheableReads: true }`     |
| Render layer (`routeRules`)      | Rendered HTML pages (ISR / SWR), per-route headers             | Nuxt / Nitro server                | `routeRules` in `nuxt.config.ts`         |
| Edge / CDN layer                 | GET responses and HTML with cacheable `Cache-Control`          | CDN / reverse proxy                | `Cache-Control` headers + your CDN       |
| Backend HTTP cache               | Store API GET responses (Varnish / Fastly)                     | Shopware backend                   | Shopware reverse-proxy config (platform) |
| Client state                     | Session, cart, user, listings, navigation                      | Browser memory (per session)       | Shared composables, `provide`/`inject`   |
| Assets / images                  | Optimized images, SVGs, static files                           | CDN / browser                      | `@nuxt/image` presets, route headers     |

The first three layers are about HTTP responses; the last two are about avoiding work the storefront already did. Most of them are not specific to Shopware Frontends: the render layer (`routeRules`, ISR / SWR / prerender), Nitro cache storage, asset caching, and client-side shared state are standard [Nuxt](https://nuxt.com) / Nitro / Vue capabilities that a Shopware Frontends project configures like any other Nuxt app - we are one use case of what the framework already provides. Only the request layer (`cacheableReads`) and the Shopware backend HTTP cache it unlocks are Shopware-specific. This page focuses on how a storefront wires these pieces together and links out to the Nuxt and Nitro docs for the underlying features.

::: info
ISR and route-rule caching are honored only by deployment targets that support them (a Node server, Vercel, Netlify, or another Nitro-compatible host) and only in a production build. They have no effect under `nuxt dev`. See [Deployment](./deployment) for hosting models.
:::

## Request layer: `cacheableReads`

`cacheableReads` is the headline new capability. It is an opt-in boolean flag (default `false`) that switches a defined set of read composables from POST to the cacheable GET variants of the Store API. POST responses are not cached by CDNs, reverse proxies, or browsers in practice (HTTP allows it only when explicitly marked, which shared caches generally ignore), whereas GET responses are cacheable by default. Enabling the flag is what makes that possible from the frontend side.

When enabled, the affected composables encode the Shopware Criteria object into a `_criteria` query parameter (gzip + base64url, via `encodeForQuery` from `@shopware/api-client/helpers`) and call the GET route instead of sending a POST body.

### Why GET over POST (the architectural decision)

Routing reads through GET is a deliberate Shopware platform decision, not just a frontend trick. The Store API [cache strategy](https://developer.shopware.com/docs/resources/references/adr/2025-09-15-store-api-cache-strategy.html) is to "prefer GET for non-mutating endpoints returning non-sensitive data", because GET responses are cacheable by default under HTTP semantics while POST responses are not. Several read routes historically defaulted to POST only so a large Criteria object could travel in the request body - and that body is exactly what makes them uncacheable.

The `_criteria` query parameter exists to remove that constraint. Its encoding - JSON -> gzip -> base64url - is defined by the platform, and `encodeForQuery` in `@shopware/api-client/helpers` implements precisely that format, keeping the Criteria small enough to travel in the URL for typical reads (very large criteria can still exceed environment URL-length limits). On the backend, `RequestCriteriaBuilder` decodes `_criteria` and rebuilds the same Criteria it would have parsed from a POST body, so the GET and POST variants return identical data. This is a transitional design: the interim approach until the HTTP `QUERY` method (a cacheable method that carries a body) is standardized.

A route can only be migrated to GET once its GET variant declares `_criteria` in the OpenAPI schema, because the generated, typed client is built from that schema. That schema gap - not a runtime limitation - is the only reason the reads listed further down stay on POST; the backend already honors `_criteria` on those GET routes at runtime.

### Enabling it

For a Nuxt app, set it as a module option in `nuxt.config.ts`:

```ts
export default defineNuxtConfig({
  shopware: {
    cacheableReads: true, // route anonymous Store API reads through cacheable GET routes
  },
});
```

The flag is read from the public runtime config, so it is available on both server and client. For a non-Nuxt setup, pass it directly to `createShopwareContext`:

```ts
import { createShopwareContext } from "@shopware/composables";

const shopware = createShopwareContext(app, {
  cacheableReads: true,
});
app.use(shopware);
```

Inside a composable the flag is read from the Shopware context and used to branch the request:

```ts
import { encodeForQuery } from "@shopware/api-client/helpers";

const { apiClient, cacheableReads } = useShopwareContext();

const result = cacheableReads
  ? await apiClient.invoke("readCountryGet get /country", {
      query: { _criteria: encodeForQuery(criteria) },
    })
  : await apiClient.invoke("readCountry post /country", {
      body: criteria,
    });
```

### Which reads switch to GET

Exactly these composables gain a GET branch when `cacheableReads` is enabled:

* `useNavigation`
* `useNavigationSearch` (`resolvePath`)
* `useCountries`
* `useUser` (`loadCountry` + `loadSalutation`)
* `useSalutations`
* `useInternationalization` (`getAvailableLanguages`)
* `useProductConfigurator`
* `useProductSearch` (single product detail)
* `useCategorySearch.advancedSearch` (category list)

::: tip
The flag is a blanket GET/POST switch per composable, not a runtime authentication check. Even account-related lookups such as `useUser.loadCountry`/`loadSalutation` use GET when the flag is on. "Anonymous" here means the data is public reference or catalog data suitable for shared HTTP caching, not that the code inspects the login state. Whether a response is actually cached, and how it is scoped per user, is governed by the Shopware backend cache rules and your CDN configuration.
:::

### Which reads stay on POST, and why

A few read paths intentionally stay on POST because the generated Store API schema does not type the `_criteria` parameter on their GET route:

* `useListing` (product listing) - always `readProductListing post /product-listing/{categoryId}`
* `useCategorySearch.search` (single category) - always `readCategory post /category/{navigationId}`
* `useLandingSearch` - always `readLandingPage post /landing-page/{landingPageId}`

As those GET schemas gain `_criteria` typing upstream, these reads can migrate too. Product listing is the first: Shopware core [PR #17204](https://github.com/shopware/shopware/pull/17204) declared `_criteria` on `GET /store-api/product-listing` (released in 6.7.12.0), so `useListing` can switch to the cacheable GET variant once the Store API types are regenerated against that schema.

Write and auth/context mutations (login, register, logout, `readCustomer`, `updateContext`, checkout) also stay on POST/PATCH regardless of the flag, because they are mutations and are not cacheable by design.

### How the criteria is encoded

`encodeForQuery` is a deterministic, pure function: it serializes the object with `JSON.stringify`, gzips it (via `fflate`), then base64url-encodes the result (no `+`, `/`, or `=`), producing a URL-safe value.

```ts
import { encodeForQuery } from "@shopware/api-client/helpers";

const criteria = { associations: { states: {} } };
const encoded = encodeForQuery(criteria); // gzip + base64url string, safe in a URL / cache key
```

Because it is deterministic, identical criteria produce an identical `_criteria` value and therefore an identical URL. That stable URL is what lets a CDN or browser register a cache hit. Object key order matters: "identical criteria" means an identical serialization, not merely a semantically equal object.

## Render layer: route rules (ISR, SWR, headers)

Shopware Frontends configures page-level HTTP caching declaratively through Nuxt's [`routeRules`](https://nuxt.com/docs/api/nuxt-config#routerules), not through Nitro's handler-level cache APIs (`defineCachedEventHandler` / `cachedFunction` are not used in the templates). The keys are glob patterns: exact paths (`/`), prefix wildcards (`/account/**`), and extension globs (`/**/*.svg`). Nuxt merges all matching rules, with more specific patterns taking precedence.

### `isr` - Incremental Static Regeneration

`isr: <seconds>` serves a cached static HTML response and revalidates it after the given window with stale-while-revalidate semantics. This is the primary strategy for storefront and catalog pages, which change infrequently relative to how often they are requested.

The `vue-demo-store` template uses a 24-hour window on the homepage and the catch-all:

```ts
routeRules: {
  "/": {
    isr: 60 * 60 * 24, // 86400s = 24h
  },
  "/checkout": {
    ssr: false,
    headers: {
      "Cache-Control": "no-cache, no-store, must-revalidate",
    },
  },
  "/checkout/**": { ssr: false },
  "/login": { ssr: false },
  "/register": { ssr: false },
  "/reset-password": { ssr: false },
  "/wishlist": { ssr: false },
  "/account": { ssr: false },
  "/account/**": { ssr: false },
  "/search": { ssr: false },
  "/search/**": { ssr: false },
  "/**": {
    isr: 60 * 60 * 24, // catch-all 24h ISR
  },
}
```

The `vue-starter-template` uses a shorter 60-minute window. The source comment captures the trade-off: increase it for mostly-static storefronts, decrease it for frequently updated content.

```ts
routeRules: {
  "/**": {
    // 60-minute ISR - increase for mostly-static storefronts, decrease for frequently updated content
    isr: 60 * 60, // 3600s
  },
  "/**/*.svg": {
    headers: {
      "Cache-Control": "public, max-age=31536000, immutable", // 1 year
    },
  },
  "/checkout": {
    ssr: false,
    headers: {
      "Cache-Control": "no-cache, no-store, must-revalidate",
    },
  },
  "/checkout/**": { ssr: false },
  "/account": { ssr: false },
  "/account/**": { ssr: false },
  "/wishlist": { ssr: false },
}
```

`vue-starter-template-extended` extends `../vue-starter-template` and defines no `routeRules` of its own, so it inherits the parent's caching. Nuxt layer extends merges parent route rules, so changes in the parent propagate to the child. `vue-blank` defines no `routeRules`, so default Nitro behavior (full SSR, no ISR) applies.

::: warning
ISR is only active in production builds and requires a runtime that can store and regenerate the cache (a Node server, Vercel, Netlify, or another Nitro-compatible host). Routes with `ssr: false` are client-rendered per request and are not ISR-cached. Exact stale-while-revalidate timing depends on the deployment target.
:::

### `swr` and `prerender`

`swr` (stale-while-revalidate without the static-build step) and `prerender` (generate the page at build time) are standard Nuxt route-rule modes documented under [Hybrid Rendering](https://nuxt.com/docs/guide/concepts/rendering#hybrid-rendering). The Shopware Frontends templates do not ship a `prerender` or `swr` configuration - they default to ISR for cacheable routes - but both are available if your content profile suits them. To enable prerendering, add a `nitro.prerender` block or a `routeRules` entry with `prerender: true`.

### `headers` - per-route `Cache-Control`

Route rules can set HTTP `Cache-Control` directly. The templates use it two ways:

```ts
// Prevent any caching on sensitive routes
"/checkout": {
  ssr: false,
  headers: {
    "Cache-Control": "no-cache, no-store, must-revalidate",
  },
},
// Long-lived, immutable caching for static SVG assets
"/**/*.svg": {
  headers: {
    "Cache-Control": "public, max-age=31536000, immutable",
  },
},
```

`max-age=31536000` is one year; `immutable` tells clients never to revalidate, which is safe only for versioned/hashed or otherwise stable assets. Note the SVG rule exists in `vue-starter-template` (and its extended child) but not in `vue-demo-store`.

### Nitro cache storage

The templates do not customize Nitro's cache storage. `vue-demo-store`'s only `nitro` option is `compressPublicAssets: true`; `vue-starter-template` has no `nitro` block at all. The default Nitro cache driver is used (in-memory in dev, host-dependent in production). For multi-instance deployments, configuring a centralized store (Redis, etc.) via `nitro.storage` is recommended platform guidance.

## Rendering modes and the CSR fallback

The render layer pairs ISR (cacheable, server-rendered pages) with `ssr: false` (client-side rendering) for user-dynamic routes. Setting `ssr: false` disables server rendering for a route and ships an HTML shell that hydrates on the client - used in the templates for `/checkout`, `/account`, `/login`, `/register`, `/wishlist`, and `/search`, so personalized data is never baked into cacheable HTML.

These rendering modes (universal SSR, client-side, ISR, and the static/SPA options) are covered in depth in [Deployment](/best-practices/deployment.html); refer to that page for the full hosting and rendering-strategy discussion rather than re-deriving it here.

::: info
`experimental.payloadExtraction` is explicitly set to `false` in all three templates, keeping data serialization under explicit control via `useAsyncData` rather than relying on extracted payload files.
:::

## Backend HTTP cache and reverse proxy

The frontend layers stop at producing cacheable requests. Whether a GET response is actually stored, for how long, and with what cache key is decided by the Shopware backend HTTP cache and your reverse proxy (Varnish self-hosted, or Fastly on Shopware Cloud).

This is where `cacheableReads` pays off. By switching reads to GET with a deterministic `_criteria` URL, the request layer produces cacheable requests; the backend reverse proxy then applies `Cache-Control`, cache tags, `sw-cache-hash`, and invalidation. None of that is handled by the frontend `@shopware/api-client` - it only forwards Shopware Store API headers (`sw-access-key`, `sw-context-token`, `sw-language-id`, and so on) and refreshes the context token from non-public response headers. It reads `Cache-Control` only to ignore `sw-context-token` on publicly cacheable responses; it does not set `Cache-Control` or handle cache tags or `sw-cache-hash`.

When a route is cacheable, Shopware marks it with the `_httpCache` route attribute and the `CacheResponseSubscriber` emits a public `Cache-Control` header (the documented default for cacheable Store API routes is `public, max-age=0, s-maxage=1800, stale-while-revalidate=86400, stale-if-error=7200`; non-cacheable routes get `no-cache, private`). Cache entries are scoped per context: the backend sets `sw-language-id`, `sw-currency-id`, and `sw-context-hash` response headers and adds them to `Vary`, so a reverse proxy or CDN stores separate entries per language, currency, and login/rule state. Invalidation reuses Shopware's existing cache tags. See the [HTTP cache concept](https://developer.shopware.com/docs/concepts/framework/http_cache.html) and the [Store API cache strategy](https://developer.shopware.com/docs/resources/references/adr/2025-09-15-store-api-cache-strategy.html) for the full model.

A few consequences follow from how the backend cache works:

* A request carrying an active `sw-context-token` (cart/session) is typically treated as non-cacheable by the backend. This is standard HTTP-cache behavior, and it is one reason personalized routes use `ssr: false`.
* If the backend responds with `no-store`/`no-cache`, nothing is cached regardless of using GET.
* Enabling `cacheableReads` without a backend that supports the GET read routes and the `_criteria` parameter yields no caching benefit (the calls still succeed, they just are not cached).

To configure the backend cache, follow the [Shopware reverse HTTP cache guide](https://developer.shopware.com/docs/guides/hosting/infrastructure/reverse-http-cache.html). The `_criteria` GET support is tracked in [Shopware issue #12388](https://github.com/shopware/shopware/issues/12388), referenced directly in the `encodeForQuery` source.

## Client state caching

Beyond HTTP, the storefront avoids redundant work by sharing in-memory state across the component tree. This is not a response cache keyed by request; it is shared reactive state that survives navigation but resets on a full page reload.

* **Shared composables.** `useCart`, `usePrice`, and `useProductSearchListing` are wrapped with VueUse's `createSharedComposable()`, so a single instance is reused across the app on the client. During SSR it automatically falls back to per-request (non-shared) mode to avoid cross-request state pollution.
* **Session, cart, user, listings.** State is held in shared refs under named injection keys (`swSessionContext`, `swCart`, `customer`, `swNavigation-${type}`, listing keys) via a `useContext` helper built on VueUse's `provideLocal`/`injectLocal`. Mutations reassign the shared ref so every consumer sees consistent state without refetching.
* **Single API client.** One Store API client is created per app and provided via `provide`/`inject`, so all composables share its `defaultHeaders` - including the `sw-context-token` it captures from non-public (private or uncached) response headers and reuses on subsequent requests. Tokens on `Cache-Control: public` responses are ignored, so a CDN hit cannot overwrite a logged-in session with a stale guest token.
* **Navigation reuse.** Navigation results are fetched once with `useAsyncData` (with stable keys for deduplication and hydration-payload serialization) and shared down the tree with `provide`/`inject` rather than refetched after hydration.

A couple of pieces of client state are also persisted durably outside memory: the `sw-context-token` is written to a cookie by the Nuxt plugin (so the session survives reloads and SSR), and `useLocalWishlist` persists wishlist ids to `localStorage`.

## Asset and image caching

Static assets and images get their own caching treatment.

* **SVGs and static assets** are served with the long-lived immutable `Cache-Control` header shown above (route rule `/**/*.svg`), so clients never revalidate them.
* **Images** are optimized through a custom Shopware `@nuxt/image` provider that maps `width`/`height`/`quality`/`format`/`fit` modifiers to CDN query parameters, plus named presets (`productCard`, `productDetail`, `hero`, `thumbnail`). When pre-generated Shopware thumbnails are available, helpers such as `getSrcSetForMedia` build a responsive `srcset` from them.

Image transforms only take effect when the backend supports remote/on-the-fly thumbnail generation (Fastly on Shopware Cloud, or self-hosted middleware such as Thumbor or imgproxy); otherwise the query parameters are ignored and the original image is served. For the full image workflow - providers, presets, thumbnails, srcset, and responsive sizing - see [Images](/best-practices/images.html).

## External resources

* [Nuxt: Rendering Modes](https://nuxt.com/docs/guide/concepts/rendering)
* [Nuxt: Hybrid Rendering / Route Rules](https://nuxt.com/docs/guide/concepts/rendering#hybrid-rendering)
* [Nuxt: `routeRules` config reference](https://nuxt.com/docs/api/nuxt-config#routerules)
* [Nuxt: `useAsyncData`](https://nuxt.com/docs/api/composables/use-async-data)
* [Nuxt: `useState`](https://nuxt.com/docs/api/composables/use-state)
* [Nitro: Cache guide](https://nitro.build/guide/cache)
* [Nitro: Deployment Presets](https://nitro.build/deploy)
* [MDN: `Cache-Control` HTTP header](https://developer.mozilla.org/en-US/docs/Web/HTTP/Reference/Headers/Cache-Control)
* [MDN: HTTP caching](https://developer.mozilla.org/en-US/docs/Web/HTTP/Caching)
* [Shopware ADR: Store API caching strategy (GET over POST, `_criteria`)](https://developer.shopware.com/docs/resources/references/adr/2025-09-15-store-api-cache-strategy.html)
* [Shopware ADR: Improved HTTP cache layer](https://developer.shopware.com/docs/resources/references/adr/2025-11-03-improved-http-cache-layer.html)
* [Shopware: HTTP cache concept](https://developer.shopware.com/docs/concepts/framework/http_cache.html)
* [Shopware: Reverse HTTP cache (Varnish / reverse proxy)](https://developer.shopware.com/docs/guides/hosting/infrastructure/reverse-http-cache.html)
* [Shopware: Caches (hosting / performance)](https://developer.shopware.com/docs/guides/hosting/performance/caches.html)
* [Shopware: Store API concepts](https://developer.shopware.com/docs/concepts/api/store-api.html)
* [Shopware: Remote thumbnail generation](https://developer.shopware.com/docs/guides/plugins/plugins/content/media/remote-thumbnail-generation.html)
* [Shopware issue #12388: `_criteria` GET query parameter](https://github.com/shopware/shopware/issues/12388)
* [Shopware PR #17204: declare `_criteria` on `GET /store-api/product-listing`](https://github.com/shopware/shopware/pull/17204)
* [VueUse: `createSharedComposable`](https://vueuse.org/shared/createSharedComposable/)
* [VueUse: `createInjectionState`](https://vueuse.org/shared/createInjectionState/)
* [Vue 3: Provide / Inject](https://vuejs.org/guide/components/provide-inject.html)
* [fflate (gzip used by `encodeForQuery`)](https://github.com/101arrowz/fflate)

---

---
url: /docs/resources/references/adr/2025-09-15-store-api-cache-strategy.md
---

# Caching Strategy for Store API

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2025-09-15-store-api-cache-strategy.md)
:::

## Context

Store API performance is critical for all headless installations. Currently, Store API responses are not
cached by default, which leads to unnecessary server load and reduced performance for end users.

At the same time, Storefront (classical Shopware frontend based on twig templates, mentioned here and further in
this doc only for context and strategy alignment) already has a caching mechanism in place and Shopware provides
a reference configuration for reverse proxies like Varnish, that supports Storefront caching.

The goal is to introduce a caching strategy for Store API, while reusing existing approaches and keeping required changes
on the client and infrastructure side to a minimum.

Important details:

* Store API response may differ by context (e.g. logged in customer, currency, language, active rules, etc).
* Storefront uses cookies to track differences in the contexts.
* Storefront marks cacheable routes via the `'_httpCache' => true` route defaults attribute. If this attribute is
  present (and other conditions are met), `CacheResponseSubscriber` adds `Cache-Control: public, s-maxage=7200` header
  to the response (TTL is controlled via configuration).
* Storefront's `Cache-Control` header is prepared for reverse-proxy (only when reverse proxy is enabled
  in the configuration). Client-side caching remains `no-cache, private` as we lack the ability to invalidate client
  caches, unlike reverse proxies.
* Storefront caches may be invalidated via cache tags (x-tag in Varnish).
* Several non-mutating Store API endpoints that return non-sensitive data use `POST` to support larger payloads
  (see Criteria object). Some of them already support both `POST` and `GET`.
* `RequestCriteriaBuilder` supports building Criteria from separate query parameters for `GET`
  requests (`filter`, `grouping`, `fields`, `page`, `limit`, etc). Criteria as a separate parameters leads
  to a more complex OpenAPI schema. Also differences between standard and php array query parameters serialization
  makes clients implementation more complex (`colors[]=red&colors[]=blue` vs `colors=red,blue`).

## Decision

1. HTTP methods
   * Prefer `GET` for non-mutating endpoints returning non-sensitive data.
   * For endpoints that currently use `POST` but are non-mutating and return non-sensitive data, add `GET` support
     (of fully transition to `GET` if possible).
2. Criteria in query parameters
   * Introduce `_criteria` parameter to support passing Criteria in `GET` requests as a single query parameter.
   * Format: JSON -> gzip -> base64url (url-safe Base64) of the Criteria object.
   * Provide SDK helpers for encoding/decoding and canonicalization (stable key ordering, normalized arrays) to improve
     cache hit ratio across clients.
   * Introduce phaseout plan for separate criteria parameters (e.g. `filter`, `grouping`, `fields`, `page`, `limit`, etc).
3. Use cache headers (not cookies) to differentiate contexts on Store API
   * Use `sw-currency-id` and `sw-language-id` to differentiate currency and language. Shopware must update currency and
     language ids in the context of the current request based on these headers.
   * Use `sw-context-hash` to differentiate other context aspects (e.g. logged in customer, active rules, etc). Use the
     same algorithm as for storefront context hash cookie.
   * All three headers must be returned in the Store API responses. If clients want to utilize caching, they should
     send these headers in subsequent requests. When client sends these headers, reverse proxy uses them to detect
     the cache bucket. Additionally, the language and currency headers change the currency and language in the response.
   * `Vary` header should include all three headers, so reverse proxies and CDNs can differentiate cache entries.
4. Mark cacheable routes
   * Use `'_httpCache'` route default attribute to mark cacheable Store API routes.
   * Extend `CacheResponseSubscriber` to add `Cache-Control` header to Store API responses similar
     to Storefront responses, but ignoring cookies (relying on headers + `Vary` instead). Default `Cache-Control`
     value for cacheable routes should be `public, max-age=0, s-maxage=1800, stale-while-revalidate=86400, stale-if-error=7200`,
     non-cacheable `no-cache, private`
5. Invalidation strategy
   * Reuse existing cache tags implementation to invalidate cached Store API responses.

## Consequences

* SDK updates
  * Switch relevant endpoints to GET where safe
  * Add support for `_criteria` parameter (encoding, decoding, canonicalization)
  * Implement automatic request method selection (fallback to POST when the compressed \_criteria would exceed practical
    URL limits).
  * Track and resend `sw-currency-id`, `sw-language-id`, and `sw-context-hash` headers on subsequent requests.
* Clients
  * No changes required if caching is not desired.
  * To utilize caching, clients should adopt the updated SDK or implement the same strategy.
  * Client should beware that `sw-currency-id`, `sw-language-id` can change the response language and currency.
* Extensions
  * Custom Store API endpoints can opt into caching using the same route flags.
* Trade-offs
  * Using compressed `_criteria` reduces request readability and makes debugging and logging harder.
  * Without canonicalization, compressed `_criteria` parameter may lead to a decreased cache hit ratio.
  * Operators may need minor reverse-proxy adjustments, depending on the level of customization.

## Considered alternatives

1. Keep using cookies for context differentiation similarly to Storefront:
   * Less explicit for the clients, cache can be used unintentionally.
   * More complex configuration for reverse proxies (e.g. Varnish).
   * No need to change the client implementation.
     Rejected in favor of explicit request headers.

2. Cache POST requests with big payloads if possible:
   * Not aligned with HTTP semantics (POST is not cacheable by default).
   * More complex configuration for reverse proxies and CDNs.
   * Not transparent for the clients that caching is used.
   * Transparent request - easier logging and debugging.
     Rejected in favor of alignment with HTTP semantics and minimal changes on infra side were preferred.

3. Two-step flow: POST returns a request hash; GET retrieves cached data by hash:
   * More complex implementation for clients (changed workflow).
   * More complex implementation for Shopware (need to store request hashes and map them to actual requests).
   * Additional round-trip for the requests.
   * Transparent request - easier to debug and log.
     Rejected in favor of simplicity of implementation, limited number of requests and minimal changes on clients side.

4. Use “plain” structured query parameters (filter\[...]\[]=...)
   * Can hit url length limits more easily.
   * More complex OpenAPI schema, problem with array format differences between clients persists.
   * Transparent request - easier to debug and log.
     Rejected in favor of more compact representation and simpler OpenAPI schema.

---

---
url: /docs/resources/references/config-reference/server/caddy.md
---
# Caddy

```text
mydomain.com {
  header {
    X-Frame-Options DENY
    Referrer-Policy no-referrer-when-downgrade
  }

  @svg {
    file
    path *.svg
  }

  header @svg Content-Security-Policy "script-src 'none'"

  @default {
    not path /theme/* /media/* /thumbnail/* /bundles/* /css/* /fonts/* /js/* /recovery/* /sitemap/*
  }

  root * public
  php_fastcgi 127.0.0.1:9000
  encode zstd gzip
  file_server
}
```

---

---
url: /docs/v6.6/resources/references/config-reference/server/caddy.md
---
# Caddy

```text
mydomain.com {
  header {
    X-Frame-Options DENY
    Referrer-Policy no-referrer-when-downgrade
  }

  @svg {
    file
    path *.svg
  }

  header @svg Content-Security-Policy "script-src 'none'"

  @default {
    not path /theme/* /media/* /thumbnail/* /bundles/* /css/* /fonts/* /js/* /recovery/* /sitemap/*
  }

  root * public
  php_fastcgi 127.0.0.1:9000
  encode zstd gzip
  file_server
}
```

---

---
url: /docs/concepts/commerce/checkout-concept/cart.md
---

# Cart

Shopping cart management is a central feature of Shopware 6. The shopping cart resides in the checkout bundle and is a central part of the checkout process.

## Design goals

The cart was designed with a few design goals in mind.

### Adaptability

Although many services exist to make working with the cart simple and intuitive, the cart itself can be changed through various processes and adapt to numerous use cases.

### Performance

The cart is designed by identifying key processes and optimizing upon them. Therefore the amount of calculations, queries, and iterations are kept to a minimum, and a clear state management is implemented.

### Abstraction

The cart has very few hard dependencies on other core entities in Shopware 6. Entities such as products, surcharges, or discounts are referenced through interfaces that the line items in the cart reference.

## Cart Struct

`\Shopware\Core\Checkout\Cart\Cart`

An instance of this class represents one single cart. As shown in the diagram below, relations to central Entities of the system are omitted. This allows Shopware 6 to manage multiple carts per user, per sales channel, or across all sales channels. The only identification is a token hash.

![Representation of the cart struct](../../../assets/commerce-checkout-cartStruct.svg)

This highly mutable data structure is acted upon from requests and calculated and validated through services. It contains:

### Line Items

A line item represents an order position.

* It may be a  shippable good, a download article, or even a bundle of many products.
* Line items contain properties that tell the cart how to handle changes in line items. E.g., *stackable* - quantity can be changed, *removable* - removable through the API, and so on.
* A line item is the main extension point for the cart process. Therefore a promotion, a discount, or a surcharge is also a line item.
* A line item can even contain other line items. So a single order position can be the composition of multiple single line items.

### Transaction

It is the payment in the cart. Contains a payment handler and the amount.

### Delivery

It is a shipment in the cart. It contains a date, a method, a target location, and the line items that should be shipped together.

### Error

Validation errors which prevent ordering from that cart.

### Tax

The calculated tax rate for the cart.

### Price

The price of all line items, including tax, delivery costs, voucher discounts, and surcharges.

## State

Shopware 6 manages the cart's state through different services. The diagram below illustrates the different states the cart can have and the state changes it can go through.

```mermaid
---
title: Cart State
---
stateDiagram-v2
    [*] --> Empty
    Empty --> Dirty : add line item
    Dirty --> Calculated : calculate
    Calculated --> Dirty : modify line item/shipping/payment
    Calculated --> Calculated : order invalid
    Calculated --> [*] : order
```

| Cart state | Description|
|------|------------|
| Empty | A cart with no items will have default shipping and payment settings. |
| Dirty | On adding a new line item, the cart undergoes modifications with invalid prices, raw line items, and uncertain delivery validity. Consequently, calculations are necessary.|
| Calculated | After accurate calculations, the cart can be either submitted as an order or may contain errors that need to be addressed. |

## Calculation

Calculating a cart is one of the more costly operations an ecommerce system must support. Therefore the interfaces of the cart are designed as precise and as quick as possible. The calculation is a multi-stage process that revolves around the mutation of the data structure of the cart struct shown in the diagram below:

```mermaid
---
title: Cart Calculation
---
stateDiagram-v2
    [*] --> Enrich
    Enrich --> Process
    Process --> Validate
    Validate --> Validate : repeat until no changes occur
    Validate --> Persist
    Persist --> [*]
```

| Cart calculation state | Description|
|------|------------|
| Enrich | The calculation process in the **enrich state** for line items involves adding images, its descriptions and determining prices |
| Process | During the **process state**, price updates occur, adjustments to shipping and payment are made|
| Validate | In the **validate state**, validation is performed using the rule system and cart changes based on plausibility checks. |
| Persist | The **persist state** is responsible for updating the storage. |

### Cart enrichment

Enrichment secures the *Independence\_ and \_Adaptability* of Shopware 6. As shown in the below code snippet, the cart can create and contain line items that are initially empty and will only be loaded (enriched) during the calculation.

```php
<?php

use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Cart\LineItem\LineItem;

$lineItem = new LineItem(/* ... */);
/** @var $cart Cart */
$cart->getLineItems()->add($lineItem);

$lineItem->getPrice(); // is now null
// enrich the cart
$lineItem->getPrice(); // now set up
```

This process is transparently controlled from the cart but executed through implementations of `\Shopware\Core\Checkout\Cart\CartDataCollectorInterface`. This interface is cut in order to reduce the number of database calls necessary to set up the cart's data structure for **price calculation** and **inspection** (meaning: rendering in a storefront, reading from the API).

A default set of collectors is implemented in Shopware 6, which has a set call order shown in the diagram below.

| Service ID | Task |
| :--- | :--- |
| Shopware\Core\Content\Product\Cart\ProductCartProcessor | Enrich all referenced products |
| Shopware\Core\Checkout\Promotion\Cart\CartPromotionsCollector | Enrich add, remove and validate promotions |
| Shopware\Core\Checkout\Shipping\Cart\ShippingMethodPriceCollector | Handle shipping prices |

```mermaid
---
title: Enrichment
---
sequenceDiagram
Enrichment->>Enrichment :
box
    participant Enrichment
    participant ProductCartProcessor
    participant CartPromotionsCollector
    participant CartDiscountCollector
    end
    Note over Enrichment,CartDiscountCollector: Collect
    Enrichment->>ProductCartProcessor: collect
    Enrichment->>CartPromotionsCollector: collect
    Enrichment->>CartDiscountCollector: collect
    Note over Enrichment,CartDiscountCollector: Enrichment
    Enrichment->>ProductCartProcessor: enrich
    Enrichment->>CartPromotionsCollector: enrich
    Enrichment->>CartDiscountCollector: enrich
    Enrichment->>Enrichment :
```

## Cart processors - price calculation and validation

After a cart is enriched, the cart is processed. The price information for all individual `LineItems` is now set up to calculate the sums. This happens in the `\Shopware\Core\Checkout\Cart\Processor` class, following these steps:

* The `lineItem` prices are calculated by applying the quantity and the tax rate.
* Deliveries are set up and cost calculated.
* Different cart values are summed up (incl, excl. vat, inc. excl. shipping).

Then the calculation of prices is done, and the cart can be inspected from the rule system.

## Context rules

After the cart has been processed, it is validated against the rules, which can lead to a change in the carts' data, so a revalidation becomes necessary. We can envision a scenario where we sell cars and have the following rules:

* Everybody buying a car gets a pair of sunglasses for free.
* Every cart containing two products gets a discount of 2%.

```mermaid
stateDiagram-v2
    [*] --> Empty_cart : checkout started
    Empty_cart --> Enrichment : User orders a car
        state Enrichment {
    Cart_with_lineitem(car) --> Cart_with_lineitem(car+sunglasses) : Iteration 1 - Cart automatically adds sunglasses
    Cart_with_lineitem(car+sunglasses) --> Cart_with_lineitem(car+sunglasses+2%discount) : Iteration 2 - Cart automatically adds discount
    }
    Cart_with_lineitem(car+sunglasses+2%discount) --> [*] : valid
```

As you can see in the diagram above, the cart is modified during the enrichment process. The sunglasses are added in the first iteration, and in the second iteration, the discount is added as the cart contains two products. This results in the expected state of one car, one pair of sunglasses, and a two-percent discount.

## Cart storage

Contrary to other entities in the system, the cart is not managed through the [Data Abstraction Layer](./../../../concepts/framework/data-abstraction-layer)(DAL). The cart can only be written and retrieved as a whole. As discussed in the sections, the workload of Shopware 6 can only be performed on the whole object in memory.

## Cart control

The state changes and cart mutation is handled automatically by a facade the `\Shopware\Core\Checkout\Cart\SalesChannel\CartService`. It controls, sets up, and modifies the cart struct.

---

---
url: /docs/guides/plugins/plugins/checkout/cart.md
---

# Cart

Cart core functions as a plugin in Shopware include adding products to the cart, displaying cart contents, adding discounts to line items, updating cart items, adding custom prices to line items, applying tax rates, proceeding to checkout, persisting cart data, integrating with the checkout process, and validating the cart. While these functions are typically available within the Shopware core system, plugins can enhance and customize them according to specific business requirements or customer preferences.

---

---
url: /docs/v6.5/concepts/commerce/checkout-concept/cart.md
---

# Cart

Shopping cart management is a central feature of Shopware 6. The shopping cart resides in the checkout bundle and is a central part of the checkout process.

## Design goals

The cart was designed with a few design goals in mind.

### Adaptability

Although many services exist to make working with the cart simple and intuitive, the cart itself can be changed through various processes and adapt to numerous use cases.

### Performance

The cart is designed by identifying key processes and optimizing upon them. Therefore the amount of calculations, queries, and iterations are kept to a minimum, and a clear state management is implemented.

### Abstraction

The cart has very few hard dependencies on other core entities in Shopware 6. Entities such as products, surcharges, or discounts are referenced through interfaces that the line items in the cart reference.

## Cart Struct

`\Shopware\Core\Checkout\Cart\Cart`

An instance of this class represents one single cart. As shown in the diagram below, relations to central Entities of the system are omitted. This allows Shopware 6 to manage multiple carts per user, per sales channel, or across all sales channels. The only identification is a token hash.

![Representation of the cart struct](../../../assets/commerce-checkout-cartStruct.svg)

This highly mutable data structure is acted upon from requests and calculated and validated through services. It contains:

### Line Items

A line item represents an order position.

* It may be a  shippable good, a download article, or even a bundle of many products.
* Line items contain properties that tell the cart how to handle changes in line items. E.g., *stackable* - quantity can be changed, *removable* - removable through the API, and so on.
* A line item is the main extension point for the cart process. Therefore a promotion, a discount, or a surcharge is also a line item.
* A line item can even contain other line items. So a single order position can be the composition of multiple single line items.

### Transaction

It is the payment in the cart. Contains a payment handler and the amount.

### Delivery

It is a shipment in the cart. It contains a date, a method, a target location, and the line items that should be shipped together.

### Error

Validation errors which prevent ordering from that cart.

### Tax

The calculated tax rate for the cart.

### Price

The price of all line items, including tax, delivery costs, voucher discounts, and surcharges.

## State

Shopware 6 manages the cart's state through different services. The diagram below illustrates the different states the cart can have and the state changes it can go through.

```mermaid
---
title: Cart State
---
stateDiagram-v2
    [*] --> Empty
    Empty --> Dirty : add line item
    Dirty --> Calculated : calculate
    Calculated --> Dirty : modify line item/shipping/payment
    Calculated --> Calculated : order invalid
    Calculated --> [*] : order
```

| Cart state | Description|
|------|------------|
| Empty | A cart with no items will have default shipping and payment settings. |
| Dirty | On adding a new line item, the cart undergoes modifications with invalid prices, raw line items, and uncertain delivery validity. Consequently, calculations are necessary.|
| Calculated | After accurate calculations, the cart can be either submitted as an order or may contain errors that need to be addressed. |

## Calculation

Calculating a cart is one of the more costly operations an ecommerce system must support. Therefore the interfaces of the cart are designed as precise and as quick as possible. The calculation is a multi-stage process that revolves around the mutation of the data structure of the cart struct shown in the diagram below:

```mermaid
---
title: Cart Calculation
---
stateDiagram-v2
    [*] --> Enrich
    Enrich --> Process
    Process --> Validate
    Validate --> Validate : repeat until no changes occur
    Validate --> Persist
    Persist --> [*]
```

| Cart calculation state | Description|
|------|------------|
| Enrich | The calculation process in the **enrich state** for line items involves adding images, its descriptions and determining prices |
| Process | During the **process state**, price updates occur, adjustments to shipping and payment are made|
| Validate | In the **validate state**, validation is performed using the rule system and cart changes based on plausibility checks. |
| Persist | The **persist state** is responsible for updating the storage. |

### Cart enrichment

Enrichment secures the *Independence\_ and \_Adaptability* of Shopware 6. As shown in the below code snippet, the cart can create and contain line items that are initially empty and will only be loaded (enriched) during the calculation.

```php
<?php 

use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Cart\LineItem\LineItem;

$lineItem = new LineItem(/* ... */);
/** @var $cart Cart */
$cart->getLineItems()->add($lineItem);

$lineItem->getPrice(); // is now null
// enrich the cart
$lineItem->getPrice(); // now set up
```

This process is transparently controlled from the cart but executed through implementations of `\Shopware\Core\Checkout\Cart\CartDataCollectorInterface`. This interface is cut in order to reduce the number of database calls necessary to set up the cart's data structure for **price calculation** and **inspection** (meaning: rendering in a storefront, reading from the API).

A default set of collectors is implemented in Shopware 6, which has a set call order shown in the diagram below.

| Service ID | Task |
| :--- | :--- |
| Shopware\Core\Content\Product\Cart\ProductCartProcessor | Enrich all referenced products |
| Shopware\Core\Checkout\Promotion\Cart\CartPromotionsCollector | Enrich add, remove and validate promotions |
| Shopware\Core\Checkout\Shipping\Cart\ShippingMethodPriceCollector | Handle shipping prices |

```mermaid
---
title: Enrichment
---
sequenceDiagram
Enrichment->>Enrichment : 
box
    participant Enrichment
    participant ProductCartProcessor
    participant CartPromotionsCollector
    participant CartDiscountCollector
    end
    Note over Enrichment,CartDiscountCollector: Collect
    Enrichment->>ProductCartProcessor: collect
    Enrichment->>CartPromotionsCollector: collect
    Enrichment->>CartDiscountCollector: collect
    Note over Enrichment,CartDiscountCollector: Enrichment
    Enrichment->>ProductCartProcessor: enrich
    Enrichment->>CartPromotionsCollector: enrich
    Enrichment->>CartDiscountCollector: enrich
    Enrichment->>Enrichment : 
```

## Cart processors - price calculation and validation

After a cart is enriched, the cart is processed. The price information for all individual `LineItems` is now set up to calculate the sums. This happens in the `\Shopware\Core\Checkout\Cart\Processor` class, following these steps:

* The `lineItem` prices are calculated by applying the quantity and the tax rate.
* Deliveries are set up and cost calculated.
* Different cart values are summed up (incl, excl. vat, inc. excl. shipping).

Then the calculation of prices is done, and the cart can be inspected from the rule system.

## Context rules

After the cart has been processed, it is validated against the rules, which can lead to a change in the carts' data, so a revalidation becomes necessary. We can envision a scenario where we sell cars and have the following rules:

* Everybody buying a car gets a pair of sunglasses for free.
* Every cart containing two products gets a discount of 2%.

```mermaid
stateDiagram-v2
    [*] --> Empty_cart : checkout started
    Empty_cart --> Enrichment : User orders a car
        state Enrichment {
    Cart_with_lineitem(car) --> Cart_with_lineitem(car+sunglasses) : Iteration 1 - Cart automatically adds sunglasses
    Cart_with_lineitem(car+sunglasses) --> Cart_with_lineitem(car+sunglasses+2%discount) : Iteration 2 - Cart automatically adds discount
    }
    Cart_with_lineitem(car+sunglasses+2%discount) --> [*] : valid
```

As you can see in the diagram above, the cart is modified during the enrichment process. The sunglasses are added in the first iteration, and in the second iteration, the discount is added as the cart contains two products. This results in the expected state of one car, one pair of sunglasses, and a two-percent discount.

## Cart storage

Contrary to other entities in the system, the cart is not managed through the [Data Abstraction Layer](/docs/concepts/framework/data-abstraction-layer)(DAL). The cart can only be written and retrieved as a whole. As discussed in the sections, the workload of Shopware 6 can only be performed on the whole object in memory.

## Cart control

The state changes and cart mutation is handled automatically by a facade the `\Shopware\Core\Checkout\Cart\SalesChannel\CartService`. It controls, sets up, and modifies the cart struct.

---

---
url: /docs/v6.5/guides/plugins/plugins/checkout/cart.md
---

# Cart

Cart core functions as a plugin in Shopware include adding products to the cart, displaying cart contents, adding discounts to line items, updating cart items, adding custom prices to line items, applying tax rates, proceeding to checkout, persisting cart data, integrating with the checkout process, and validating the cart. While these functions are typically available within the Shopware core system, plugins can enhance and customize them according to specific business requirements or customer preferences.

---

---
url: /docs/v6.6/concepts/commerce/checkout-concept/cart.md
---

# Cart

Shopping cart management is a central feature of Shopware 6. The shopping cart resides in the checkout bundle and is a central part of the checkout process.

## Design goals

The cart was designed with a few design goals in mind.

### Adaptability

Although many services exist to make working with the cart simple and intuitive, the cart itself can be changed through various processes and adapt to numerous use cases.

### Performance

The cart is designed by identifying key processes and optimizing upon them. Therefore the amount of calculations, queries, and iterations are kept to a minimum, and a clear state management is implemented.

### Abstraction

The cart has very few hard dependencies on other core entities in Shopware 6. Entities such as products, surcharges, or discounts are referenced through interfaces that the line items in the cart reference.

## Cart Struct

`\Shopware\Core\Checkout\Cart\Cart`

An instance of this class represents one single cart. As shown in the diagram below, relations to central Entities of the system are omitted. This allows Shopware 6 to manage multiple carts per user, per sales channel, or across all sales channels. The only identification is a token hash.

![Representation of the cart struct](../../../assets/commerce-checkout-cartStruct.svg)

This highly mutable data structure is acted upon from requests and calculated and validated through services. It contains:

### Line Items

A line item represents an order position.

* It may be a  shippable good, a download article, or even a bundle of many products.
* Line items contain properties that tell the cart how to handle changes in line items. E.g., *stackable* - quantity can be changed, *removable* - removable through the API, and so on.
* A line item is the main extension point for the cart process. Therefore a promotion, a discount, or a surcharge is also a line item.
* A line item can even contain other line items. So a single order position can be the composition of multiple single line items.

### Transaction

It is the payment in the cart. Contains a payment handler and the amount.

### Delivery

It is a shipment in the cart. It contains a date, a method, a target location, and the line items that should be shipped together.

### Error

Validation errors which prevent ordering from that cart.

### Tax

The calculated tax rate for the cart.

### Price

The price of all line items, including tax, delivery costs, voucher discounts, and surcharges.

## State

Shopware 6 manages the cart's state through different services. The diagram below illustrates the different states the cart can have and the state changes it can go through.

```mermaid
---
title: Cart State
---
stateDiagram-v2
    [*] --> Empty
    Empty --> Dirty : add line item
    Dirty --> Calculated : calculate
    Calculated --> Dirty : modify line item/shipping/payment
    Calculated --> Calculated : order invalid
    Calculated --> [*] : order
```

| Cart state | Description|
|------|------------|
| Empty | A cart with no items will have default shipping and payment settings. |
| Dirty | On adding a new line item, the cart undergoes modifications with invalid prices, raw line items, and uncertain delivery validity. Consequently, calculations are necessary.|
| Calculated | After accurate calculations, the cart can be either submitted as an order or may contain errors that need to be addressed. |

## Calculation

Calculating a cart is one of the more costly operations an ecommerce system must support. Therefore the interfaces of the cart are designed as precise and as quick as possible. The calculation is a multi-stage process that revolves around the mutation of the data structure of the cart struct shown in the diagram below:

```mermaid
---
title: Cart Calculation
---
stateDiagram-v2
    [*] --> Enrich
    Enrich --> Process
    Process --> Validate
    Validate --> Validate : repeat until no changes occur
    Validate --> Persist
    Persist --> [*]
```

| Cart calculation state | Description|
|------|------------|
| Enrich | The calculation process in the **enrich state** for line items involves adding images, its descriptions and determining prices |
| Process | During the **process state**, price updates occur, adjustments to shipping and payment are made|
| Validate | In the **validate state**, validation is performed using the rule system and cart changes based on plausibility checks. |
| Persist | The **persist state** is responsible for updating the storage. |

### Cart enrichment

Enrichment secures the *Independence\_ and \_Adaptability* of Shopware 6. As shown in the below code snippet, the cart can create and contain line items that are initially empty and will only be loaded (enriched) during the calculation.

```php
<?php 

use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Cart\LineItem\LineItem;

$lineItem = new LineItem(/* ... */);
/** @var $cart Cart */
$cart->getLineItems()->add($lineItem);

$lineItem->getPrice(); // is now null
// enrich the cart
$lineItem->getPrice(); // now set up
```

This process is transparently controlled from the cart but executed through implementations of `\Shopware\Core\Checkout\Cart\CartDataCollectorInterface`. This interface is cut in order to reduce the number of database calls necessary to set up the cart's data structure for **price calculation** and **inspection** (meaning: rendering in a storefront, reading from the API).

A default set of collectors is implemented in Shopware 6, which has a set call order shown in the diagram below.

| Service ID | Task |
| :--- | :--- |
| Shopware\Core\Content\Product\Cart\ProductCartProcessor | Enrich all referenced products |
| Shopware\Core\Checkout\Promotion\Cart\CartPromotionsCollector | Enrich add, remove and validate promotions |
| Shopware\Core\Checkout\Shipping\Cart\ShippingMethodPriceCollector | Handle shipping prices |

```mermaid
---
title: Enrichment
---
sequenceDiagram
Enrichment->>Enrichment : 
box
    participant Enrichment
    participant ProductCartProcessor
    participant CartPromotionsCollector
    participant CartDiscountCollector
    end
    Note over Enrichment,CartDiscountCollector: Collect
    Enrichment->>ProductCartProcessor: collect
    Enrichment->>CartPromotionsCollector: collect
    Enrichment->>CartDiscountCollector: collect
    Note over Enrichment,CartDiscountCollector: Enrichment
    Enrichment->>ProductCartProcessor: enrich
    Enrichment->>CartPromotionsCollector: enrich
    Enrichment->>CartDiscountCollector: enrich
    Enrichment->>Enrichment : 
```

## Cart processors - price calculation and validation

After a cart is enriched, the cart is processed. The price information for all individual `LineItems` is now set up to calculate the sums. This happens in the `\Shopware\Core\Checkout\Cart\Processor` class, following these steps:

* The `lineItem` prices are calculated by applying the quantity and the tax rate.
* Deliveries are set up and cost calculated.
* Different cart values are summed up (incl, excl. vat, inc. excl. shipping).

Then the calculation of prices is done, and the cart can be inspected from the rule system.

## Context rules

After the cart has been processed, it is validated against the rules, which can lead to a change in the carts' data, so a revalidation becomes necessary. We can envision a scenario where we sell cars and have the following rules:

* Everybody buying a car gets a pair of sunglasses for free.
* Every cart containing two products gets a discount of 2%.

```mermaid
stateDiagram-v2
    [*] --> Empty_cart : checkout started
    Empty_cart --> Enrichment : User orders a car
        state Enrichment {
    Cart_with_lineitem(car) --> Cart_with_lineitem(car+sunglasses) : Iteration 1 - Cart automatically adds sunglasses
    Cart_with_lineitem(car+sunglasses) --> Cart_with_lineitem(car+sunglasses+2%discount) : Iteration 2 - Cart automatically adds discount
    }
    Cart_with_lineitem(car+sunglasses+2%discount) --> [*] : valid
```

As you can see in the diagram above, the cart is modified during the enrichment process. The sunglasses are added in the first iteration, and in the second iteration, the discount is added as the cart contains two products. This results in the expected state of one car, one pair of sunglasses, and a two-percent discount.

## Cart storage

Contrary to other entities in the system, the cart is not managed through the [Data Abstraction Layer](/docs/concepts/framework/data-abstraction-layer)(DAL). The cart can only be written and retrieved as a whole. As discussed in the sections, the workload of Shopware 6 can only be performed on the whole object in memory.

## Cart control

The state changes and cart mutation is handled automatically by a facade the `\Shopware\Core\Checkout\Cart\SalesChannel\CartService`. It controls, sets up, and modifies the cart struct.

---

---
url: /docs/v6.6/guides/plugins/plugins/checkout/cart.md
---

# Cart

Cart core functions as a plugin in Shopware include adding products to the cart, displaying cart contents, adding discounts to line items, updating cart items, adding custom prices to line items, applying tax rates, proceeding to checkout, persisting cart data, integrating with the checkout process, and validating the cart. While these functions are typically available within the Shopware core system, plugins can enhance and customize them according to specific business requirements or customer preferences.

---

---
url: /docs/guides/plugins/plugins/architecture/cart-process.md
---

# Cart Extension Architecture

The cart is recalculated multiple times per request to resolve dependencies between line items. Custom extensions must follow strict performance and determinism rules.

## Design principles

* Cart processing is multi-pass and must remain deterministic.
* Data loading must be separated from calculation to ensure stable performance.
* Price logic must be centralized and reusable.

## Extension guidelines

* Use `CartDataCollector` to load external data once.
* Use `CartProcessor` to modify calculated items.
* Never perform database queries in `process()`.
* Always use `PriceCalculator` classes for price adjustments.

## Technical rules

* `CartProcessorInterface::process()` must not execute queries, as it runs multiple times per request.
* The `\Shopware\Core\Checkout\Cart\CartDataCollectorInterface::collect()` method must check whether data was already loaded and append it to `CartDataCollection`. This is to avoid having to execute unnecessarily many queries on the database.
* Line items must be created via a `LineItemFactoryHandler` class.
* All price calculations must use the `Shopware\Core\Checkout\Cart\Price` calculators, which are stored inside the `Shopware\Core\Checkout\Cart\Price` class.
* Cart-related functions must be mapped via corresponding Store API routes in the `Shopware\Core\Checkout\Cart\SalesChannel` namespace.

---

---
url: >-
  /docs/resources/references/app-reference/script-reference/cart-manipulation-script-services-reference.md
---

# Cart Manipulation script services reference

## [services.cart (`Shopware\Core\Checkout\Cart\Facade\CartFacade`)](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/CartFacade.php) {#cartfacade}

The `cart` service allows you to manipulate the cart.
You can use the cart service to add line-items, change prices, add discounts, etc. to the cart.

### calculate()

* The `calculate()` method recalculates the whole cart.

  Use this to get the correct prices after you made changes to the cart.
  Note that after calling the `calculate()` all collections (e.g. items(), products()) get new references,
  so if you still hold references to things inside the cart, these are outdated after calling `calculate()`.

  The `calculate()` method will be called automatically after your cart script executed.

### count()

* `count()` returns the count of line-items in this collection.

  Note that it does only count the line-items directly in this collection and not child line-items of those.
* **Returns** `int`

  The number of line-items in this collection.

### discount()

* The `discount()` methods creates a new discount line-item with the given type and value.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\DiscountFacade`](./cart-manipulation-script-services-reference#discountfacade)

  Returns the newly created discount line-item.

* **Arguments:**
  * *`string`* **key**: The id for the new discount.
  * *`string`* **type**: The type of the discount, e.g. `percentage`, `absolute`
  * *`float|\PriceCollection`* **value**: The value of the discount, a float for percentage discounts or a `PriceCollection` for absolute discounts.
  * *`string`* **label**: The label of the discount line-item.

* **Examples:**
  * Add an absolute discount to the cart.

    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% if services.cart.items.count <= 0 %}
        {% return %}
    {% endif %}

    {% if services.cart.items.has('my-discount') %}
        {% return %}
    {% endif %}

    {% set price = services.cart.price.create({
        'default': { 'gross': -19.99, 'net': -19.99}
    }) %}

    {% do services.cart.discount('my-discount', 'absolute', price, 'Fancy discount') %}
    ```
  * Add a relative discount to the cart.

    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% if services.cart.has('my-discount') %}
        {% return %}
    {% endif %}

    {% do services.cart.discount('my-discount', 'percentage', -10, 'Fancy discount') %}
    ```

### errors()

* The `errors()` method returns the current errors of the cart.

  You can use it to add new errors or warning or to remove existing ones.
* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ErrorsFacade`](./cart-manipulation-script-services-reference#errorsfacade)

  A `ErrorsFacade` containing all cart errors as a collection (may be an empty collection if there are no errors).

### get()

* `get()` returns the line-item with the given id from this collection.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade) | `null`

  The line-item with the given id, or null if it does not exist.

* **Arguments:**
  * *`string`* **id**: The id of the line-item that should be returned.

### has()

* `has()` checks if a line-item with the given id exists in this collection.

* **Returns** `bool`

  Returns true if the given line-item or a line-item with the given id already exists in the collection, false otherwise.

* **Arguments:**
  * *`string|\ItemFacade`* **id**: The id or a line-item that should be checked if it already exists in the collection.

### items()

* The `items()` method returns all line-items of the current cart for further manipulation.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemsFacade`](./cart-manipulation-script-services-reference#itemsfacade)

  A `ItemsFacade` containing all line-items in the current cart as a collection.

### price()

* The `price()` method returns the current price of the cart.

  Note that this price may be outdated, if you changed something inside the cart in your script.
  Use the `calculate()` method to recalculate the cart and update the price.
* **Returns** [`Shopware\Core\Checkout\Cart\Facade\CartPriceFacade`](./cart-manipulation-script-services-reference#cartpricefacade)

  The calculated price of the cart.

### products()

* The `product()` method returns all products of the current cart for further manipulation.

  Similar to the `items()` method, but the line-items are filtered, to only contain product line items.
* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ProductsFacade`](./cart-manipulation-script-services-reference#productsfacade)

  A `ProductsFacade` containing all product line-items in the current cart as a collection.

### remove()

* `remove()` removes the given line-item or the line-item with the given id from this collection.

* **Arguments:**
  * *`string|\ItemFacade`* **id**: The id of the line-item or the line-item that should be removed.

* **Examples:**
  * Add and then remove a product line-item from the cart.

    ```twig
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% do services.cart.products.remove(hook.ids.get('p1')) %}
    ```

### states()

* `states()` allows you to access the state functions of the current cart.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\StatesFacade`](./cart-manipulation-script-services-reference#statesfacade)

  A `StatesFacade` containing all cart states as a collection (maybe an empty collection if there are no states).

### surcharge()

* The `surcharge()` methods creates a new surcharge line-item with the given type and value.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\DiscountFacade`](./cart-manipulation-script-services-reference#discountfacade)

  Returns the newly created surcharge line-item.

* **Arguments:**
  * *`string`* **key**: The id for the new surcharge.
  * *`string`* **type**: The type of the surcharge, e.g. `percentage`, `absolute`
  * *`float|\PriceCollection`* **value**: The value of the surcharge, a float for percentage surcharges or a `PriceCollection` for absolute surcharges.
  * *`string`* **label**: The label of the surcharge line-item.

* **Examples:**
  * Add an absolute surcharge to the cart.#

    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% set price = services.cart.price.create({
        'default': { 'gross': 19.99, 'net': 19.99}
    }) %}

    {% do services.cart.surcharge('my-surcharge', 'absolute', price, 'Fancy surcharge') %}
    ```
  * Add a relative surcharge to the cart.

    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% if services.cart.has('my-surcharge') %}
        {% return %}
    {% endif %}

    {% do services.cart.surcharge('my-surcharge', 'percentage', -10, 'Fancy discount') %}
    ```

***

## [`Shopware\Core\Checkout\Cart\Facade\CartPriceFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/CartPriceFacade.php) {#cartpricefacade}

The CartPriceFacade is a wrapper around the calculated price of a cart.

### create()

* `create()` creates a new `PriceCollection` based on an array of prices.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Pricing\PriceCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Pricing/PriceCollection.php)

  Returns the newly created `PriceCollection`.

* **Arguments:**
  * *`array`* **price**: The prices for the new collection, indexed by the currency-id or iso-code of the currency.

* **Examples:**
  * Create a new Price in the default currency.

    ```twig
    {% set price = services.cart.price.create({
        'default': { 'gross': 19.99, 'net': 19.99}
    }) %}
    ```

### getNet()

* `getNet()` returns the net price of the cart.

* **Returns** `float`

  Returns the net price of the cart as float.

### getPosition()

* `getPosition()` returns the sum price of all line-items in the cart.

  In the position price the shipping costs are excluded.
  Depending on the tax settings this may be the gross or net price og the line-items.
* **Returns** `float`

  The position price as float.

### getRaw()

* \`getRaw() returns the total price of the cart before rounding.

* **Returns** `float`

  The total price before rounding as float.

### getRounded()

* Alias for `getTotal()`.

* **Returns** `float`

  The rounded total price of the cart as float.

### getTotal()

* `getTotal()` returns the total price of the cart that has to be paid by the customer.

  Depending on the tax settings this may be the gross or net price.
  Note that this price is already rounded, to get the raw price before rounding use `getRaw()`.
* **Returns** `float`

  The rounded total price of the cart as float.

***

## [`Shopware\Core\Checkout\Cart\Facade\ContainerFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/ContainerFacade.php) {#containerfacade}

The ContainerFacade allows you to wrap multiple line-items inside a container line-item.

### add()

* Use the `add()` method to add an item to this container.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade)

  The item that was added to the container.

* **Arguments:**
  * *[`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade)* **item**: The item that should be added.

* **Examples:**
  * Add a product to the container and reduce the quantity of the original line-item.

    ```twig
    ```

### count()

* `count()` returns the count of line-items in this collection.

  Note that it does only count the line-items directly in this collection and not child line-items of those.
* **Returns** `int`

  The number of line-items in this collection.

### discount()

* The `discount()` methods creates a new discount line-item with the given type and value.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\DiscountFacade`](./cart-manipulation-script-services-reference#discountfacade)

  Returns the newly created discount line-item.

* **Arguments:**
  * *`string`* **key**: The id for the new discount.
  * *`string`* **type**: The type of the discount, e.g. `percentage`, `absolute`
  * *`float|\PriceCollection`* **value**: The value of the discount, a float for percentage discounts or a `PriceCollection` for absolute discounts.
  * *`string`* **label**: The label of the discount line-item.

* **Examples:**
  * Add an absolute discount to the cart.

    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% if services.cart.items.count <= 0 %}
        {% return %}
    {% endif %}

    {% if services.cart.items.has('my-discount') %}
        {% return %}
    {% endif %}

    {% set price = services.cart.price.create({
        'default': { 'gross': -19.99, 'net': -19.99}
    }) %}

    {% do services.cart.discount('my-discount', 'absolute', price, 'Fancy discount') %}
    ```
  * Add a relative discount to the cart.

    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% if services.cart.has('my-discount') %}
        {% return %}
    {% endif %}

    {% do services.cart.discount('my-discount', 'percentage', -10, 'Fancy discount') %}
    ```

### get()

* `get()` returns the line-item with the given id from this collection.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade) | `null`

  The line-item with the given id, or null if it does not exist.

* **Arguments:**
  * *`string`* **id**: The id of the line-item that should be returned.

### getChildren()

* `getChildren()` returns the child line-items of this line-item.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemsFacade`](./cart-manipulation-script-services-reference#itemsfacade)

  Returns the children as a `ItemsFacade`, that may be empty if no children exist.

### getId()

* `getId()` returns the id of the line-item.

* **Returns** `string`

  Returns the id.

### getLabel()

* `getLabel()` returns the translated label of the line-item.

* **Returns** `string` | `null`

  Returns the translated label, or null if none exists.

### getPayload()

* `getPayload()` returns the payload of this line-item.

* **Returns** [`Shopware\Core\Framework\Script\Facade\ArrayFacade`](./miscellaneous-script-services-reference#arrayfacade)

  Returns the payload as `ArrayFacade`.

### getPrice()

* `getPrice()` returns the calculated price of the line-item.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\PriceFacade`](./cart-manipulation-script-services-reference#pricefacade) | `null`

  Returns the price of the line-item as a `PriceFacade` or null if the line-item has no calculated price.

### getQuantity()

* `getQuantity()` returns the quantity of the line-item.

* **Returns** `int`

  Returns the quantity.

### getReferencedId()

* `getReferenceId()` returns the id of the referenced entity of the line-item.

  E.g. for product line-items this will return the id of the referenced product.
* **Returns** `string` | `null`

  Returns the id of the referenced entity, or null if no entity is referenced.

### getType()

* `getType()` returns the type of this line-item.

  Possible types include `product`, `discount`, `container`, etc.
* **Returns** `string`

  The type of the line-item.

### has()

* `has()` checks if a line-item with the given id exists in this collection.

* **Returns** `bool`

  Returns true if the given line-item or a line-item with the given id already exists in the collection, false otherwise.

* **Arguments:**
  * *`string|\ItemFacade`* **id**: The id or a line-item that should be checked if it already exists in the collection.

### products()

* The `product()` method returns all products inside the current container for further manipulation.

  Similar to the `children()` method, but the line-items are filtered, to only contain product line items.
* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ProductsFacade`](./cart-manipulation-script-services-reference#productsfacade)

  A `ProductsFacade` containing all product line-items inside the current container as a collection.

### remove()

* `remove()` removes the given line-item or the line-item with the given id from this collection.

* **Arguments:**
  * *`string|\ItemFacade`* **id**: The id of the line-item or the line-item that should be removed.

* **Examples:**
  * Add and then remove a product line-item from the cart.

    ```twig
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% do services.cart.products.remove(hook.ids.get('p1')) %}
    ```

### surcharge()

* The `surcharge()` methods creates a new surcharge line-item with the given type and value.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\DiscountFacade`](./cart-manipulation-script-services-reference#discountfacade)

  Returns the newly created surcharge line-item.

* **Arguments:**
  * *`string`* **key**: The id for the new surcharge.
  * *`string`* **type**: The type of the surcharge, e.g. `percentage`, `absolute`
  * *`float|\PriceCollection`* **value**: The value of the surcharge, a float for percentage surcharges or a `PriceCollection` for absolute surcharges.
  * *`string`* **label**: The label of the surcharge line-item.

* **Examples:**
  * Add an absolute surcharge to the cart.#

    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% set price = services.cart.price.create({
        'default': { 'gross': 19.99, 'net': 19.99}
    }) %}

    {% do services.cart.surcharge('my-surcharge', 'absolute', price, 'Fancy surcharge') %}
    ```
  * Add a relative surcharge to the cart.

    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% if services.cart.has('my-surcharge') %}
        {% return %}
    {% endif %}

    {% do services.cart.surcharge('my-surcharge', 'percentage', -10, 'Fancy discount') %}
    ```

### take()

* `take()` splits an existing line-item by a given quantity.

  It removes the given quantity from the existing line-item and returns a new line-item with exactly that quantity.
* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade) | `null`

  Returns the new line-item as an `ItemFacade` or null if taking is not possible because the line-item has no sufficient quantity.
* **Arguments:**
  * *`int`* **quantity**: The quantity that should be taken.
  * *`string` | `null`* **key**: Optional: The id of the new line-item. A random UUID will be used if none is provided.

    Default: `null`
* **Examples:**
  * Take a quantity of 2 from an existing product line-item and add it to the cart again.

    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

    {% do services.cart.products.add(hook.ids.get('p1'), 5) %}

    {% set product = services.cart.products.get(hook.ids.get('p1')) %}

    {% set split = product.take(2, 'new-key') %}

    {% do services.cart.products.add(split) %}
    ```

***

## [`Shopware\Core\Checkout\Cart\Facade\DiscountFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/DiscountFacade.php) {#discountfacade}

The DiscountFacade is a wrapper around a newly created discount.
Note that this wrapper is independent from the line-item that was added for this discount.

### getId()

* `getId()` returns the id of the line-item that was added with this discount.

* **Returns** `string`

  The id of the discount line-item.

### getLabel()

* `getLabel()` returns the translated label of the line-item that was added with this discount.

* **Returns** `string` | `null`

  The translated label of the discount line-item.

***

## [`Shopware\Core\Checkout\Cart\Facade\ErrorsFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/ErrorsFacade.php) {#errorsfacade}

The ErrorsFacade is a wrapper around the errors of a cart.
You can use it to add new errors to the cart or remove existing ones.

### error()

* The `error()` method adds a new error of type `error` to the cart.

  The error will be displayed to the user and the checkout will be blocked if at least one error was added.
* **Arguments:**
  * *`string`* **key**: The snippet-key of the message that should be displayed to the user.
  * *`string` | `null`* **id**: An optional id that can be used to reference the error, if none is provided the $key will be used as id.

    Default: `null`
  * *`array`* **parameters**: Optional: Any parameters that the snippet for the error message may need.

    Default: `array (
    )`
* **Examples:**
  * Add a error to the cart.

    ```twig
    {% do services.cart.errors.error('NO_PRODUCTS_IN_CART') %}
    ```

### get()

* The `get()` method returns the error with the given id.

* **Returns** [`Shopware\Core\Checkout\Cart\Error\Error`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Error/Error.php) | `null`

  The Error with the given id, null if an error with that id does not exist.

* **Arguments:**
  * *`string`* **id**: The id of the error that should be returned.

### has()

* The `has()` method, checks if an error with a given id exists.

* **Returns** `bool`

  Returns true if an error with that key exists, false otherwise.

* **Arguments:**
  * *`string`* **id**: The id of the error that should be checked.

### notice()

* The `notice()` method adds a new error of type `notice` to the cart.

  The notice will be displayed to the user, but the checkout won't be blocked.
* **Arguments:**
  * *`string`* **key**: The snippet-key of the message that should be displayed to the user.
  * *`string` | `null`* **id**: An optional id that can be used to reference the error, if none is provided the $key will be used as id.

    Default: `null`
  * *`array`* **parameters**: Optional: Any parameters that the snippet for the error message may need.

    Default: `array (
    )`
* **Examples:**
  * Add a notice to the cart.

    ```twig
    {% do services.cart.errors.warning('ADD_PRODUCTS_OR_GO_AWAY') %}
    ```
  * Add a notice to the cart with a custom id.

    ```twig
    {% do services.cart.errors.notice('YOU_SHOULD_REALLY_ADD_PRODUCTS', 'add-same-message') %}
    ```
  * Add a notice to the cart with parameters.

    ```twig
    {% do services.cart.errors.notice('MESSAGE_WITH_PARAMETERS', null, {'foo': 'bar'}) %}
    ```

### remove()

* The `remove()` method removes the error with the given id.

* **Arguments:**
  * *`string`* **id**: The id of the error that should be removed.

### resubmittable()

* The `resubmittable()` method adds a new error of type `error` to the cart.

  The notice will be displayed to the user, the order will be blocked, but the user can submit the order again.
* **Arguments:**
  * *`string`* **key**: The snippet-key of the message that should be displayed to the user.
  * *`string` | `null`* **id**: An optional id that can be used to reference the error, if none is provided the $key will be used as id.

    Default: `null`
  * *`array`* **parameters**: Optional: Any parameters that the snippet for the error message may need.

    Default: `array (
    )`

### warning()

* The `warning()` method adds a new error of type `warning` to the cart.

  The warning will be displayed to the user, but the checkout won't be blocked.
* **Arguments:**
  * *`string`* **key**: The snippet-key of the message that should be displayed to the user.
  * *`string` | `null`* **id**: An optional id that can be used to reference the error, if none is provided the $key will be used as id.

    Default: `null`
  * *`array`* **parameters**: Optional: Any parameters that the snippet for the error message may need.

    Default: `array (
    )`
* **Examples:**
  * Add a warning to the cart.

    ```twig
    {% do services.cart.errors.notice('YOU_SHOULD_REALLY_ADD_PRODUCTS') %}
    ```

***

## [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/ItemFacade.php) {#itemfacade}

The ItemFacade is a wrapper around one line-item.

### getChildren()

* `getChildren()` returns the child line-items of this line-item.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemsFacade`](./cart-manipulation-script-services-reference#itemsfacade)

  Returns the children as a `ItemsFacade`, that may be empty if no children exist.

### getId()

* `getId()` returns the id of the line-item.

* **Returns** `string`

  Returns the id.

### getLabel()

* `getLabel()` returns the translated label of the line-item.

* **Returns** `string` | `null`

  Returns the translated label, or null if none exists.

### getPayload()

* `getPayload()` returns the payload of this line-item.

* **Returns** [`Shopware\Core\Framework\Script\Facade\ArrayFacade`](./miscellaneous-script-services-reference#arrayfacade)

  Returns the payload as `ArrayFacade`.

### getPrice()

* `getPrice()` returns the calculated price of the line-item.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\PriceFacade`](./cart-manipulation-script-services-reference#pricefacade) | `null`

  Returns the price of the line-item as a `PriceFacade` or null if the line-item has no calculated price.

### getQuantity()

* `getQuantity()` returns the quantity of the line-item.

* **Returns** `int`

  Returns the quantity.

### getReferencedId()

* `getReferenceId()` returns the id of the referenced entity of the line-item.

  E.g. for product line-items this will return the id of the referenced product.
* **Returns** `string` | `null`

  Returns the id of the referenced entity, or null if no entity is referenced.

### getType()

* `getType()` returns the type of this line-item.

  Possible types include `product`, `discount`, `container`, etc.
* **Returns** `string`

  The type of the line-item.

### take()

* `take()` splits an existing line-item by a given quantity.

  It removes the given quantity from the existing line-item and returns a new line-item with exactly that quantity.
* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade) | `null`

  Returns the new line-item as an `ItemFacade` or null if taking is not possible because the line-item has no sufficient quantity.
* **Arguments:**
  * *`int`* **quantity**: The quantity that should be taken.
  * *`string` | `null`* **key**: Optional: The id of the new line-item. A random UUID will be used if none is provided.

    Default: `null`
* **Examples:**
  * Take a quantity of 2 from an existing product line-item and add it to the cart again.

    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

    {% do services.cart.products.add(hook.ids.get('p1'), 5) %}

    {% set product = services.cart.products.get(hook.ids.get('p1')) %}

    {% set split = product.take(2, 'new-key') %}

    {% do services.cart.products.add(split) %}
    ```

***

## [`Shopware\Core\Checkout\Cart\Facade\ItemsFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/ItemsFacade.php) {#itemsfacade}

The ItemsFacade is a wrapper around a collection of line-items.

### add()

* `add()` adds a line-item to this collection.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade)

  Returns the added line-item.

* **Arguments:**
  * *[`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade)* **item**: The line-item that should be added.

* **Examples:**
  * Add an absolute discount to the cart.

    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% if services.cart.items.count <= 0 %}
        {% return %}
    {% endif %}

    {% if services.cart.items.has('my-discount') %}
        {% return %}
    {% endif %}

    {% set price = services.cart.price.create({
        'default': { 'gross': -19.99, 'net': -19.99}
    }) %}

    {% do services.cart.discount('my-discount', 'absolute', price, 'Fancy discount') %}
    ```

### count()

* `count()` returns the count of line-items in this collection.

  Note that it does only count the line-items directly in this collection and not child line-items of those.
* **Returns** `int`

  The number of line-items in this collection.

### get()

* `get()` returns the line-item with the given id from this collection.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade) | `null`

  The line-item with the given id, or null if it does not exist.

* **Arguments:**
  * *`string`* **id**: The id of the line-item that should be returned.

### has()

* `has()` checks if a line-item with the given id exists in this collection.

* **Returns** `bool`

  Returns true if the given line-item or a line-item with the given id already exists in the collection, false otherwise.

* **Arguments:**
  * *`string|\ItemFacade`* **id**: The id or a line-item that should be checked if it already exists in the collection.

### remove()

* `remove()` removes the given line-item or the line-item with the given id from this collection.

* **Arguments:**
  * *`string|\ItemFacade`* **id**: The id of the line-item or the line-item that should be removed.

* **Examples:**
  * Add and then remove a product line-item from the cart.

    ```twig
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% do services.cart.products.remove(hook.ids.get('p1')) %}
    ```

***

## [`Shopware\Core\Checkout\Cart\Facade\PriceFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/PriceFacade.php) {#pricefacade}

The PriceFacade is a wrapper around a price.

### change()

* `change()` allows a price overwrite of the current price scope. The provided price will be recalculated
  over the quantity price calculator to consider quantity, tax rule and cash rounding configurations.

* **Arguments:**
  * *[`Shopware\Core\Framework\DataAbstractionLayer\Pricing\PriceCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Pricing/PriceCollection.php)* **price**: The provided price can be a fetched price from the database or generated over the `PriceFactory` statically

* **Examples:**
  * Overwrite prices with a static defined collection

    ```twig
    {% do product.calculatedPrices.change([
        { to: 20, price: services.price.create({ 'default': { 'gross': 15, 'net': 15} }) },
        { to: 30, price: services.price.create({ 'default': { 'gross': 10, 'net': 10} }) },
        { to: null, price: services.price.create({ 'default': { 'gross': 5, 'net': 5} }) },
    ]) %}
    ```

### create()

* `create()` creates a new `PriceCollection` based on an array of prices.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Pricing\PriceCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Pricing/PriceCollection.php)

  Returns the newly created `PriceCollection`.

* **Arguments:**
  * *`array`* **price**: The prices for the new collection, indexed by the currency-id or iso-code of the currency.

* **Examples:**
  * Create a new Price in the default currency.

    ```twig
    {% set price = services.cart.price.create({
        'default': { 'gross': 19.99, 'net': 19.99}
    }) %}
    ```

### discount()

* `discount()` allows a percentage discount calculation of the current price scope. The provided value will be ensured to be negative via `abs(value) * -1`.

  The provided discount is interpreted as a percentage value and will be applied to the unit price and the total price as well.
* **Arguments:**
  * *`float`* **value**: The percentage value of the discount. The value will be ensured to be negative via `abs(value) * -1`.
* **Examples:**
  * Adds a 10% discount to the existing calculated price

    ```twig
    {% do product.calculatedPrice.discount(10) %}
    ```

### getQuantity()

* `getQuantity()` returns the quantity that was used to calculate the total price.

* **Returns** `int`

  Returns the quantity.

### getRules()

* `getRules()` returns the tax rules that were used to calculate the price.

* **Returns** [`Shopware\Core\Checkout\Cart\Tax\Struct\TaxRuleCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Tax/Struct/TaxRuleCollection.php)

  Returns the tax rules.

### getTaxes()

* `getTaxes()` returns the calculated taxes of the price.

* **Returns** [`Shopware\Core\Checkout\Cart\Tax\Struct\CalculatedTaxCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Tax/Struct/CalculatedTaxCollection.php)

  Returns the calculated taxes.

### getTotal()

* `getTotal()` returns the total price for the line-item.

* **Returns** `float`

  The total price as float.

### getUnit()

* `getUnit()` returns the unit price for the line-item.

  This is equivalent to the total price of the line-item with the quantity 1.
* **Returns** `float`

  The price per unit as float.

### minus()

* `minus()` allows a price subtraction of the current price scope. The provided price will be recalculated via the quantity price calculator.

  The provided price is interpreted as a unit price and will reduce to the current unit price.
  The total price is calculated afterwards considering quantity, tax rule and cash rounding configurations.
* **Arguments:**
  * *[`Shopware\Core\Framework\DataAbstractionLayer\Pricing\PriceCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Pricing/PriceCollection.php)* **price**: The provided price can be a fetched price from the database or generated over the `PriceFactory` statically
* **Examples:**
  * Minus a static defined price to the existing calculated price

    ```twig
    {% set price = services.price.create({
        'default': { 'gross': 1.5, 'net': 1.5}
    }) %}

    {% do product.calculatedPrice.minus(price) %}
    ```

### plus()

* `plus()` allows a price addition of the current price scope. The provided price will be recalculated via the quantity price calculator.

  The provided price is interpreted as a unit price and will be added to the current unit price.
  The total price is calculated afterwards considering quantity, tax rule and cash rounding configurations.
* **Arguments:**
  * *[`Shopware\Core\Framework\DataAbstractionLayer\Pricing\PriceCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Pricing/PriceCollection.php)* **price**: The provided price can be a fetched price from the database or generated over the `PriceFactory` statically
* **Examples:**
  * Plus a static defined price to the existing calculated price

    ```twig
    {% set price = services.price.create({
        'default': { 'gross': 1.5, 'net': 1.5}
    }) %}

    {% do product.calculatedPrice.plus(price) %}
    ```

### surcharge()

* `surcharge()` allows a percentage surcharge calculation of the current price scope. The provided value will be ensured to be negative via `abs(value)`.

  The provided surcharge is interpreted as a percentage value and will be applied to the unit price and the total price as well.
* **Arguments:**
  * *`float`* **value**: The percentage value of the surcharge. The value will be ensured to be negative via `abs(value)`.
* **Examples:**
  * Adds a 10% surcharge to the existing calculated price

    ```twig
    {% do product.calculatedPrice.surcharge(10) %}
    ```

***

## [services.price (`Shopware\Core\Checkout\Cart\Facade\PriceFactory`)](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/PriceFactory.php) {#pricefactory}

The PriceFacade is a wrapper around a price.

### create()

* `create()` creates a new `PriceCollection` based on an array of prices.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Pricing\PriceCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Pricing/PriceCollection.php)

  Returns the newly created `PriceCollection`.

* **Arguments:**
  * *`array`* **prices**: The prices for the new collection, indexed by the currency-id or iso-code of the currency.

* **Examples:**
  * Create a new Price in the default currency.

    ```twig
    {% set price = services.cart.price.create({
        'default': { 'gross': 19.99, 'net': 19.99}
    }) %}
    ```

***

## [`Shopware\Core\Checkout\Cart\Facade\ProductsFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/ProductsFacade.php) {#productsfacade}

The ProductsFacade is a wrapper around a collection of product line-items.

### add()

* `add()` adds a new product  line-item to this collection.

  In the case only a product id is provided it will create a new line-item from type product for the given product id.
* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade)

  The newly added product line-item.
* **Arguments:**
  * *`string|\LineItem|\ItemFacade`* **product**: The product that should be added. Either an existing `ItemFacade` or `LineItem` or alternatively the id of a product.
  * *`int`* **quantity**: Optionally provide the quantity with which the product line-item should be created, defaults to 1.

    Default: `1`
* **Examples:**
  * Add a product to the cart by id.

    ```twig
    {% do services.cart.products.add(hook.ids.get('p1')) %}
    ```

### count()

* `count()` returns the count of line-items in this collection.

  Note that it does only count the line-items directly in this collection and not child line-items of those.
* **Returns** `int`

  The number of line-items in this collection.

### create()

* `create()` creates a new product line-item for the product with the given id in the given quantity.

  Note that the created line-item will not be added automatically to this collection, use `add()` for that.
* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade)

  The newly created product line-item.
* **Arguments:**
  * *`string`* **productId**: The product id for which a line-item should be created.
  * *`int`* **quantity**: Optionally provide the quantity with which the product line-item should be created, defaults to 1.

    Default: `1`

### get()

* `get()` returns the product line-item with the given product id.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade) | `null`

  The line-item associated with the given product id, or null if it does not exist.

* **Arguments:**
  * *`string`* **productId**: The id of the product, of which the line-item should be returned.

* **Examples:**
  * Get a product line-item by id.

    ```twig
    {% set product = services.cart.products.get(hook.ids.get('p1')) %}
    ```

### has()

* `has()` checks if a line-item with the given id exists in this collection.

* **Returns** `bool`

  Returns true if the given line-item or a line-item with the given id already exists in the collection, false otherwise.

* **Arguments:**
  * *`string|\ItemFacade`* **id**: The id or a line-item that should be checked if it already exists in the collection.

### remove()

* `remove()` removes the given line-item or the line-item with the given id from this collection.

* **Arguments:**
  * *`string|\ItemFacade`* **id**: The id of the line-item or the line-item that should be removed.

* **Examples:**
  * Add and then remove a product line-item from the cart.

    ```twig
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% do services.cart.products.remove(hook.ids.get('p1')) %}
    ```

***

## [`Shopware\Core\Checkout\Cart\Facade\StatesFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/StatesFacade.php) {#statesfacade}

The StatesFacade allows access to the current cart states and functions.

### add()

* `add()` allows you to add one or multiple states as string values to the cart.

  This can be useful to check if your script did already run and did some manipulations to the cart.
* **Arguments:**
  * *`string`* **states**: One or more strings that will be stored on the cart.

### get()

* `get()` returns all states that are present on the cart.

* **Returns** `array`

  An array containing all current states of the cart.

### has()

* `has()` allows you to check if one or more states are present on the cart.

* **Returns** `bool`

  Returns true if at least one of the passed states is present on the cart, false otherwise.

* **Arguments:**
  * *`string`* **states**: One or more strings that should be checked.

### remove()

* `remove()` removes the given state from the cart, if it existed.

* **Arguments:**
  * *`string`* **state**: The state that should be removed.

***

---

---
url: >-
  /docs/v6.5/resources/references/app-reference/script-reference/cart-manipulation-script-services-reference.md
---

# Cart Manipulation script services reference

## [services.cart (`Shopware\Core\Checkout\Cart\Facade\CartFacade`)](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/CartFacade.php) {#cartfacade}

The `cart` service allows you to manipulate the cart.
You can use the cart service to add line-items, change prices, add discounts, etc. to the cart.

### items()

* The `items()` method returns all line-items of the current cart for further manipulation.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemsFacade`](./cart-manipulation-script-services-reference#itemsfacade)

  A `ItemsFacade` containing all line-items in the current cart as a collection.

### products()

* The `product()` method returns all products of the current cart for further manipulation. Similar to the `items()` method, but the line-items are filtered, to only contain product line items.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ProductsFacade`](./cart-manipulation-script-services-reference#productsfacade)

  A `ProductsFacade` containing all product line-items in the current cart as a collection.

### calculate()

* The `calculate()` method recalculates the whole cart.

  Use this to get the correct prices after you made changes to the cart. Note that after calling the `calculate()` all collections (e.g. items(), products()) get new references,	so if you still hold references to things inside the cart, these are outdated after calling `calculate()`. This method will be called automatically after your cart script executed.

### price()

* The `price()` method returns the current price of the cart.

  Note that this price may be outdated, if you changed something inside the cart in your script.Use the `calculate()` method to recalculate the cart and update the price.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\CartPriceFacade`](./cart-manipulation-script-services-reference#cartpricefacade)

  The calculated price of the cart.

### errors()

* The `errors()` method returns the current errors of the cart.

  You can use it to add new errors or warning or to remove existing ones.
* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ErrorsFacade`](./cart-manipulation-script-services-reference#errorsfacade)

  A `ErrorsFacade` containing all cart errors as a collection (may be an empty collection if there are no errors).

### states()

* `states()` allows you to access the state functions of the current cart.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\StatesFacade`](./cart-manipulation-script-services-reference#statesfacade)

  A `StatesFacade` containing all cart states as a collection (maybe an empty collection if there are no states).

### discount()

* The `discount()` methods creates a new discount line-item with the given type and value.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\DiscountFacade`](./cart-manipulation-script-services-reference#discountfacade).

  Returns the newly created discount line-item.

* **Arguments:**
  * *`string`* **key**: The id for the new discount.
  * *`string`* **type**: The type of the discount, e.g. `percentage`, `absolute`
  * *`float|\PriceCollection`* **value**: The value of the discount, a float for percentage discounts or a `PriceCollection` for absolute discounts.
  * *`string`* **label**: The label of the discount line-item.

* **Examples:**
  * Add an absolute discount to the cart.

    ````
    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% if services.cart.items.count <= 0 %}
        {% return %}
    {% endif %}

    {% if services.cart.items.has('my-discount') %}
        {% return %}
    {% endif %}

    {% set price = services.cart.price.create({
        'default': { 'gross': -19.99, 'net': -19.99}
    }) %}

    {% do services.cart.discount('my-discount', 'absolute', price, 'Fancy discount') %}
    ```
    ````

  * Add a relative discount to the cart.

    ````
    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% if services.cart.has('my-discount') %}
        {% return %}
    {% endif %}

    {% do services.cart.discount('my-discount', 'percentage', -10, 'Fancy discount') %}
    ```
    ````

### surcharge()

* The `surcharge()` methods creates a new surcharge line-item with the given type and value.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\DiscountFacade`](./cart-manipulation-script-services-reference#discountfacade).

  Returns the newly created surcharge line-item.

* **Arguments:**
  * *`string`* **key**: The id for the new surcharge.
  * *`string`* **type**: The type of the surcharge, e.g. `percentage`, `absolute`
  * *`float|\PriceCollection`* **value**: The value of the surcharge, a float for percentage surcharges or a `PriceCollection` for absolute surcharges.
  * *`string`* **label**: The label of the surcharge line-item.

* **Examples:**

  * Add an absolute surcharge to the cart.#

    ````
    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% set price = services.cart.price.create({
        'default': { 'gross': 19.99, 'net': 19.99}
    }) %}

    {% do services.cart.surcharge('my-surcharge', 'absolute', price, 'Fancy surcharge') %}
    ```
    ````

  * Add a relative surcharge to the cart.

    ````
    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% if services.cart.has('my-surcharge') %}
        {% return %}
    {% endif %}

    {% do services.cart.surcharge('my-surcharge', 'percentage', -10, 'Fancy discount') %}
    ```
    ````

### get()

* `get()` returns the line-item with the given id from this collection.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade) | `null`

  The line-item with the given id, or null if it does not exist.

* **Arguments:**
  * *`string`* **id**: The id of the line-item that should be returned.

### remove()

* `remove()` removes the given line-item or the line-item with the given id from this collection.

* **Arguments:**

  * *`string|\ItemFacade`* **id**: The id of the line-item or the line-item that should be removed.

* **Examples:**

  * Add and then remove a product line-item from the cart.

    ````
    ```twig
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% do services.cart.products.remove(hook.ids.get('p1')) %}
    ```
    ````

### has()

* `has()` checks if a line-item with the given id exists in this collection.

* **Returns** `bool`

  Returns true if the given line-item or a line-item with the given id already exists in the collection, false otherwise.

* **Arguments:**

  * *`string|\ItemFacade`* **id**: The id or a line-item that should be checked if it already exists in the collection.

### count()

* `count()` returns the count of line-items in this collection.

  Note that it does only count the line-items directly in this collection and not child line-items of those.

* **Returns** `int`

  The number of line-items in this collection.

***

## [`Shopware\Core\Checkout\Cart\Facade\CartPriceFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/CartPriceFacade.php) {#cartpricefacade}

The CartPriceFacade is a wrapper around the calculated price of a cart.

### getNet()

* `getNet()` returns the net price of the cart.

* **Returns** `float`

  Returns the net price of the cart as float.

### getTotal()

* `getTotal()` returns the total price of the cart that has to be paid by the customer.

  Depending on the tax settings this may be the gross or net price. Note that this price is already rounded, to get the raw price before rounding use `getRaw()`.

* **Returns** `float`

  The rounded total price of the cart as float.

### getPosition()

* `getPosition()` returns the sum price of all line-items in the cart.

  In the position price the shipping costs are excluded. Depending on the tax settings this may be the gross or net price og the line-items.

* **Returns** `float`

  The position price as float.

### getRounded()

* Alias for `getTotal()`.

* **Returns** `float`

  The rounded total price of the cart as float.

### getRaw()

* \`getRaw() returns the total price of the cart before rounding.

* **Returns** `float`

  The total price before rounding as float.

### create()

* `create()` creates a new `PriceCollection` based on an array of prices.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Pricing\PriceCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Pricing/PriceCollection.php)

  Returns the newly created `PriceCollection`.

* **Arguments:**

  * *`array`* **price**: The prices for the new collection, indexed by the currency-id or iso-code of the currency.

* **Examples:**

  * Create a new Price in the default currency.

    ````
    ```twig
    {% set price = services.cart.price.create({
        'default': { 'gross': 19.99, 'net': 19.99}
    }) %}
    ```
    ````

***

## [`Shopware\Core\Checkout\Cart\Facade\ContainerFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/ContainerFacade.php) {#containerfacade}

The ContainerFacade allows you to wrap multiple line-items inside a container line-item.

### products()

* The `product()` method returns all products inside the current container for further manipulation.

  Similar to the `children()` method, but the line-items are filtered, to only contain product line items.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ProductsFacade`](./cart-manipulation-script-services-reference#productsfacade)

  A `ProductsFacade` containing all product line-items inside the current container as a collection.

### add()

* Use the `add()` method to add an item to this container.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade)

  The item that was added to the container.

* **Arguments:**

  * *[`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade)* **item**: The item that should be added.

* **Examples:**

  * Add a product to the container and reduce the quantity of the original line-item.

    ````
    ```twig

    ```
    ````

### getPrice()

* `getPrice()` returns the calculated price of the line-item.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\PriceFacade`](./cart-manipulation-script-services-reference#pricefacade) | `null`

  Returns the price of the line-item as a `PriceFacade` or null if the line-item has no calculated price.

### take()

* `take()` splits an existing line-item by a given quantity.

  It removes the given quantity from the existing line-item and returns a new line-item with exactly that quantity.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade) | `null`

  Returns the new line-item as an `ItemFacade` or null if taking is not possible because the line-item has no sufficient quantity.

* **Arguments:**

  * *`int`* **quantity**: The quantity that should be taken.
  * *`string` | `null`* **key**: Optional: The id of the new line-item. A random UUID will be used if none is provided.

    ```
    Default: `null`.
    ```

* **Examples:**

  * Take a quantity of 2 from an existing product line-item and add it to the cart again.

    ````
    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

    {% do services.cart.products.add(hook.ids.get('p1'), 5) %}

    {% set product = services.cart.products.get(hook.ids.get('p1')) %}

    {% set split = product.take(2, 'new-key') %}

    {% do services.cart.products.add(split) %}
    ```
    ````

### getId()

* `getId()` returns the id of the line-item.

* **Returns** `string`

  Returns the id.

### getReferencedId()

* `getReferenceId()` returns the id of the referenced entity of the line-item.

  E.g. for product line-items this will return the id of the referenced product.
* **Returns** `string` | `null`

  Returns the id of the referenced entity, or null if no entity is referenced.

### getQuantity()

* `getQuantity()` returns the quantity of the line-item.

* **Returns** `int`

  Returns the quantity.

### getLabel()

* `getLabel()` returns the translated label of the line-item.

* **Returns** `string` | `null`

  Returns the translated label, or null if none exists.

### getPayload()

* `getPayload()` returns the payload of this line-item.

* **Returns** [`Shopware\Core\Framework\Script\Facade\ArrayFacade`](./miscellaneous-script-services-reference#arrayfacade)

  Returns the payload as `ArrayFacade`.

### getChildren()

* `getChildren()` returns the child line-items of this line-item.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemsFacade`](./cart-manipulation-script-services-reference#itemsfacade)

  Returns the children as a `ItemsFacade`, that may be empty if no children exist.

### getType()

* `getType()` returns the type of this line-item.

  Possible types include `product`, `discount`, `container`, etc.
* **Returns** `string`

  The type of the line-item.

### discount()

* The `discount()` methods creates a new discount line-item with the given type and value.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\DiscountFacade`](./cart-manipulation-script-services-reference#discountfacade)

  Returns the newly created discount line-item.

* **Arguments:**

  * *`string`* **key**: The id for the new discount.
  * *`string`* **type**: The type of the discount, e.g. `percentage`, `absolute`
  * *`float|\PriceCollection`* **value**: The value of the discount, a float for percentage discounts or a `PriceCollection` for absolute discounts.
  * *`string`* **label**: The label of the discount line-item.

* **Examples:**

  * Add an absolute discount to the cart.

    ````
    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% if services.cart.items.count <= 0 %}
        {% return %}
    {% endif %}

    {% if services.cart.items.has('my-discount') %}
        {% return %}
    {% endif %}

    {% set price = services.cart.price.create({
        'default': { 'gross': -19.99, 'net': -19.99}
    }) %}

    {% do services.cart.discount('my-discount', 'absolute', price, 'Fancy discount') %}
    ```
    ````

  * Add a relative discount to the cart.

    ````
    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% if services.cart.has('my-discount') %}
        {% return %}
    {% endif %}

    {% do services.cart.discount('my-discount', 'percentage', -10, 'Fancy discount') %}
    ```
    ````

### surcharge()

* The `surcharge()` methods creates a new surcharge line-item with the given type and value.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\DiscountFacade`](./cart-manipulation-script-services-reference#discountfacade)

  Returns the newly created surcharge line-item.

* **Arguments:**
  * *`string`* **key**: The id for the new surcharge.
  * *`string`* **type**: The type of the surcharge, e.g. `percentage`, `absolute`
  * *`float|\PriceCollection`* **value**: The value of the surcharge, a float for percentage surcharges or a `PriceCollection` for absolute surcharges.
  * *`string`* **label**: The label of the surcharge line-item.

* **Examples:**

  * Add an absolute surcharge to the cart.#

    ````
    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% set price = services.cart.price.create({
        'default': { 'gross': 19.99, 'net': 19.99}
    }) %}

    {% do services.cart.surcharge('my-surcharge', 'absolute', price, 'Fancy surcharge') %}
    ```
    ````

  * Add a relative surcharge to the cart.

    ````
    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% if services.cart.has('my-surcharge') %}
        {% return %}
    {% endif %}

    {% do services.cart.surcharge('my-surcharge', 'percentage', -10, 'Fancy discount') %}
    ```
    ````

### get()

* `get()` returns the line-item with the given id from this collection.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade) | `null`

  The line-item with the given id, or null if it does not exist.

* **Arguments:**

  * *`string`* **id**: The id of the line-item that should be returned.

### remove()

* `remove()` removes the given line-item or the line-item with the given id from this collection.

* **Arguments:**

  * *`string|\ItemFacade`* **id**: The id of the line-item or the line-item that should be removed.

* **Examples:**

  * Add and then remove a product line-item from the cart.

    ````
    ```twig
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% do services.cart.products.remove(hook.ids.get('p1')) %}
    ```
    ````

### has()

* `has()` checks if a line-item with the given id exists in this collection.

* **Returns** `bool`

  Returns true if the given line-item or a line-item with the given id already exists in the collection, false otherwise.

* **Arguments:**

  * *`string|\ItemFacade`* **id**: The id or a line-item that should be checked if it already exists in the collection.

### count()

* `count()` returns the count of line-items in this collection.

  Note that it does only count the line-items directly in this collection and not child line-items of those.

* **Returns** `int`

  The number of line-items in this collection.

***

## [`Shopware\Core\Checkout\Cart\Facade\DiscountFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/DiscountFacade.php) {#discountfacade}

The DiscountFacade is a wrapper around a newly created discount.
Note that this wrapper is independent from the line-item that was added for this discount.

### getId()

* `getId()` returns the id of the line-item that was added with this discount.

* **Returns** `string`

  The id of the discount line-item.

### getLabel()

* `getLabel()` returns the translated label of the line-item that was added with this discount.

* **Returns** `string` | `null`

  The translated label of the discount line-item.

***

## [`Shopware\Core\Checkout\Cart\Facade\ErrorsFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/ErrorsFacade.php) {#errorsfacade}

The ErrorsFacade is a wrapper around the errors of a cart.
You can use it to add new errors to the cart or remove existing ones.

### error()

* The `error()` method adds a new error of type `error` to the cart.

  The error will be displayed to the user and the checkout will be blocked if at least one error was added.

* **Arguments:**

  * *`string`* **key**: The snippet-key of the message that should be displayed to the user.
  * *`string` | `null`* **id**: An optional id that can be used to reference the error, if none is provided the $key will be used as id.

    ```
    Default: `null`
    ```
  * *`array`* **parameters**: Optional: Any parameters that the snippet for the error message may need.

    ```
    Default: `array ()`
    ```

* **Examples:**

  * Add a error to the cart.

    ````
    ```twig
    {% do services.cart.errors.error('NO_PRODUCTS_IN_CART') %}
    ```
    ````

### warning()

* The `warning()` method adds a new error of type `warning` to the cart.

  The warning will be displayed to the user, but the checkout won't be blocked.

* **Arguments:**

  * *`string`* **key**: The snippet-key of the message that should be displayed to the user.
  * *`string` | `null`* **id**: An optional id that can be used to reference the error, if none is provided the $key will be used as id.

    ```
    Default: `null`
    ```
  * *`array`* **parameters**: Optional: Any parameters that the snippet for the error message may need.

    ```
    Default: `array ()`
    ```

* **Examples:**

  * Add a warning to the cart.

    ````
    ```twig
    {% do services.cart.errors.notice('YOU_SHOULD_REALLY_ADD_PRODUCTS') %}
    ```
    ````

### notice()

* The `notice()` method adds a new error of type `notice` to the cart.

  The notice will be displayed to the user, but the checkout won't be blocked.

* **Arguments:**

  * *`string`* **key**: The snippet-key of the message that should be displayed to the user.
  * *`string` | `null`* **id**: An optional id that can be used to reference the error, if none is provided the $key will be used as id.

    ```
    Default: `null`
    ```
  * *`array`* **parameters**: Optional: Any parameters that the snippet for the error message may need.

    ```
    Default: `array ()`
    ```

* **Examples:**

  * Add a notice to the cart.

    ````
    ```twig
    {% do services.cart.errors.warning('ADD_PRODUCTS_OR_GO_AWAY') %}
    ```
    ````

  * Add a notice to the cart with a custom id.

    ````
    ```twig
    {% do services.cart.errors.notice('YOU_SHOULD_REALLY_ADD_PRODUCTS', 'add-same-message') %}
    ```
    ````

  * Add a notice to the cart with parameters.

    ````
    ```twig
    {% do services.cart.errors.notice('MESSAGE_WITH_PARAMETERS', null, {'foo': 'bar'}) %}
    ```
    ````

### resubmittable()

* The `resubmittable()` method adds a new error of type `error` to the cart.

  The notice will be displayed to the user, the order will be blocked, but the user can submit the order again.

* **Arguments:**

  * *`string`* **key**: The snippet-key of the message that should be displayed to the user.

  * *`string` | `null`* **id**: An optional id that can be used to reference the error, if none is provided the $key will be used as id.

    ```
    Default: `null`
    ```

  * *`array`* **parameters**: Optional: Any parameters that the snippet for the error message may need.

    ```
    Default: `array ()`
    ```

### has()

* The `has()` method, checks if an error with a given id exists.

* **Returns** `bool`

  Returns true if an error with that key exists, false otherwise.

* **Arguments:**

  * *`string`* **id**: The id of the error that should be checked.

### remove()

* The `remove()` method removes the error with the given id.

* **Arguments:**

  * *`string`* **id**: The id of the error that should be removed.

### get()

* The `get()` method returns the error with the given id.

* **Returns** [`Shopware\Core\Checkout\Cart\Error\Error`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Error/Error.php) | `null`

  The Error with the given id, null if an error with that id does not exist.

* **Arguments:**

  * *`string`* **id**: The id of the error that should be returned.

***

## [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/ItemFacade.php) {#itemfacade}

The ItemFacade is a wrapper around one line-item.

### getPrice()

* `getPrice()` returns the calculated price of the line-item.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\PriceFacade`](./cart-manipulation-script-services-reference#pricefacade) | `null`

  Returns the price of the line-item as a `PriceFacade` or null if the line-item has no calculated price.

### take()

* `take()` splits an existing line-item by a given quantity.

  It removes the given quantity from the existing line-item and returns a new line-item with exactly that quantity.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade) | `null`

  Returns the new line-item as an `ItemFacade` or null if taking is not possible because the line-item has no sufficient quantity.

* **Arguments:**

  * *`int`* **quantity**: The quantity that should be taken.

  * *`string` | `null`* **key**: Optional: The id of the new line-item. A random UUID will be used if none is provided.

    ```
    Default: `null`
    ```

* **Examples:**

  * Take a quantity of 2 from an existing product line-item and add it to the cart again.

    ````
    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

    {% do services.cart.products.add(hook.ids.get('p1'), 5) %}

    {% set product = services.cart.products.get(hook.ids.get('p1')) %}

    {% set split = product.take(2, 'new-key') %}

    {% do services.cart.products.add(split) %}
    ```
    ````

### getId()

* `getId()` returns the id of the line-item.

* **Returns** `string`

  Returns the id.

### getReferencedId()

* `getReferenceId()` returns the id of the referenced entity of the line-item.

  E.g. for product line-items this will return the id of the referenced product.

* **Returns** `string` | `null`

  Returns the id of the referenced entity, or null if no entity is referenced.

### getQuantity()

* `getQuantity()` returns the quantity of the line-item.

* **Returns** `int`

  Returns the quantity.

### getLabel()

* `getLabel()` returns the translated label of the line-item.

* **Returns** `string` | `null`

  Returns the translated label, or null if none exists.

### getPayload()

* `getPayload()` returns the payload of this line-item.

* **Returns** [`Shopware\Core\Framework\Script\Facade\ArrayFacade`](./miscellaneous-script-services-reference#arrayfacade)

  Returns the payload as `ArrayFacade`.

### getChildren()

* `getChildren()` returns the child line-items of this line-item.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemsFacade`](./cart-manipulation-script-services-reference#itemsfacade)

  Returns the children as a `ItemsFacade`, that may be empty if no children exist.

### getType()

* `getType()` returns the type of this line-item.

  Possible types include `product`, `discount`, `container`, etc.

* **Returns** `string`

  The type of the line-item.

***

## [`Shopware\Core\Checkout\Cart\Facade\ItemsFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/ItemsFacade.php) {#itemsfacade}

The ItemsFacade is a wrapper around a collection of line-items.

### add()

* `add()` adds a line-item to this collection.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade)

  Returns the added line-item.

* **Arguments:**

  * *[`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade)* **item**: The line-item that should be added.

* **Examples:**

  * Add an absolute discount to the cart.

    ````
    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% if services.cart.items.count <= 0 %}
        {% return %}
    {% endif %}

    {% if services.cart.items.has('my-discount') %}
        {% return %}
    {% endif %}

    {% set price = services.cart.price.create({
        'default': { 'gross': -19.99, 'net': -19.99}
    }) %}

    {% do services.cart.discount('my-discount', 'absolute', price, 'Fancy discount') %}
    ```
    ````

### get()

* `get()` returns the line-item with the given id from this collection.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade) | `null`

  The line-item with the given id, or null if it does not exist.

* **Arguments:**

  * *`string`* **id**: The id of the line-item that should be returned.

### has()

* `has()` checks if a line-item with the given id exists in this collection.

* **Returns** `bool`

  Returns true if the given line-item or a line-item with the given id already exists in the collection, false otherwise.

* **Arguments:**

  * *`string|\ItemFacade`* **id**: The id or a line-item that should be checked if it already exists in the collection.

### remove()

* `remove()` removes the given line-item or the line-item with the given id from this collection.

* **Arguments:**

  * *`string|\ItemFacade`* **id**: The id of the line-item or the line-item that should be removed.

* **Examples:**

  * Add and then remove a product line-item from the cart.

    ````
    ```twig
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% do services.cart.products.remove(hook.ids.get('p1')) %}
    ```
    ````

### count()

* `count()` returns the count of line-items in this collection.

  Note that it does only count the line-items directly in this collection and not child line-items of those.

* **Returns** `int`

  The number of line-items in this collection.

***

## [`Shopware\Core\Checkout\Cart\Facade\PriceFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/PriceFacade.php) {#pricefacade}

The PriceFacade is a wrapper around a price.

### getTotal()

* `getTotal()` returns the total price for the line-item.

* **Returns** `float`

  The total price as float.

### getUnit()

* `getUnit()` returns the unit price for the line-item.

  This is equivalent to the total price of the line-item with the quantity 1.

* **Returns** `float`

  The price per unit as float.

### getQuantity()

* `getQuantity()` returns the quantity that was used to calculate the total price.

* **Returns** `int`

  Returns the quantity.

### getTaxes()

* `getTaxes()` returns the calculated taxes of the price.

* **Returns** [`Shopware\Core\Checkout\Cart\Tax\Struct\CalculatedTaxCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Tax/Struct/CalculatedTaxCollection.php)

  Returns the calculated taxes.

### getRules()

* `getRules()` returns the tax rules that were used to calculate the price.

* **Returns** [`Shopware\Core\Checkout\Cart\Tax\Struct\TaxRuleCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Tax/Struct/TaxRuleCollection.php)

  Returns the tax rules.

### change()

* `change()` allows a price overwrite of the current price scope. The provided price will be recalculated
  over the quantity price calculator to consider quantity, tax rule and cash rounding configurations.

* **Arguments:**

  * *[`Shopware\Core\Framework\DataAbstractionLayer\Pricing\PriceCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Pricing/PriceCollection.php)* **price**: The provided price can be a fetched price from the database or generated over the `PriceFactory` statically.

* **Examples:**

  * Overwrite prices with a static defined collection

    ````
    ```twig
    {% do product.calculatedPrices.change([
        { to: 20, price: services.price.create({ 'default': { 'gross': 15, 'net': 15} }) },
        { to: 30, price: services.price.create({ 'default': { 'gross': 10, 'net': 10} }) },
        { to: null, price: services.price.create({ 'default': { 'gross': 5, 'net': 5} }) },
    ]) %}
    ```
    ````

### plus()

* `plus()` allows a price addition of the current price scope. The provided price will be recalculated via the quantity price calculator.

  The provided price is interpreted as a unit price and will be added to the current unit price. The total price is calculated afterwards considering quantity, tax rule and cash rounding configurations.

* **Arguments:**

  * *[`Shopware\Core\Framework\DataAbstractionLayer\Pricing\PriceCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Pricing/PriceCollection.php)* **price**: The provided price can be a fetched price from the database or generated over the `PriceFactory` statically.

* **Examples:**

  * Plus a static defined price to the existing calculated price

    ````
    ```twig
    {% set price = services.price.create({
        'default': { 'gross': 1.5, 'net': 1.5}
    }) %}

    {% do product.calculatedPrice.plus(price) %}
    ```
    ````

### minus()

* `minus()` allows a price subtraction of the current price scope. The provided price will be recalculated via the quantity price calculator.

  The provided price is interpreted as a unit price and will reduce to the current unit price. The total price is calculated afterwards considering quantity, tax rule and cash rounding configurations.

* **Arguments:**

  * *[`Shopware\Core\Framework\DataAbstractionLayer\Pricing\PriceCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Pricing/PriceCollection.php)* **price**: The provided price can be a fetched price from the database or generated over the `PriceFactory` statically.

* **Examples:**

  * Minus a static defined price to the existing calculated price

    ````
    ```twig
    {% set price = services.price.create({
        'default': { 'gross': 1.5, 'net': 1.5}
    }) %}

    {% do product.calculatedPrice.minus(price) %}
    ```
    ````

### discount()

* `discount()` allows a percentage discount calculation of the current price scope. The provided value will be ensured to be negative via `abs(value) * -1`.

  The provided discount is interpreted as a percentage value and will be applied to the unit price and the total price as well.

* **Arguments:**

  * *`float`* **value**: The percentage value of the discount. The value will be ensured to be negative via `abs(value) * -1`.

* **Examples:**

  * Adds a 10% discount to the existing calculated price

    ````
    ```twig
    {% do product.calculatedPrice.discount(10) %}
    ```
    ````

### surcharge()

* `surcharge()` allows a percentage surcharge calculation of the current price scope. The provided value will be ensured to be negative via `abs(value)`.

  The provided surcharge is interpreted as a percentage value and will be applied to the unit price and the total price as well.

* **Arguments:**

  * *`float`* **value**: The percentage value of the surcharge. The value will be ensured to be negative via `abs(value)`.

* **Examples:**

  * Adds a 10% surcharge to the existing calculated price

    ````
    ```twig
    {% do product.calculatedPrice.surcharge(10) %}
    ```
    ````

### create()

* `create()` creates a new `PriceCollection` based on an array of prices.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Pricing\PriceCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Pricing/PriceCollection.php)

  Returns the newly created `PriceCollection`.

* **Arguments:**

  * *`array`* **price**: The prices for the new collection, indexed by the currency-id or iso-code of the currency.

* **Examples:**

  * Create a new Price in the default currency.

    ````
    ```twig
    {% set price = services.cart.price.create({
        'default': { 'gross': 19.99, 'net': 19.99}
    }) %}
    ```
    ````

***

## [services.price (`Shopware\Core\Checkout\Cart\Facade\PriceFactory`)](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/PriceFactory.php) {#pricefactory}

The PriceFacade is a wrapper around a price.

### create()

* `create()` creates a new `PriceCollection` based on an array of prices.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Pricing\PriceCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Pricing/PriceCollection.php)

  Returns the newly created `PriceCollection`.

* **Arguments:**

  * *`array`* **prices**: The prices for the new collection, indexed by the currency-id or iso-code of the currency.

* **Examples:**

  * Create a new Price in the default currency.

    ````
    ```twig
    {% set price = services.cart.price.create({
        'default': { 'gross': 19.99, 'net': 19.99}
    }) %}
    ```
    ````

***

## [`Shopware\Core\Checkout\Cart\Facade\ProductsFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/ProductsFacade.php) {#productsfacade}

The ProductsFacade is a wrapper around a collection of product line-items.

### get()

* `get()` returns the product line-item with the given product id.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade) | `null`

  The line-item associated with the given product id, or null if it does not exist.

* **Arguments:**

  * *`string`* **productId**: The id of the product, of which the line-item should be returned.

* **Examples:**

  * Get a product line-item by id.

    ````
    ```twig
    {% set product = services.cart.products.get(hook.ids.get('p1')) %}
    ```
    ````

### add()

* `add()` adds a new product  line-item to this collection.

  In the case only a product id is provided it will create a new line-item from type product for the given product id.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade)

  The newly added product line-item.

* **Arguments:**

  * *`string|\LineItem|\ItemFacade`* **product**: The product that should be added. Either an existing `ItemFacade` or `LineItem` or alternatively the id of a product.

  * *`int`* **quantity**: Optionally provide the quantity with which the product line-item should be created, defaults to 1.

    ```
    Default: `1`
    ```

* **Examples:**

  * Add a product to the cart by id.

    ````
    ```twig
    {% do services.cart.products.add(hook.ids.get('p1')) %}
    ```
    ````

### create()

* `create()` creates a new product line-item for the product with the given id in the given quantity.

  Note that the created line-item will not be added automatically to this collection, use `add()` for that.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade)

  The newly created product line-item.

* **Arguments:**

  * *`string`* **productId**: The product id for which a line-item should be created.
  * *`int`* **quantity**: Optionally provide the quantity with which the product line-item should be created, defaults to 1.

    ```
    Default: `1`
    ```

### remove()

* `remove()` removes the given line-item or the line-item with the given id from this collection.

* **Arguments:**

  * *`string|\ItemFacade`* **id**: The id of the line-item or the line-item that should be removed.

* **Examples:**

  * Add and then remove a product line-item from the cart.

    ````
    ```twig
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% do services.cart.products.remove(hook.ids.get('p1')) %}
    ```
    ````

### has()

* `has()` checks if a line-item with the given id exists in this collection.

* **Returns** `bool`

  Returns true if the given line-item or a line-item with the given id already exists in the collection, false otherwise.

* **Arguments:**

  * *`string|\ItemFacade`* **id**: The id or a line-item that should be checked if it already exists in the collection.

### count()

* `count()` returns the count of line-items in this collection.

  Note that it does only count the line-items directly in this collection and not child line-items of those.

* **Returns** `int`

  The number of line-items in this collection.

***

## [`Shopware\Core\Checkout\Cart\Facade\StatesFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/StatesFacade.php) {#statesfacade}

The StatesFacade allows access to the current cart states and functions.

### add()

* `add()` allows you to add one or multiple states as string values to the cart.

  This can be useful to check if your script did already run and did some manipulations to the cart.

* **Arguments:**

  * *`string`* **states**: One or more strings that will be stored on the cart.

### remove()

* `remove()` removes the given state from the cart, if it existed.

* **Arguments:**

  * *`string`* **state**: The state that should be removed.

### has()

* `has()` allows you to check if one or more states are present on the cart.

* **Returns** `bool`

  Returns true if at least one of the passed states is present on the cart, false otherwise.

* **Arguments:**

  * *`string`* **states**: One or more strings that should be checked.

### get()

* `get()` returns all states that are present on the cart.

* **Returns** `array`

  An array containing all current states of the cart.

***

---

---
url: >-
  /docs/v6.6/resources/references/app-reference/script-reference/cart-manipulation-script-services-reference.md
---

# Cart Manipulation script services reference

## [services.cart (`Shopware\Core\Checkout\Cart\Facade\CartFacade`)](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/CartFacade.php) {#cartfacade}

The `cart` service allows you to manipulate the cart.
You can use the cart service to add line-items, change prices, add discounts, etc. to the cart.

### items()

* The `items()` method returns all line-items of the current cart for further manipulation.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemsFacade`](./cart-manipulation-script-services-reference#itemsfacade)

  A `ItemsFacade` containing all line-items in the current cart as a collection.

### products()

* The `product()` method returns all products of the current cart for further manipulation. Similar to the `items()` method, but the line-items are filtered, to only contain product line items.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ProductsFacade`](./cart-manipulation-script-services-reference#productsfacade)

  A `ProductsFacade` containing all product line-items in the current cart as a collection.

### calculate()

* The `calculate()` method recalculates the whole cart.

  Use this to get the correct prices after you made changes to the cart. Note that after calling the `calculate()` all collections (e.g. items(), products()) get new references,	so if you still hold references to things inside the cart, these are outdated after calling `calculate()`. This method will be called automatically after your cart script executed.

### price()

* The `price()` method returns the current price of the cart.

  Note that this price may be outdated, if you changed something inside the cart in your script.Use the `calculate()` method to recalculate the cart and update the price.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\CartPriceFacade`](./cart-manipulation-script-services-reference#cartpricefacade)

  The calculated price of the cart.

### errors()

* The `errors()` method returns the current errors of the cart.

  You can use it to add new errors or warning or to remove existing ones.
* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ErrorsFacade`](./cart-manipulation-script-services-reference#errorsfacade)

  A `ErrorsFacade` containing all cart errors as a collection (may be an empty collection if there are no errors).

### states()

* `states()` allows you to access the state functions of the current cart.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\StatesFacade`](./cart-manipulation-script-services-reference#statesfacade)

  A `StatesFacade` containing all cart states as a collection (maybe an empty collection if there are no states).

### discount()

* The `discount()` methods creates a new discount line-item with the given type and value.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\DiscountFacade`](./cart-manipulation-script-services-reference#discountfacade).

  Returns the newly created discount line-item.

* **Arguments:**
  * *`string`* **key**: The id for the new discount.
  * *`string`* **type**: The type of the discount, e.g. `percentage`, `absolute`
  * *`float|\PriceCollection`* **value**: The value of the discount, a float for percentage discounts or a `PriceCollection` for absolute discounts.
  * *`string`* **label**: The label of the discount line-item.

* **Examples:**
  * Add an absolute discount to the cart.

    ````
    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% if services.cart.items.count <= 0 %}
        {% return %}
    {% endif %}

    {% if services.cart.items.has('my-discount') %}
        {% return %}
    {% endif %}

    {% set price = services.cart.price.create({
        'default': { 'gross': -19.99, 'net': -19.99}
    }) %}

    {% do services.cart.discount('my-discount', 'absolute', price, 'Fancy discount') %}
    ```
    ````

  * Add a relative discount to the cart.

    ````
    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% if services.cart.has('my-discount') %}
        {% return %}
    {% endif %}

    {% do services.cart.discount('my-discount', 'percentage', -10, 'Fancy discount') %}
    ```
    ````

### surcharge()

* The `surcharge()` methods creates a new surcharge line-item with the given type and value.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\DiscountFacade`](./cart-manipulation-script-services-reference#discountfacade).

  Returns the newly created surcharge line-item.

* **Arguments:**
  * *`string`* **key**: The id for the new surcharge.
  * *`string`* **type**: The type of the surcharge, e.g. `percentage`, `absolute`
  * *`float|\PriceCollection`* **value**: The value of the surcharge, a float for percentage surcharges or a `PriceCollection` for absolute surcharges.
  * *`string`* **label**: The label of the surcharge line-item.

* **Examples:**

  * Add an absolute surcharge to the cart.#

    ````
    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% set price = services.cart.price.create({
        'default': { 'gross': 19.99, 'net': 19.99}
    }) %}

    {% do services.cart.surcharge('my-surcharge', 'absolute', price, 'Fancy surcharge') %}
    ```
    ````

  * Add a relative surcharge to the cart.

    ````
    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% if services.cart.has('my-surcharge') %}
        {% return %}
    {% endif %}

    {% do services.cart.surcharge('my-surcharge', 'percentage', -10, 'Fancy discount') %}
    ```
    ````

### get()

* `get()` returns the line-item with the given id from this collection.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade) | `null`

  The line-item with the given id, or null if it does not exist.

* **Arguments:**
  * *`string`* **id**: The id of the line-item that should be returned.

### remove()

* `remove()` removes the given line-item or the line-item with the given id from this collection.

* **Arguments:**

  * *`string|\ItemFacade`* **id**: The id of the line-item or the line-item that should be removed.

* **Examples:**

  * Add and then remove a product line-item from the cart.

    ````
    ```twig
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% do services.cart.products.remove(hook.ids.get('p1')) %}
    ```
    ````

### has()

* `has()` checks if a line-item with the given id exists in this collection.

* **Returns** `bool`

  Returns true if the given line-item or a line-item with the given id already exists in the collection, false otherwise.

* **Arguments:**

  * *`string|\ItemFacade`* **id**: The id or a line-item that should be checked if it already exists in the collection.

### count()

* `count()` returns the count of line-items in this collection.

  Note that it does only count the line-items directly in this collection and not child line-items of those.

* **Returns** `int`

  The number of line-items in this collection.

***

## [`Shopware\Core\Checkout\Cart\Facade\CartPriceFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/CartPriceFacade.php) {#cartpricefacade}

The CartPriceFacade is a wrapper around the calculated price of a cart.

### getNet()

* `getNet()` returns the net price of the cart.

* **Returns** `float`

  Returns the net price of the cart as float.

### getTotal()

* `getTotal()` returns the total price of the cart that has to be paid by the customer.

  Depending on the tax settings this may be the gross or net price. Note that this price is already rounded, to get the raw price before rounding use `getRaw()`.

* **Returns** `float`

  The rounded total price of the cart as float.

### getPosition()

* `getPosition()` returns the sum price of all line-items in the cart.

  In the position price the shipping costs are excluded. Depending on the tax settings this may be the gross or net price og the line-items.

* **Returns** `float`

  The position price as float.

### getRounded()

* Alias for `getTotal()`.

* **Returns** `float`

  The rounded total price of the cart as float.

### getRaw()

* \`getRaw() returns the total price of the cart before rounding.

* **Returns** `float`

  The total price before rounding as float.

### create()

* `create()` creates a new `PriceCollection` based on an array of prices.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Pricing\PriceCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Pricing/PriceCollection.php)

  Returns the newly created `PriceCollection`.

* **Arguments:**

  * *`array`* **price**: The prices for the new collection, indexed by the currency-id or iso-code of the currency.

* **Examples:**

  * Create a new Price in the default currency.

    ````
    ```twig
    {% set price = services.cart.price.create({
        'default': { 'gross': 19.99, 'net': 19.99}
    }) %}
    ```
    ````

***

## [`Shopware\Core\Checkout\Cart\Facade\ContainerFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/ContainerFacade.php) {#containerfacade}

The ContainerFacade allows you to wrap multiple line-items inside a container line-item.

### products()

* The `product()` method returns all products inside the current container for further manipulation.

  Similar to the `children()` method, but the line-items are filtered, to only contain product line items.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ProductsFacade`](./cart-manipulation-script-services-reference#productsfacade)

  A `ProductsFacade` containing all product line-items inside the current container as a collection.

### add()

* Use the `add()` method to add an item to this container.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade)

  The item that was added to the container.

* **Arguments:**

  * *[`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade)* **item**: The item that should be added.

* **Examples:**

  * Add a product to the container and reduce the quantity of the original line-item.

    ````
    ```twig

    ```
    ````

### getPrice()

* `getPrice()` returns the calculated price of the line-item.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\PriceFacade`](./cart-manipulation-script-services-reference#pricefacade) | `null`

  Returns the price of the line-item as a `PriceFacade` or null if the line-item has no calculated price.

### take()

* `take()` splits an existing line-item by a given quantity.

  It removes the given quantity from the existing line-item and returns a new line-item with exactly that quantity.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade) | `null`

  Returns the new line-item as an `ItemFacade` or null if taking is not possible because the line-item has no sufficient quantity.

* **Arguments:**

  * *`int`* **quantity**: The quantity that should be taken.
  * *`string` | `null`* **key**: Optional: The id of the new line-item. A random UUID will be used if none is provided.

    ```
    Default: `null`.
    ```

* **Examples:**

  * Take a quantity of 2 from an existing product line-item and add it to the cart again.

    ````
    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

    {% do services.cart.products.add(hook.ids.get('p1'), 5) %}

    {% set product = services.cart.products.get(hook.ids.get('p1')) %}

    {% set split = product.take(2, 'new-key') %}

    {% do services.cart.products.add(split) %}
    ```
    ````

### getId()

* `getId()` returns the id of the line-item.

* **Returns** `string`

  Returns the id.

### getReferencedId()

* `getReferenceId()` returns the id of the referenced entity of the line-item.

  E.g. for product line-items this will return the id of the referenced product.
* **Returns** `string` | `null`

  Returns the id of the referenced entity, or null if no entity is referenced.

### getQuantity()

* `getQuantity()` returns the quantity of the line-item.

* **Returns** `int`

  Returns the quantity.

### getLabel()

* `getLabel()` returns the translated label of the line-item.

* **Returns** `string` | `null`

  Returns the translated label, or null if none exists.

### getPayload()

* `getPayload()` returns the payload of this line-item.

* **Returns** [`Shopware\Core\Framework\Script\Facade\ArrayFacade`](./miscellaneous-script-services-reference#arrayfacade)

  Returns the payload as `ArrayFacade`.

### getChildren()

* `getChildren()` returns the child line-items of this line-item.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemsFacade`](./cart-manipulation-script-services-reference#itemsfacade)

  Returns the children as a `ItemsFacade`, that may be empty if no children exist.

### getType()

* `getType()` returns the type of this line-item.

  Possible types include `product`, `discount`, `container`, etc.
* **Returns** `string`

  The type of the line-item.

### discount()

* The `discount()` methods creates a new discount line-item with the given type and value.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\DiscountFacade`](./cart-manipulation-script-services-reference#discountfacade)

  Returns the newly created discount line-item.

* **Arguments:**

  * *`string`* **key**: The id for the new discount.
  * *`string`* **type**: The type of the discount, e.g. `percentage`, `absolute`
  * *`float|\PriceCollection`* **value**: The value of the discount, a float for percentage discounts or a `PriceCollection` for absolute discounts.
  * *`string`* **label**: The label of the discount line-item.

* **Examples:**

  * Add an absolute discount to the cart.

    ````
    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% if services.cart.items.count <= 0 %}
        {% return %}
    {% endif %}

    {% if services.cart.items.has('my-discount') %}
        {% return %}
    {% endif %}

    {% set price = services.cart.price.create({
        'default': { 'gross': -19.99, 'net': -19.99}
    }) %}

    {% do services.cart.discount('my-discount', 'absolute', price, 'Fancy discount') %}
    ```
    ````

  * Add a relative discount to the cart.

    ````
    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% if services.cart.has('my-discount') %}
        {% return %}
    {% endif %}

    {% do services.cart.discount('my-discount', 'percentage', -10, 'Fancy discount') %}
    ```
    ````

### surcharge()

* The `surcharge()` methods creates a new surcharge line-item with the given type and value.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\DiscountFacade`](./cart-manipulation-script-services-reference#discountfacade)

  Returns the newly created surcharge line-item.

* **Arguments:**
  * *`string`* **key**: The id for the new surcharge.
  * *`string`* **type**: The type of the surcharge, e.g. `percentage`, `absolute`
  * *`float|\PriceCollection`* **value**: The value of the surcharge, a float for percentage surcharges or a `PriceCollection` for absolute surcharges.
  * *`string`* **label**: The label of the surcharge line-item.

* **Examples:**

  * Add an absolute surcharge to the cart.#

    ````
    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% set price = services.cart.price.create({
        'default': { 'gross': 19.99, 'net': 19.99}
    }) %}

    {% do services.cart.surcharge('my-surcharge', 'absolute', price, 'Fancy surcharge') %}
    ```
    ````

  * Add a relative surcharge to the cart.

    ````
    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% if services.cart.has('my-surcharge') %}
        {% return %}
    {% endif %}

    {% do services.cart.surcharge('my-surcharge', 'percentage', -10, 'Fancy discount') %}
    ```
    ````

### get()

* `get()` returns the line-item with the given id from this collection.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade) | `null`

  The line-item with the given id, or null if it does not exist.

* **Arguments:**

  * *`string`* **id**: The id of the line-item that should be returned.

### remove()

* `remove()` removes the given line-item or the line-item with the given id from this collection.

* **Arguments:**

  * *`string|\ItemFacade`* **id**: The id of the line-item or the line-item that should be removed.

* **Examples:**

  * Add and then remove a product line-item from the cart.

    ````
    ```twig
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% do services.cart.products.remove(hook.ids.get('p1')) %}
    ```
    ````

### has()

* `has()` checks if a line-item with the given id exists in this collection.

* **Returns** `bool`

  Returns true if the given line-item or a line-item with the given id already exists in the collection, false otherwise.

* **Arguments:**

  * *`string|\ItemFacade`* **id**: The id or a line-item that should be checked if it already exists in the collection.

### count()

* `count()` returns the count of line-items in this collection.

  Note that it does only count the line-items directly in this collection and not child line-items of those.

* **Returns** `int`

  The number of line-items in this collection.

***

## [`Shopware\Core\Checkout\Cart\Facade\DiscountFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/DiscountFacade.php) {#discountfacade}

The DiscountFacade is a wrapper around a newly created discount.
Note that this wrapper is independent from the line-item that was added for this discount.

### getId()

* `getId()` returns the id of the line-item that was added with this discount.

* **Returns** `string`

  The id of the discount line-item.

### getLabel()

* `getLabel()` returns the translated label of the line-item that was added with this discount.

* **Returns** `string` | `null`

  The translated label of the discount line-item.

***

## [`Shopware\Core\Checkout\Cart\Facade\ErrorsFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/ErrorsFacade.php) {#errorsfacade}

The ErrorsFacade is a wrapper around the errors of a cart.
You can use it to add new errors to the cart or remove existing ones.

### error()

* The `error()` method adds a new error of type `error` to the cart.

  The error will be displayed to the user and the checkout will be blocked if at least one error was added.

* **Arguments:**

  * *`string`* **key**: The snippet-key of the message that should be displayed to the user.
  * *`string` | `null`* **id**: An optional id that can be used to reference the error, if none is provided the $key will be used as id.

    ```
    Default: `null`
    ```
  * *`array`* **parameters**: Optional: Any parameters that the snippet for the error message may need.

    ```
    Default: `array ()`
    ```

* **Examples:**

  * Add a error to the cart.

    ````
    ```twig
    {% do services.cart.errors.error('NO_PRODUCTS_IN_CART') %}
    ```
    ````

### warning()

* The `warning()` method adds a new error of type `warning` to the cart.

  The warning will be displayed to the user, but the checkout won't be blocked.

* **Arguments:**

  * *`string`* **key**: The snippet-key of the message that should be displayed to the user.
  * *`string` | `null`* **id**: An optional id that can be used to reference the error, if none is provided the $key will be used as id.

    ```
    Default: `null`
    ```
  * *`array`* **parameters**: Optional: Any parameters that the snippet for the error message may need.

    ```
    Default: `array ()`
    ```

* **Examples:**

  * Add a warning to the cart.

    ````
    ```twig
    {% do services.cart.errors.notice('YOU_SHOULD_REALLY_ADD_PRODUCTS') %}
    ```
    ````

### notice()

* The `notice()` method adds a new error of type `notice` to the cart.

  The notice will be displayed to the user, but the checkout won't be blocked.

* **Arguments:**

  * *`string`* **key**: The snippet-key of the message that should be displayed to the user.
  * *`string` | `null`* **id**: An optional id that can be used to reference the error, if none is provided the $key will be used as id.

    ```
    Default: `null`
    ```
  * *`array`* **parameters**: Optional: Any parameters that the snippet for the error message may need.

    ```
    Default: `array ()`
    ```

* **Examples:**

  * Add a notice to the cart.

    ````
    ```twig
    {% do services.cart.errors.warning('ADD_PRODUCTS_OR_GO_AWAY') %}
    ```
    ````

  * Add a notice to the cart with a custom id.

    ````
    ```twig
    {% do services.cart.errors.notice('YOU_SHOULD_REALLY_ADD_PRODUCTS', 'add-same-message') %}
    ```
    ````

  * Add a notice to the cart with parameters.

    ````
    ```twig
    {% do services.cart.errors.notice('MESSAGE_WITH_PARAMETERS', null, {'foo': 'bar'}) %}
    ```
    ````

### resubmittable()

* The `resubmittable()` method adds a new error of type `error` to the cart.

  The notice will be displayed to the user, the order will be blocked, but the user can submit the order again.

* **Arguments:**

  * *`string`* **key**: The snippet-key of the message that should be displayed to the user.

  * *`string` | `null`* **id**: An optional id that can be used to reference the error, if none is provided the $key will be used as id.

    ```
    Default: `null`
    ```

  * *`array`* **parameters**: Optional: Any parameters that the snippet for the error message may need.

    ```
    Default: `array ()`
    ```

### has()

* The `has()` method, checks if an error with a given id exists.

* **Returns** `bool`

  Returns true if an error with that key exists, false otherwise.

* **Arguments:**

  * *`string`* **id**: The id of the error that should be checked.

### remove()

* The `remove()` method removes the error with the given id.

* **Arguments:**

  * *`string`* **id**: The id of the error that should be removed.

### get()

* The `get()` method returns the error with the given id.

* **Returns** [`Shopware\Core\Checkout\Cart\Error\Error`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Error/Error.php) | `null`

  The Error with the given id, null if an error with that id does not exist.

* **Arguments:**

  * *`string`* **id**: The id of the error that should be returned.

***

## [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/ItemFacade.php) {#itemfacade}

The ItemFacade is a wrapper around one line-item.

### getPrice()

* `getPrice()` returns the calculated price of the line-item.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\PriceFacade`](./cart-manipulation-script-services-reference#pricefacade) | `null`

  Returns the price of the line-item as a `PriceFacade` or null if the line-item has no calculated price.

### take()

* `take()` splits an existing line-item by a given quantity.

  It removes the given quantity from the existing line-item and returns a new line-item with exactly that quantity.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade) | `null`

  Returns the new line-item as an `ItemFacade` or null if taking is not possible because the line-item has no sufficient quantity.

* **Arguments:**

  * *`int`* **quantity**: The quantity that should be taken.

  * *`string` | `null`* **key**: Optional: The id of the new line-item. A random UUID will be used if none is provided.

    ```
    Default: `null`
    ```

* **Examples:**

  * Take a quantity of 2 from an existing product line-item and add it to the cart again.

    ````
    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}

    {% do services.cart.products.add(hook.ids.get('p1'), 5) %}

    {% set product = services.cart.products.get(hook.ids.get('p1')) %}

    {% set split = product.take(2, 'new-key') %}

    {% do services.cart.products.add(split) %}
    ```
    ````

### getId()

* `getId()` returns the id of the line-item.

* **Returns** `string`

  Returns the id.

### getReferencedId()

* `getReferenceId()` returns the id of the referenced entity of the line-item.

  E.g. for product line-items this will return the id of the referenced product.

* **Returns** `string` | `null`

  Returns the id of the referenced entity, or null if no entity is referenced.

### getQuantity()

* `getQuantity()` returns the quantity of the line-item.

* **Returns** `int`

  Returns the quantity.

### getLabel()

* `getLabel()` returns the translated label of the line-item.

* **Returns** `string` | `null`

  Returns the translated label, or null if none exists.

### getPayload()

* `getPayload()` returns the payload of this line-item.

* **Returns** [`Shopware\Core\Framework\Script\Facade\ArrayFacade`](./miscellaneous-script-services-reference#arrayfacade)

  Returns the payload as `ArrayFacade`.

### getChildren()

* `getChildren()` returns the child line-items of this line-item.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemsFacade`](./cart-manipulation-script-services-reference#itemsfacade)

  Returns the children as a `ItemsFacade`, that may be empty if no children exist.

### getType()

* `getType()` returns the type of this line-item.

  Possible types include `product`, `discount`, `container`, etc.

* **Returns** `string`

  The type of the line-item.

***

## [`Shopware\Core\Checkout\Cart\Facade\ItemsFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/ItemsFacade.php) {#itemsfacade}

The ItemsFacade is a wrapper around a collection of line-items.

### add()

* `add()` adds a line-item to this collection.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade)

  Returns the added line-item.

* **Arguments:**

  * *[`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade)* **item**: The line-item that should be added.

* **Examples:**

  * Add an absolute discount to the cart.

    ````
    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% if services.cart.items.count <= 0 %}
        {% return %}
    {% endif %}

    {% if services.cart.items.has('my-discount') %}
        {% return %}
    {% endif %}

    {% set price = services.cart.price.create({
        'default': { 'gross': -19.99, 'net': -19.99}
    }) %}

    {% do services.cart.discount('my-discount', 'absolute', price, 'Fancy discount') %}
    ```
    ````

### get()

* `get()` returns the line-item with the given id from this collection.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade) | `null`

  The line-item with the given id, or null if it does not exist.

* **Arguments:**

  * *`string`* **id**: The id of the line-item that should be returned.

### has()

* `has()` checks if a line-item with the given id exists in this collection.

* **Returns** `bool`

  Returns true if the given line-item or a line-item with the given id already exists in the collection, false otherwise.

* **Arguments:**

  * *`string|\ItemFacade`* **id**: The id or a line-item that should be checked if it already exists in the collection.

### remove()

* `remove()` removes the given line-item or the line-item with the given id from this collection.

* **Arguments:**

  * *`string|\ItemFacade`* **id**: The id of the line-item or the line-item that should be removed.

* **Examples:**

  * Add and then remove a product line-item from the cart.

    ````
    ```twig
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% do services.cart.products.remove(hook.ids.get('p1')) %}
    ```
    ````

### count()

* `count()` returns the count of line-items in this collection.

  Note that it does only count the line-items directly in this collection and not child line-items of those.

* **Returns** `int`

  The number of line-items in this collection.

***

## [`Shopware\Core\Checkout\Cart\Facade\PriceFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/PriceFacade.php) {#pricefacade}

The PriceFacade is a wrapper around a price.

### getTotal()

* `getTotal()` returns the total price for the line-item.

* **Returns** `float`

  The total price as float.

### getUnit()

* `getUnit()` returns the unit price for the line-item.

  This is equivalent to the total price of the line-item with the quantity 1.

* **Returns** `float`

  The price per unit as float.

### getQuantity()

* `getQuantity()` returns the quantity that was used to calculate the total price.

* **Returns** `int`

  Returns the quantity.

### getTaxes()

* `getTaxes()` returns the calculated taxes of the price.

* **Returns** [`Shopware\Core\Checkout\Cart\Tax\Struct\CalculatedTaxCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Tax/Struct/CalculatedTaxCollection.php)

  Returns the calculated taxes.

### getRules()

* `getRules()` returns the tax rules that were used to calculate the price.

* **Returns** [`Shopware\Core\Checkout\Cart\Tax\Struct\TaxRuleCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Tax/Struct/TaxRuleCollection.php)

  Returns the tax rules.

### change()

* `change()` allows a price overwrite of the current price scope. The provided price will be recalculated
  over the quantity price calculator to consider quantity, tax rule and cash rounding configurations.

* **Arguments:**

  * *[`Shopware\Core\Framework\DataAbstractionLayer\Pricing\PriceCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Pricing/PriceCollection.php)* **price**: The provided price can be a fetched price from the database or generated over the `PriceFactory` statically.

* **Examples:**

  * Overwrite prices with a static defined collection

    ````
    ```twig
    {% do product.calculatedPrices.change([
        { to: 20, price: services.price.create({ 'default': { 'gross': 15, 'net': 15} }) },
        { to: 30, price: services.price.create({ 'default': { 'gross': 10, 'net': 10} }) },
        { to: null, price: services.price.create({ 'default': { 'gross': 5, 'net': 5} }) },
    ]) %}
    ```
    ````

### plus()

* `plus()` allows a price addition of the current price scope. The provided price will be recalculated via the quantity price calculator.

  The provided price is interpreted as a unit price and will be added to the current unit price. The total price is calculated afterwards considering quantity, tax rule and cash rounding configurations.

* **Arguments:**

  * *[`Shopware\Core\Framework\DataAbstractionLayer\Pricing\PriceCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Pricing/PriceCollection.php)* **price**: The provided price can be a fetched price from the database or generated over the `PriceFactory` statically.

* **Examples:**

  * Plus a static defined price to the existing calculated price

    ````
    ```twig
    {% set price = services.price.create({
        'default': { 'gross': 1.5, 'net': 1.5}
    }) %}

    {% do product.calculatedPrice.plus(price) %}
    ```
    ````

### minus()

* `minus()` allows a price subtraction of the current price scope. The provided price will be recalculated via the quantity price calculator.

  The provided price is interpreted as a unit price and will reduce to the current unit price. The total price is calculated afterwards considering quantity, tax rule and cash rounding configurations.

* **Arguments:**

  * *[`Shopware\Core\Framework\DataAbstractionLayer\Pricing\PriceCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Pricing/PriceCollection.php)* **price**: The provided price can be a fetched price from the database or generated over the `PriceFactory` statically.

* **Examples:**

  * Minus a static defined price to the existing calculated price

    ````
    ```twig
    {% set price = services.price.create({
        'default': { 'gross': 1.5, 'net': 1.5}
    }) %}

    {% do product.calculatedPrice.minus(price) %}
    ```
    ````

### discount()

* `discount()` allows a percentage discount calculation of the current price scope. The provided value will be ensured to be negative via `abs(value) * -1`.

  The provided discount is interpreted as a percentage value and will be applied to the unit price and the total price as well.

* **Arguments:**

  * *`float`* **value**: The percentage value of the discount. The value will be ensured to be negative via `abs(value) * -1`.

* **Examples:**

  * Adds a 10% discount to the existing calculated price

    ````
    ```twig
    {% do product.calculatedPrice.discount(10) %}
    ```
    ````

### surcharge()

* `surcharge()` allows a percentage surcharge calculation of the current price scope. The provided value will be ensured to be negative via `abs(value)`.

  The provided surcharge is interpreted as a percentage value and will be applied to the unit price and the total price as well.

* **Arguments:**

  * *`float`* **value**: The percentage value of the surcharge. The value will be ensured to be negative via `abs(value)`.

* **Examples:**

  * Adds a 10% surcharge to the existing calculated price

    ````
    ```twig
    {% do product.calculatedPrice.surcharge(10) %}
    ```
    ````

### create()

* `create()` creates a new `PriceCollection` based on an array of prices.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Pricing\PriceCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Pricing/PriceCollection.php)

  Returns the newly created `PriceCollection`.

* **Arguments:**

  * *`array`* **price**: The prices for the new collection, indexed by the currency-id or iso-code of the currency.

* **Examples:**

  * Create a new Price in the default currency.

    ````
    ```twig
    {% set price = services.cart.price.create({
        'default': { 'gross': 19.99, 'net': 19.99}
    }) %}
    ```
    ````

***

## [services.price (`Shopware\Core\Checkout\Cart\Facade\PriceFactory`)](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/PriceFactory.php) {#pricefactory}

The PriceFacade is a wrapper around a price.

### create()

* `create()` creates a new `PriceCollection` based on an array of prices.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Pricing\PriceCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Pricing/PriceCollection.php)

  Returns the newly created `PriceCollection`.

* **Arguments:**

  * *`array`* **prices**: The prices for the new collection, indexed by the currency-id or iso-code of the currency.

* **Examples:**

  * Create a new Price in the default currency.

    ````
    ```twig
    {% set price = services.cart.price.create({
        'default': { 'gross': 19.99, 'net': 19.99}
    }) %}
    ```
    ````

***

## [`Shopware\Core\Checkout\Cart\Facade\ProductsFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/ProductsFacade.php) {#productsfacade}

The ProductsFacade is a wrapper around a collection of product line-items.

### get()

* `get()` returns the product line-item with the given product id.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade) | `null`

  The line-item associated with the given product id, or null if it does not exist.

* **Arguments:**

  * *`string`* **productId**: The id of the product, of which the line-item should be returned.

* **Examples:**

  * Get a product line-item by id.

    ````
    ```twig
    {% set product = services.cart.products.get(hook.ids.get('p1')) %}
    ```
    ````

### add()

* `add()` adds a new product  line-item to this collection.

  In the case only a product id is provided it will create a new line-item from type product for the given product id.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade)

  The newly added product line-item.

* **Arguments:**

  * *`string|\LineItem|\ItemFacade`* **product**: The product that should be added. Either an existing `ItemFacade` or `LineItem` or alternatively the id of a product.

  * *`int`* **quantity**: Optionally provide the quantity with which the product line-item should be created, defaults to 1.

    ```
    Default: `1`
    ```

* **Examples:**

  * Add a product to the cart by id.

    ````
    ```twig
    {% do services.cart.products.add(hook.ids.get('p1')) %}
    ```
    ````

### create()

* `create()` creates a new product line-item for the product with the given id in the given quantity.

  Note that the created line-item will not be added automatically to this collection, use `add()` for that.

* **Returns** [`Shopware\Core\Checkout\Cart\Facade\ItemFacade`](./cart-manipulation-script-services-reference#itemfacade)

  The newly created product line-item.

* **Arguments:**

  * *`string`* **productId**: The product id for which a line-item should be created.
  * *`int`* **quantity**: Optionally provide the quantity with which the product line-item should be created, defaults to 1.

    ```
    Default: `1`
    ```

### remove()

* `remove()` removes the given line-item or the line-item with the given id from this collection.

* **Arguments:**

  * *`string|\ItemFacade`* **id**: The id of the line-item or the line-item that should be removed.

* **Examples:**

  * Add and then remove a product line-item from the cart.

    ````
    ```twig
    {% do services.cart.products.add(hook.ids.get('p1')) %}

    {% do services.cart.products.remove(hook.ids.get('p1')) %}
    ```
    ````

### has()

* `has()` checks if a line-item with the given id exists in this collection.

* **Returns** `bool`

  Returns true if the given line-item or a line-item with the given id already exists in the collection, false otherwise.

* **Arguments:**

  * *`string|\ItemFacade`* **id**: The id or a line-item that should be checked if it already exists in the collection.

### count()

* `count()` returns the count of line-items in this collection.

  Note that it does only count the line-items directly in this collection and not child line-items of those.

* **Returns** `int`

  The number of line-items in this collection.

***

## [`Shopware\Core\Checkout\Cart\Facade\StatesFacade`](https://github.com/shopware/shopware/blob/trunk/src/Core/Checkout/Cart/Facade/StatesFacade.php) {#statesfacade}

The StatesFacade allows access to the current cart states and functions.

### add()

* `add()` allows you to add one or multiple states as string values to the cart.

  This can be useful to check if your script did already run and did some manipulations to the cart.

* **Arguments:**

  * *`string`* **states**: One or more strings that will be stored on the cart.

### remove()

* `remove()` removes the given state from the cart, if it existed.

* **Arguments:**

  * *`string`* **state**: The state that should be removed.

### has()

* `has()` allows you to check if one or more states are present on the cart.

* **Returns** `bool`

  Returns true if at least one of the passed states is present on the cart, false otherwise.

* **Arguments:**

  * *`string`* **states**: One or more strings that should be checked.

### get()

* `get()` returns all states that are present on the cart.

* **Returns** `array`

  An array containing all current states of the cart.

***

---

---
url: /docs/v6.5/resources/guidelines/code/cart-process.md
---

# Cart Process

* Within `\Shopware\Core\Checkout\Cart\CartProcessorInterface::process`, no queries may be executed because this method is executed several times in a row to resolve the dependencies of the elements in the shopping cart.
* The `\Shopware\Core\Checkout\Cart\CartDataCollectorInterface::collect` method must always check if the required data has already been loaded. This is to avoid having to execute unnecessarily many queries on the database. The loaded data will be appended to the passed *CartDataCollection*.
* The creation of line items must always take place via a `LineItemFactoryHandler` class.
* All price calculations must take place via an appropriate `PriceCalculator`. All price calculators are stored inside the `Shopware\Core\Checkout\Cart\Price` class.
* All shopping cart functions must be mapped via a corresponding store API route. The routes are located in the `Shopware\Core\Checkout\Cart\SalesChannel` namespace.

---

---
url: /docs/v6.6/resources/guidelines/code/cart-process.md
---

# Cart Process

* Within `\Shopware\Core\Checkout\Cart\CartProcessorInterface::process`, no queries may be executed because this method is executed several times in a row to resolve the dependencies of the elements in the shopping cart.
* The `\Shopware\Core\Checkout\Cart\CartDataCollectorInterface::collect` method must always check if the required data has already been loaded. This is to avoid having to execute unnecessarily many queries on the database. The loaded data will be appended to the passed *CartDataCollection*.
* The creation of line items must always take place via a `LineItemFactoryHandler` class.
* All price calculations must take place via an appropriate `PriceCalculator`. All price calculators are stored inside the `Shopware\Core\Checkout\Cart\Price` class.
* All shopping cart functions must be mapped via a corresponding store API route. The routes are located in the `Shopware\Core\Checkout\Cart\SalesChannel` namespace.

---

---
url: /docs/guides/hosting/performance/cart-storage.md
---

# Cart Storage

By default, Shopware stores the cart in the database.
This can be a performance bottleneck in scenarios where high throughput is required (e.g., thousands of orders per minute), especially if a DB cluster with a read/write-split is used.
Additionally, as the content in that table can change quite quickly, it can lead to an explosion of the databases `binlog` file.

Redis is better suited in high-throughput scenarios, therefore you should use Redis as storage for the cart in such scenarios.

## Using Redis as storage

To use Redis, create a `config/packages/shopware.yml` file with the following content:

```yaml
shopware:
  cart:
    redis_url: 'redis://host:port/dbindex?persistent=1'
```

```yaml
shopware:
    redis:
        connections:
            persistent:
                dsn: 'redis://host:port/dbindex?persistent=1'
    cart:
        storage:
            type: 'redis'
            config:
                 connection: 'persistent'
```

Note that the `?persistent=1` parameter here refers to the connection pooling, not the persistent storage of data.
Using a persistent Redis connection is recommended to avoid connection issues in high-load scenarios.
Please refer to the [Redis configuration guide](../infrastructure/redis) for more information.\*

There is also a `cart:migrate` command to migrate the existing carts between MySQL and Redis, so the migration does not influence end-user experience.

## Migrating between storages

You can migrate the current carts from the DB to Redis by running the following CLI command:

```shell
bin/console cart:migrate {fromStorage} {redisUrl?}
```

::: info
Providing the redis URL is optional.
If not provided, the value from the configuration will be used.
If it is not configured in the yaml file, you need to provide the URL.
:::

For example, if you want to migrate from the default `SQL` storage to the high-performing `Redis` storage, the command is:

```shell
bin/console cart:migrate sql
```

## Redis configuration

As the information stored here is durable and should be persistent, even in the case of a Redis restart, it is recommended to configure the used Redis instance that it will not just keep the data in memory, but also store it on the disk.
This can be done by using snapshots (RDB) and Append Only Files (AOF), refer to the [Redis docs](https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/) for details.

As key eviction policy you should use `volatile-lru`, which only automatically deletes carts that are expired, as otherwise you might risk of losing data.
For a detailed overview of Redis key eviction policies see the [Redis docs](https://redis.io/docs/latest/develop/reference/eviction/).

---

---
url: /docs/v6.6/guides/hosting/performance/cart-storage.md
---

# Cart Storage

By default, shopware stores the cart in the database. This can be a performance bottleneck in scenarios where high throughput is required (e.g., thousands of orders per minute), especially if a DB cluster with a read/write-split is used.
Additionally, as the content in that table can change quite quickly, it can lead to an explosion of the databases `binlog` file.

Redis is better suited in high-throughput scenarios, therefore you should use Redis as storage for the cart in such scenarios.

## Using Redis as storage

To use Redis, create a `config/packages/shopware.yml` file with the following content:

```yaml
shopware:
  cart:
    redis_url: 'redis://host:port/dbindex?persistent=1'
```

```yaml
shopware:
    redis:
        connections:
            persistent:
                dsn: 'redis://host:port/dbindex?persistent=1'
    cart:
        storage:
            type: 'redis'
            config:
                 connection: 'persistent'
```

## Migrating between storages

You can migrate the current carts from the DB to Redis by running the following CLI command:

```shell
bin/console cart:migrate {fromStorage} {redisUrl?}
```

::: info
Providing the redis URL is optional. If not provided, the value from the configuration will be used. If it is not configured in the yaml file, you need to provide the URL.
:::

For example, if you want to migrate from the default `SQL` storage to the high-performing `Redis` storage, the command is:

```shell
bin/console cart:migrate sql
```

## Redis configuration

As the information stored here is durable and should be persistent, even in the case of a Redis restart, it is recommended to configure the used Redis instance that it will not just keep the data in memory, but also store it on the disk. This can be done by using snapshots (RDB) and Append Only Files (AOF), refer to the [Redis docs](https://redis.io/docs/latest/operate/oss_and_stack/management/persistence/) for details.

As key eviction policy you should use `volatile-lru`, which only automatically deletes carts that are expired, as otherwise you might risk of losing data. For a detailed overview of Redis key eviction policies see the [Redis docs](https://redis.io/docs/latest/develop/reference/eviction/).

---

---
url: /docs/concepts/commerce/catalog.md
---

# Catalog

In this section, we will go through the structure that organizes products, prices and everything related to maintaining a **product catalog** within the store.

First, let us understand about products and how they are defined.

---

---
url: /docs/v6.5/concepts/commerce/catalog.md
---

# Catalog

In this section, we will go through the structure that organizes products, prices and everything related to maintaining a **product catalog** within the store.

First, let us understand about products and how they are defined.

---

---
url: /docs/v6.6/concepts/commerce/catalog.md
---

# Catalog

In this section, we will go through the structure that organizes products, prices and everything related to maintaining a **product catalog** within the store.

First, let us understand about products and how they are defined.

---

---
url: /docs/v6.5/resources/references/adr/2023-09-22-catalog-import-api.md
---

# Catalog Import API

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2023-09-22-catalog-import-api.md)
:::

## Context

Our current API for importing entities is very flexible,
however:

* The documentation is lackluster and brittle due to the fact that the schema maps directly to the databases.
* This exposure of implementation details leads to issues documenting the api but also using it as certain fields and entities are just bookkeeping.
* The size and complexity of the current schema make it impossible to generate clients or mappers for it.
* Variants and Media uploads have to be fully managed by the client
* The api puts the effort of error handling onto the client

Resulting in increased effort to build and maintain middlewares.

We want to provide an HTTP API and a PHP API for importing catalog related entities independent of the database schema.
And reduce the amount of implementation details developers have to know about when integrating Shopware within existing
systems e.g., ProductVisibility, ProductMedia Entities, Media creation, errors, etc.

## Decision

We will introduce a new PHP Layer for importing catalog entities. It will:

* Evolve independently of the current database schema
* Be strongly typed
* Support referencing associations by different fields (eg assign tax by name instead of id)
* Be simpler to import images and generate variants
* Support asynchronous importing
* Have advanced error handling and reporting

We will expose this new PHP layer over an HTTP API with full Open API specifications.

## Consequences

We will first release an @experimental feature with a very limited scope, a minimal data set.
We will not support the full breadth of options available to the catalog system.

This will allow us to gather feedback, make changes and provide a well-designed system.

### API Overview

**PHP api**

```php
// for the structure of $myProductData see: Appendix A
function myMigration(array $myProductData)
{

    $productBatch = ProductBatch::fromRequestData($myProductData);
    $session = $this->importFactory->startSession('my-import');
    $session->addProductRecords($productBatch);
    $session->commit();
    // not required, as import runs async
    while(!$session->done()) {
        echo $session->status();
    }
}
```

**REST api**

This API is exposed as the following HTTP endpoints:

### Starting an import

`POST /api/import/catalog/start`:

This creates an import return a unique identifier to the import. This endpoint accepts a configuration payload, allowing you to customize the import, for example:

* The name of the import, eg `product-import-202307012`
* The indexing configuration
* Reporting webhooks for errors
* And so on

### Creating/Updating entities

`POST /api/import/{{import_id}}/record`:

#### Examples

* [Create a product with a new media](../../../assets/adr/catalog-import/examples#create-a-product-with-a-new-media)
* [Update a product and update its media](../../../assets/adr/catalog-import/examples#update-a-product-and-update-its-media)
* [Create a category and assign products to it](../../../assets/adr/catalog-import/examples#create-a-category-and-assign-products-to-it)
* [Create a product with a custom entity](../../../assets/adr/catalog-import/examples#create-a-product-with-a-custom-entity)
* [Update a custom entity](../../../assets/adr/catalog-import/examples#update-a-custom-entity)

This endpoint is used to create and update entities. The data is stored for later import, specifically during the `commit` http call.

Note: They will not be imported in to the system yet.

This stage takes care of resolving specific associations and existence checks.

It is important to note that while it is possible to create nested entities, it is not possible to update them via the parent entity. Updates should be performed on the root level.

For example: you can create a product with nested media. If you want to update the media, you must do it at the root level, by referencing the entity directly (by its ID or any resolvers the entity supports).

This stage will also extract some inline records, for example, media records specified directly on the product and create separate records for them.
After that process, we will sort records based on their dependencies, to optimize for bulk inserts. This is only performed for entities which should be created.

Custom entities can also be added and updated in the same manner as normal entities, however, they must be defined under the `extensions` key due to the fact that the schema is not known ahead of time. See above examples relating to custom entities.

For example, consider the following record set:

```
├── Product 1
│   ├── Tax 1
│   ├── Media 1
│   ├── Media 2
├── Product 2
│   ├── Tax 2
│   ├── Media 3
```

The entities will be assigned a level value like so:

| Entity    | Level |
|-----------|-------|
| Tax 1     | 1     |
| Tax 2     | 1     |
| Media 1   | 1     |
| Media 2   | 1     |
| Media 3   | 1     |
| Product 1 | 0     |
| Product 2 | 0     |

With this data, we can decide which records can be processed at the same time. The highest level has no dependencies. In this case, level 1. All of those records can be processed at the same time. Once done, the next level can be processed.

The records will be saved into a simple intermediate store, in a generic structure, not related to the database or DAL.

The store will either be something like redis or mysql. Regardless, this store will be behind an interface and will be exchangeable.

You can push as many records to this end point as you wish. When you are done, you call the commit endpoint.

Calling 'record' is not possible after an import has been committed. An error will be returned.

### Deleting entities

`POST /api/import/{{import_id}}/record/delete`:

#### Examples

* [Delete a product & media](../../../assets/adr/catalog-import/examples#delete-a-product-and-media)

This endpoint is used to delete entities from the system, as with POST calls to the `/record` endpoint, the deletions are only queued. They delete will happen during the `/commit` call.

The payload is a simple array of entities with an array of ID's to delete.

### Unassigning nested entities

`POST /api/import/{{import_id}}/record/unassign`:

#### Examples

* [Un-assign a media from a product](../../../assets/adr/catalog-import/examples#un-assign-a-media-from-a-product)

This endpoint is used to remove entity associations.

### Committing an import

`POST /api/import/{{import_id}}/commit`

This endpoint is used to commit the records and begin the actual import into Shopware.

As previously noted, records will be batched by workers according to their level, traversing from the highest level to the lowest. During this process, the generic record structure will be mapped to the expected DAL structure.

Internally, the sync API will be used to perform the actual "inserts".

Calling commit can only be performed once. Any subsequent commits will return an error.

### Getting the status of an import

`POST /api/import/{{import_id}}/status`

This endpoint returns the status of the import.

Subsequent calls to the status end point will return the current status of the import and errors reported so far.

The status will be reported as one of `started`, `importing`, `cancelled` or `done`.

When the import is finished, `status` will be reported as `done`, and all the errors will be included and the duration and totals will reflect the total imported.

### Cancelling an import

`POST /api/import/{{import_id}}/cancel`

This endpoint cancels a non-committed import. It's not possible to cancel an already committed import.

Cancelling an import will delete all records pushed to it. This might be useful in case some erroneous data was pushed to the import.

### Http Schema

[Openapi schema](../../../assets/adr/catalog-import/import-http-schema.yml)

### Resolver Concept

When associating records, it will be possible to specify the ID of the association, for example, when you want to assign a tax entity to a product, you can pass the tax ID.

The problem here is that you may not know, or want to keep a record of the referenced entity ID.

We will introduce the concept of Resolvers to solve this problem.

The job of a resolver is to look for references to its entities (in this case Tax) and resolve any of them which are not ID references, to ID references.

In the initial experimental release, we will ship with a minimal set of reference resolvers to prove the concept. We will also explore how we can open it up for extension developers to provide reference resolvers and have them automatically integrated with the API specification.

## Media Uploading

In the first iteration, we will only support uploading media files from an external URL. The image will be downloaded during import.

We will still honor the configuration setting `media.enable_url_upload_feature`. If the config is disabled, the import will skip importing media.

## Error handling

### Whilst adding import records

Whilst adding import instructions via the '/record' endpoints, errors will be directly reported to you regarding resolving. For example, if you try to update an entity which does not exist. Or assign an entity to another that does not exist.

See [Error Response: Resolving Root Entities](../../../assets/adr/catalog-import/examples#error-response-resolving-root-entities) for the request and response when trying to update a product which does not exist.

When a nested entity does not exist, the error is reported under the root entity. When an error occurs in a nested entity, the root entity will not be updated.

See [Error Response: Resolving Nested Entities](../../../assets/adr/catalog-import/examples#error-response-resolving-nested-entities) for the request and response when trying to assign products which do not exist to a category.

### Whilst committing

* When an error occurs created a nested entity, the root entity will also fail, it will not be updated.
* When a root entity cannot be updated or created, all nested entities will be deleted. Note that it is not possible to update nested entities, so there is no issue with rolling back nested entities to their previous state.

See [Error Response Status Root](../../../assets/adr/catalog-import/examples#error-response-status-root) for the request and response when trying to create a product with a not unique product number.
See [Error Response Status Nested](../../../assets/adr/catalog-import/examples#error-response-status-nested) for the request and response when trying to create a product with a media which cannot be downloaded.

## Error reporting

Errors will be reported in real time to a given webhook URL, or via the `status` end point under the error key. The properties are described in the `Failure` object of the API specification.

Note: the webhook will not be implemented in the first draft and the general concept is open for discussion.

The errors will be keyed by the id of the entity given during the `record` endpoint.

Errors will be classified with a severity using the levels from [RFC5424](https://datatracker.ietf.org/doc/html/rfc5424).

# Appendix

## Appendix A: An example PHP payload to import a product with categories, media and tax records.

```php
$myProductData = [
        [
            'id' => '018a6b222b5a734d956fb03dda765bf8',
            'name' => 'Cool Prod 1',
            'productNumber' => 'COOLPROD1',
            'tax' => [
                'name' => 'Reduced rate 2', //The tax record is referenced via its name attribute instead of its ID
            ],
            'prices' => [
                [
                    'currency' => 'EUR',
                    'gross' => 15,
                    'net' => 10,
                    'linked' => false,
                ],
            ],
            'stock' => '100',
            'categories' => [
                [
                    'path' => ['Home', 'Category 2', 'Category 3'], //The product will be assigned to the category: Home/Category 2/Category 3
                ],
            ],
            'media' => [
                [
                    //this image will be downloaded and assigned to a media record, and then assigned to the product
                    'url' => 'https://images.unsplash.com/photo-1660236822651-4263beb35fa8?ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D&auto=format&fit=crop&w=1170&q=80',
                    'title' => 'pommes',
                    'alt' => 'alt',
                    'filename' => 'other-media.jpg',
                ],
            ],
        ],
    ];
```

---

---
url: >-
  /docs/v6.6/resources/references/adr/_superseded/2023-09-22-catalog-import-api.md
---

# Catalog Import API

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/_superseded/2023-09-22-catalog-import-api.md)
:::

## Superseded as this "project" was aborted as a lot of further issues came up while working on this approach.

## Context

Our current API for importing entities is very flexible,
however:

* The documentation is lackluster and brittle due to the fact that the schema maps directly to the databases.
* This exposure of implementation details leads to issues documenting the api but also using it as certain fields and entities are just bookkeeping.
* The size and complexity of the current schema make it impossible to generate clients or mappers for it.
* Variants and Media uploads have to be fully managed by the client
* The api puts the effort of error handling onto the client

Resulting in increased effort to build and maintain middlewares.

We want to provide an HTTP API and a PHP API for importing catalog related entities independent of the database schema.
And reduce the amount of implementation details developers have to know about when integrating Shopware within existing
systems e.g., ProductVisibility, ProductMedia Entities, Media creation, errors, etc.

## Decision

We will introduce a new PHP Layer for importing catalog entities. It will:

* Evolve independently of the current database schema
* Be strongly typed
* Support referencing associations by different fields (eg assign tax by name instead of id)
* Be simpler to import images and generate variants
* Support asynchronous importing
* Have advanced error handling and reporting

We will expose this new PHP layer over an HTTP API with full Open API specifications.

## Consequences

We will first release an @experimental feature with a very limited scope, a minimal data set.
We will not support the full breadth of options available to the catalog system.

This will allow us to gather feedback, make changes and provide a well-designed system.

### API Overview

**PHP api**

```php
// for the structure of $myProductData see: Appendix A
function myMigration(array $myProductData)
{

    $productBatch = ProductBatch::fromRequestData($myProductData);
    $session = $this->importFactory->startSession('my-import');
    $session->addProductRecords($productBatch);
    $session->commit();
    // not required, as import runs async
    while(!$session->done()) {
        echo $session->status();
    }
}
```

**REST api**

This API is exposed as the following HTTP endpoints:

### Starting an import

`POST /api/import/catalog/start`:

This creates an import return a unique identifier to the import. This endpoint accepts a configuration payload, allowing you to customize the import, for example:

* The name of the import, eg `product-import-202307012`
* The indexing configuration
* Reporting webhooks for errors
* And so on

### Creating/Updating entities

`POST /api/import/{{import_id}}/record`:

#### Examples

* [Create a product with a new media](../../../assets/adr/catalog-import/examples#create-a-product-with-a-new-media)
* [Update a product and update its media](../../../assets/adr/catalog-import/examples#update-a-product-and-update-its-media)
* [Create a category and assign products to it](../../../assets/adr/catalog-import/examples#create-a-category-and-assign-products-to-it)
* [Create a product with a custom entity](../../../assets/adr/catalog-import/examples#create-a-product-with-a-custom-entity)
* [Update a custom entity](../../../assets/adr/catalog-import/examples#update-a-custom-entity)

This endpoint is used to create and update entities. The data is stored for later import, specifically during the `commit` http call.

Note: They will not be imported in to the system yet.

This stage takes care of resolving specific associations and existence checks.

It is important to note that while it is possible to create nested entities, it is not possible to update them via the parent entity. Updates should be performed on the root level.

For example: you can create a product with nested media. If you want to update the media, you must do it at the root level, by referencing the entity directly (by its ID or any resolvers the entity supports).

This stage will also extract some inline records, for example, media records specified directly on the product and create separate records for them.
After that process, we will sort records based on their dependencies, to optimize for bulk inserts. This is only performed for entities which should be created.

Custom entities can also be added and updated in the same manner as normal entities, however, they must be defined under the `extensions` key due to the fact that the schema is not known ahead of time. See above examples relating to custom entities.

For example, consider the following record set:

```
├── Product 1
│   ├── Tax 1
│   ├── Media 1
│   ├── Media 2
├── Product 2
│   ├── Tax 2
│   ├── Media 3
```

The entities will be assigned a level value like so:

| Entity    | Level |
|-----------|-------|
| Tax 1     | 1     |
| Tax 2     | 1     |
| Media 1   | 1     |
| Media 2   | 1     |
| Media 3   | 1     |
| Product 1 | 0     |
| Product 2 | 0     |

With this data, we can decide which records can be processed at the same time. The highest level has no dependencies. In this case, level 1. All of those records can be processed at the same time. Once done, the next level can be processed.

The records will be saved into a simple intermediate store, in a generic structure, not related to the database or DAL.

The store will either be something like redis or mysql. Regardless, this store will be behind an interface and will be exchangeable.

You can push as many records to this end point as you wish. When you are done, you call the commit endpoint.

Calling 'record' is not possible after an import has been committed. An error will be returned.

### Deleting entities

`POST /api/import/{{import_id}}/record/delete`:

#### Examples

* [Delete a product & media](../../../assets/adr/catalog-import/examples#delete-a-product-and-media)

This endpoint is used to delete entities from the system, as with POST calls to the `/record` endpoint, the deletions are only queued. They delete will happen during the `/commit` call.

The payload is a simple array of entities with an array of ID's to delete.

### Unassigning nested entities

`POST /api/import/{{import_id}}/record/unassign`:

#### Examples

* [Un-assign a media from a product](../../../assets/adr/catalog-import/examples#un-assign-a-media-from-a-product)

This endpoint is used to remove entity associations.

### Committing an import

`POST /api/import/{{import_id}}/commit`

This endpoint is used to commit the records and begin the actual import into Shopware.

As previously noted, records will be batched by workers according to their level, traversing from the highest level to the lowest. During this process, the generic record structure will be mapped to the expected DAL structure.

Internally, the sync API will be used to perform the actual "inserts".

Calling commit can only be performed once. Any subsequent commits will return an error.

### Getting the status of an import

`POST /api/import/{{import_id}}/status`

This endpoint returns the status of the import.

Subsequent calls to the status end point will return the current status of the import and errors reported so far.

The status will be reported as one of `started`, `importing`, `cancelled` or `done`.

When the import is finished, `status` will be reported as `done`, and all the errors will be included and the duration and totals will reflect the total imported.

### Cancelling an import

`POST /api/import/{{import_id}}/cancel`

This endpoint cancels a non-committed import. It's not possible to cancel an already committed import.

Cancelling an import will delete all records pushed to it. This might be useful in case some erroneous data was pushed to the import.

### Http Schema

[Openapi schema](../../../assets/adr/catalog-import/import-http-schema.yml)

### Resolver Concept

When associating records, it will be possible to specify the ID of the association, for example, when you want to assign a tax entity to a product, you can pass the tax ID.

The problem here is that you may not know, or want to keep a record of the referenced entity ID.

We will introduce the concept of Resolvers to solve this problem.

The job of a resolver is to look for references to its entities (in this case Tax) and resolve any of them which are not ID references, to ID references.

In the initial experimental release, we will ship with a minimal set of reference resolvers to prove the concept. We will also explore how we can open it up for extension developers to provide reference resolvers and have them automatically integrated with the API specification.

## Media Uploading

In the first iteration, we will only support uploading media files from an external URL. The image will be downloaded during import.

We will still honor the configuration setting `media.enable_url_upload_feature`. If the config is disabled, the import will skip importing media.

## Error handling

### Whilst adding import records

Whilst adding import instructions via the '/record' endpoints, errors will be directly reported to you regarding resolving. For example, if you try to update an entity which does not exist. Or assign an entity to another that does not exist.

See [Error Response: Resolving Root Entities](../../../assets/adr/catalog-import/examples#error-response-resolving-root-entities) for the request and response when trying to update a product which does not exist.

When a nested entity does not exist, the error is reported under the root entity. When an error occurs in a nested entity, the root entity will not be updated.

See [Error Response: Resolving Nested Entities](../../../assets/adr/catalog-import/examples#error-response-resolving-nested-entities) for the request and response when trying to assign products which do not exist to a category.

### Whilst committing

* When an error occurs created a nested entity, the root entity will also fail, it will not be updated.
* When a root entity cannot be updated or created, all nested entities will be deleted. Note that it is not possible to update nested entities, so there is no issue with rolling back nested entities to their previous state.

See [Error Response Status Root](../../../assets/adr/catalog-import/examples#error-response-status-root) for the request and response when trying to create a product with a not unique product number.
See [Error Response Status Nested](../../../assets/adr/catalog-import/examples#error-response-status-nested) for the request and response when trying to create a product with a media which cannot be downloaded.

## Error reporting

Errors will be reported in real time to a given webhook URL, or via the `status` end point under the error key. The properties are described in the `Failure` object of the API specification.

Note: the webhook will not be implemented in the first draft and the general concept is open for discussion.

The errors will be keyed by the id of the entity given during the `record` endpoint.

Errors will be classified with a severity using the levels from [RFC5424](https://datatracker.ietf.org/doc/html/rfc5424).

# Appendix

## Appendix A: An example PHP payload to import a product with categories, media and tax records.

```php
$myProductData = [
        [
            'id' => '018a6b222b5a734d956fb03dda765bf8',
            'name' => 'Cool Prod 1',
            'productNumber' => 'COOLPROD1',
            'tax' => [
                'name' => 'Reduced rate 2', //The tax record is referenced via its name attribute instead of its ID
            ],
            'prices' => [
                [
                    'currency' => 'EUR',
                    'gross' => 15,
                    'net' => 10,
                    'linked' => false,
                ],
            ],
            'stock' => '100',
            'categories' => [
                [
                    'path' => ['Home', 'Category 2', 'Category 3'], //The product will be assigned to the category: Home/Category 2/Category 3
                ],
            ],
            'media' => [
                [
                    //this image will be downloaded and assigned to a media record, and then assigned to the product
                    'url' => 'https://images.unsplash.com/photo-1660236822651-4263beb35fa8?ixlib=rb-4.0.3&ixid=M3wxMjA3fDB8MHxwaG90by1wYWdlfHx8fGVufDB8fHx8fA%3D%3D&auto=format&fit=crop&w=1170&q=80',
                    'title' => 'pommes',
                    'alt' => 'alt',
                    'filename' => 'other-media.jpg',
                ],
            ],
        ],
    ];
```

---

---
url: /docs/concepts/commerce/catalog/categories.md
---

# Categories

Categories in Shopware organize products, drive storefront navigation, and define SEO-relevant URLs. The entire catalog lives in one category tree, and every sales channel chooses entry points inside that tree. For how to use the Admin UI, see the [user documentation on categories](https://docs.shopware.com/en/shopware-6-en/catalogues/categories) and [Dynamic Product Groups](https://docs.shopware.com/en/shopware-6-de/Catalogues/Dynamicproductgroups). This page focuses on developer details.

![category](../../../assets/concept-categories.png)

## Category model and tree

* Each category stores `parentId`, `path`, and `level` to build breadcrumbs, infer inheritance, and traverse efficiently.
* Flags:
  * `active` determines whether the category participates in navigation and listings.
  * `visible` and `hideInNavigation` control menu rendering without disabling the category entirely.
* Types:
  * `page`: regular category (listing or landing page).
  * `folder`: structuring element; not rendered as a page and typically used to group children.
  * `link`: redirects to an external URL or internal static link.

## Entity associations and database schema

```mermaid
erDiagram
    CATEGORY ||--o{ CATEGORY_TRANSLATION : translations
    CATEGORY }o--|| CMS_PAGE : cms_page
    CATEGORY }o--|| PRODUCT_STREAM : product_stream
    CATEGORY ||--o{ PRODUCT_CATEGORY : products
    PRODUCT ||--o{ PRODUCT_CATEGORY : categories
    SALES_CHANNEL }o--|| CATEGORY : navigation_roots
    CATEGORY ||--o{ SEO_URL : seo_urls
```

* `category`: tree structure plus `cmsPageId` for layout inheritance; `productAssignmentType` controls explicit vs. stream-based listings.
* `category_translation`: localized names, breadcrumbs, links, and SEO text.
* `product_category`: explicit product links used for listings when not driven by a product stream.
* `product_stream`: dynamic filters attached to a category when assignments are stream-based.
* `cms_page`: CMS layout referenced by categories (inherited when missing).
* `sales_channel`: entry categories (`navigation`, `footer`, `service`) anchoring storefront menus.
* `seo_url`: generated URLs per category and sales channel domain, rebuilt by the SEO indexer.

## Sales channel entry points and navigation

Every [Sales Channel](sales-channels) defines `navigation`, `footer`, and `service` entry categories. The storefront builds menus from the children of those entry points, inheriting explicit assignments from lower levels.

Store API endpoints:

* `/store-api/navigation/{activeId}/{rootId}` for hierarchical menus.
* `/store-api/category/{navigationId}` for category details including assigned CMS layout data.

Navigation responses are cached. Adjust cache identity or tags via `NavigationRouteCacheKeyEvent` and `NavigationRouteCacheTagsEvent`. Use `NavigationLoadedEvent` to enrich or modify the tree before it is returned.

::: info
Categories can be hidden from navigation via the hide-in-navigation flag while remaining reachable by direct URL if they are still `active`.
:::

## Product assignments and Dynamic Product Groups

* Explicit assignments: stored in `product_category` (and `product_category_tree` for inherited links) to put category IDs directly on products.
* Dynamic Product Groups (product streams): attached to a category to evaluate saved filters at runtime and automate listings (for example, brand filters or price ranges). See the [user docs](https://docs.shopware.com/en/shopware-6-de/Catalogues/Dynamicproductgroups) for configuration guidance.

Both assignment types are merged for a category listing. `ProductListingRoute` builds the listing criteria from the category configuration, sales channel, and request filters. Extend or alter the listing query with `ProductListingCriteriaEvent`.

## CMS layout integration

Categories can reference a [CMS layout](../content/shopping-experiences-cms.md). Layout selection is inherited: if `cmsPageId` is missing, the parent layout is used. Category-specific slot configuration is stored on the category and merged at runtime, so one layout can serve many categories with different media and copy. `folder` categories ignore layouts; `link` categories redirect immediately.

## SEO and URLs

Per-category SEO fields include `metaTitle`, `metaDescription`, `keywords`, `seoUrl`, and robot flags (`noIndex`, `noFollow`). SEO URLs are generated from templates under *Settings → SEO* and are rebuilt when categories change or when the SEO indexer runs.

* Customize URL templates (e.g., include the breadcrumb) and priorities per sales channel domain.
* React to regenerated URLs via `SeoUrlUpdateEvent`, or enqueue additional updates when categories are changed programmatically.
* Emit canonical links when rendering custom category pages.

## Extensibility and events

* `NavigationLoadedEvent`: navigation tree loaded; enrich or adjust nodes.
* `SalesChannelCategoryIdsFetchedEvent`: category IDs resolved for a sales channel.
* `CategoryIndexerEvent`: keep de-normalized data or external search indices in sync.
* `ProductListingCriteriaEvent`: customize listing filters, sorting, and aggregations for category pages.
* `SeoUrlUpdateEvent`: observe or react to SEO URL regeneration.

Categories are fully extensible via custom fields or entity extensions. Expose custom data through Store API response extensions when it is needed in storefronts or external channels.

---

---
url: /docs/v6.5/concepts/commerce/catalog/categories.md
---

# Categories

Products in Shopware are organized in categories. Categories are represented as a hierarchical tree and they contain products. A product can be contained in multiple categories. Catalog categories provide structure to your catalog content.

There is a single category tree that represents the whole product catalog of your store.

![category](../../../assets/concept-categories.png)

## Product assignments

There are two ways that products can be assigned to a category. Either through an explicit assignment or using a Dynamic Product Group. Explicit assignments are stored in a database table, whereas dynamic groups are a collection of filters that get evaluated at execution time.

## Navigation

Categories also serve as entry points for your store navigation. For every [Sales Channel](sales-channels), you can select a category to be the root of your navigation. Shopware will then build the navigation based on that category's child categories. Parent categories also contain the explicit assignments of their children based on the Inheritance relation between categories.

::: info
Categories can be globally hidden from store navigations based on a hide in navigation flag.
:::

## CMS layouts

Every category has a [CMS layout](../content/shopping-experiences-cms.md) assigned to it. The layout dictates in which way the category will be displayed. It is very useful to centralize the management of CMS pages and hydrate it based on the category configuration.

## Types

In addition to being a product collection and a navigation item, categories can also be used as a *structuring element* (which in itself is not a category that can be visited, but it is visible in the tree) or a *custom link* redirecting to an external resource.

---

---
url: /docs/v6.6/concepts/commerce/catalog/categories.md
---

# Categories

Products in Shopware are organized in categories. Categories are represented as a hierarchical tree and they contain products. A product can be contained in multiple categories. Catalog categories provide structure to your catalog content.

There is a single category tree that represents the whole product catalog of your store.

![category](../../../assets/concept-categories.png)

## Product assignments

There are two ways that products can be assigned to a category. Either through an explicit assignment or using a Dynamic Product Group. Explicit assignments are stored in a database table, whereas dynamic groups are a collection of filters that get evaluated at execution time.

## Navigation

Categories also serve as entry points for your store navigation. For every [Sales Channel](sales-channels), you can select a category to be the root of your navigation. Shopware will then build the navigation based on that category's child categories. Parent categories also contain the explicit assignments of their children based on the Inheritance relation between categories.

::: info
Categories can be globally hidden from store navigations based on a hide in navigation flag.
:::

## CMS layouts

Every category has a [CMS layout](../content/shopping-experiences-cms.md) assigned to it. The layout dictates in which way the category will be displayed. It is very useful to centralize the management of CMS pages and hydrate it based on the category configuration.

## Types

In addition to being a product collection and a navigation item, categories can also be used as a *structuring element* (which in itself is not a category that can be visited, but it is visible in the tree) or a *custom link* redirecting to an external resource.

---

---
url: /docs/products/paas/shopware/cdn.md
---

# CDN

This section provides comprehensive information about Content Delivery Network (CDN) solutions for Shopware PaaS Native, with a focus on Fastly integration and optimization strategies.

## Fastly CDN

Fastly serves as the primary CDN solution for Shopware PaaS Native, delivering edge caching capabilities that significantly enhance your shop's performance and user experience. By storing HTTP cache at the nearest edge server to your customers, Fastly reduces response times globally while minimizing resource consumption on your application servers.

### Key Benefits

* **Global Performance**: Cached responses are served from edge locations worldwide, drastically reducing latency
* **Resource Optimization**: Reduces load on your application servers by serving cached content from the edge
* **Redis Cache Relief**: Minimizes Redis cache usage by handling HTTP cache at the CDN level
* **Automatic Scaling**: Seamlessly handles traffic spikes without impacting your application performance

### Integration

Fastly is fully integrated into Shopware PaaS Native. The integration includes:

* Automatic cache invalidation mechanisms
* Soft purge capabilities to maintain performance during cache updates
* Deployment helper integration for seamless VCL snippet management. See the [Fastly snippets documentation](./fastly-snippets.md) for more details.

### Configuration

Fastly is automatically configured and enabled by default in Shopware PaaS Native environments. No additional Shopware configuration is required - the PaaS platform handles all Fastly setup and cache management automatically.

We configure two different Fastly services:

* `storefront`: Service that proxies the storefront and admin Shopware instances.
* `cdn`: Service that proxies all the CDN assets hosted on S3 (public bucket).

## Custom Domains

### Prerequisites

Before adding a custom domain to your Shopware PaaS Native environment, ensure you have:

* Shopware PaaS CLI installed and configured (`sw-paas`)
* Your organization ID (retrieve it using `sw-paas org list`)
* A registered domain with access to DNS management
* Permissions to deploy your application

### Overview

Custom domains allow you to serve your Shopware shop through your own branded domain while leveraging Fastly's CDN for optimal performance. The platform actively validates your DNS configuration during domain creation to ensure proper routing and security.

**Important:** DNS records must be configured and fully propagated **before** creating the domain in the PaaS platform. The domain creation process validates all DNS records in real-time and will fail if they are not correctly configured.

### Quick Reference: DNS Records

| Record Type | For Apex Domains | For Non-Apex Domains | Target                 | Count | Purpose                                |
|-------------|:----------------:|:--------------------:|------------------------|:-----:|----------------------------------------|
| `CNAME`     |        No        |       **Yes**        | `cdn.shopware.shop`    |   1   | Routes subdomain traffic to Fastly CDN |
| `A`         |     **Yes**      |          No          | Fastly IPv4 addresses  |   4   | Routes apex domain traffic (IPv4)      |
| `AAAA`      |     **Yes**      |          No          | Fastly IPv6 addresses  |   4   | Routes apex domain traffic (IPv6)      |
| `TXT`       |     **Yes**      |          No          | Domain ownership proof |   1   | Validates domain ownership             |

### Step 1: Configure DNS Records

Configure DNS records at your domain registrar or DNS provider. The required records differ based on whether you're using an apex domain or a subdomain.

#### For Non-Apex Domains (Subdomains)

If your custom domain is a subdomain (e.g., `shop.example.com`, `www.example.com`), create a `CNAME` record:

```dns
CNAME: cdn.shopware.shop
```

**Example:**

```dns
shop.example.com.  IN  CNAME  cdn.shopware.shop.
```

#### For Apex Domains

If your custom domain is an apex/root domain (e.g., `example.com`), you need to configure multiple record types:

**1. IPv4 routing** - Create all `A` records:

```dns
151.101.3.52
151.101.67.52
151.101.131.52
151.101.195.52
```

**2. IPv6 routing** - Create all `AAAA` records:

```dns
2a04:4e42::820
2a04:4e42:200::820
2a04:4e42:400::820
2a04:4e42:600::820
```

### Step 2: Domain ownership - Create a `TXT` record to prove domain ownership

```dns
_shopware-challenge.<domain> IN TXT "shopware-challenge=<organization id>"
```

Replace `<domain>` with your actual domain and `<organization id>` with your organization ID from `sw-paas org list`.

Example with the following setup:

* your application FQDN is `myshop.example.com`
* then your domain is `example.com`
* your organization ID is `abc123`

Create the following record:

```dns
_shopware-challenge.example.com.  IN  TXT  "shopware-challenge=abc123"
```

::: info
The challenge record needs to stay as long as the domain is configured in our PaaS.
:::

::: info **DNS Propagation Time:** DNS changes typically propagate within 15-30 minutes but can take up to 48 hours depending on TTL settings and DNS provider. We strongly recommend waiting for full propagation before proceeding to Step 4.
Use Step 3 to validate all records are correct and propagated.
:::

### Step 3: Verify DNS Propagation

Before creating the domain in the PaaS platform, verify that your DNS records have propagated correctly using the `dig` command or online DNS lookup tools.

**For non-apex domains (CNAME):**

```bash
dig shop.example.com CNAME
```

**For apex domains:**

```bash
# Verify A records
dig example.com A

# Verify AAAA records
dig example.com AAAA
```

**For challenge record:**

```bash
# Verify TXT record
dig _shopware-challenge.example.com TXT
```

Ensure the responses match the values you configured in Step 1 and 2.

### Step 4: Create Domain in PaaS

Once DNS records are configured and propagated, create the domain using the CLI:

```bash
sw-paas domain create
```

You can attach multiple domains to a single shop by running this command for each domain.

::: warning
**Active DNS Validation:** The platform performs real-time validation of your DNS configuration during domain creation. The following checks must pass:

* **For apex domains:** A records point to correct Fastly IPv4 addresses, AAAA records point to correct Fastly IPv6 addresses, and TXT record matches your organization ID
* **For non-apex domains:** CNAME record points to `cdn.shopware.shop`
* **DNS propagation:** Records must be resolvable through public DNS

If validation fails, verify your DNS configuration and wait for propagation before retrying.
:::

### Step 5: Deploy Application

After successful domain creation, trigger an application deployment to activate the domain:

```bash
sw-paas application deploy create
```

Alternatively, you can use:

```bash
sw-paas application update
```

You may use the same commit to trigger a deployment.

### Step 6: Configure in Shopware

After deployment completes:

1. Log in to your Shopware administration panel
2. Navigate to domain/storefront configuration
3. Associate the custom domain with your desired storefront

The domain should now serve traffic through the Fastly CDN.

### Troubleshooting

#### DNS Validation Fails During Domain Creation

**Symptoms:**

* Error message during `sw-paas domain create`
* Domain creation rejected or fails validation

**Solutions:**

1. **Verify DNS record configuration**
   * Double-check that all required records are configured correctly
   * For apex domains: Ensure all 4 A records, all 4 AAAA records, and the TXT record are present
   * For non-apex domains: Ensure CNAME points to `cdn.shopware.shop`

2. **Check DNS propagation**
   * Use `dig` commands (see Step 2) to verify records are resolvable
   * Try querying from different DNS servers: `dig @8.8.8.8 example.com A`
   * Use online tools like [whatsmydns.net](https://www.whatsmydns.net) to check global propagation

3. **Wait for propagation**
   * If records appear correct in your DNS provider but aren't resolving, wait longer for propagation
   * DNS changes can take up to 48 hours in some cases

4. **Verify organization ID**
   * Run `sw-paas org list` to confirm your organization ID
   * Ensure the TXT record value exactly matches: `shopware-challenge=<your-org-id>`

5. **Check for typos**
   * Verify the domain name is spelled correctly
   * Ensure no extra spaces or characters in DNS records

#### Domain Created But Not Serving Traffic

**Symptoms:**

* Domain creation succeeded, but the site is not accessible
* SSL/TLS certificate errors
* Connection timeouts

**Solutions:**

1. **Verify deployment completed**
   * Check that Step 4 deployment finished successfully
   * Run `sw-paas application deploy get` to check application status

2. **Check Shopware configuration**
   * Ensure domain is associated with a storefront in Shopware admin (Step 5)
   * Verify sales channel configuration

3. **Clear caches**
   * Clear browser cache and cookies
   * Try accessing the domain in incognito/private browsing mode
   * Clear Shopware caches if necessary

4. **DNS propagation delay**
   * Even after domain creation, DNS changes may still be propagating globally
   * Wait additional time and retest

#### Getting Help

If issues persist after trying the above solutions, contact Shopware support with the following information:

* Domain name you're trying to configure
* Your organization ID
* Complete error messages (exact text)
* DNS query results (output from `dig` commands)
* Timeline of actions taken and when errors occurred
* Screenshots of DNS configuration from your provider

This information will help the support to diagnose and resolve the issue quickly.

---

---
url: /docs/v6.5/guides/plugins/plugins/checkout/cart/change-price-of-item.md
---

# Change price of items in cart

## Overview

This guide will tackle the issue of changing the price of a line item in the cart dynamically. The following example is **not** recommended if you want to add a discount / surcharge to your products. Make sure to check out the guide about [adding a discount into the cart](add-cart-discounts).

::: warning
Changing the price like it's done in the following example should rarely be done and only with great caution. A live-shopping plugin would be a good example about when to actually change an item's price instead of adding a discount / surcharge.
:::

## Prerequisites

This guide is also built upon the [plugin base guide](../../plugin-base-guide), which creates a plugin first. The namespaces used in the examples of this guide match those of the plugin base guide, yet those are just examples.

Furthermore, you should know how to register a service to the [dependency injection container](../../plugin-fundamentals/dependency-injection).

## Changing the price

In order to change a price of an item in the cart, you'll have to use a cart collector and a cart processor. The collector is used to collect all new prices necessary for your line items and therefore provide this data. It will also take care of reducing duplicated requests, but we'll get into that later.

The processor will then take the new prices, calculate them appropriately and apply them to the line items.

While we will start with the collector part, do not be confused later on in this guide, because we'll use the same class for both collecting the prices and processing the cart.

### The collector

So the collector has to collect all prices necessary in order to overwrite a line item.

This guide will not cover where to actually fetch the new prices from, that's up to you. This could e.g. be an [extension of the product entity](../../framework/data-handling/add-complex-data-to-existing-entities), which contains the new price, or an API call from somewhere else, which will return the new price.

Your collector class has to implement the interface `Shopware\Core\Checkout\Cart\CartDataCollectorInterface` and therefore the method `collect`.

Let's have a look at an example:

```php
// <plugin root>/src/Core/Checkout/Cart/OverwritePriceCollector.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout\Cart;

use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Cart\CartBehavior;
use Shopware\Core\Checkout\Cart\CartDataCollectorInterface;
use Shopware\Core\Checkout\Cart\LineItem\CartDataCollection;
use Shopware\Core\Checkout\Cart\LineItem\LineItem;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class OverwritePriceCollector implements CartDataCollectorInterface
{
    public function collect(CartDataCollection $data, Cart $original, SalesChannelContext $context, CartBehavior $behavior): void
    {
        // get all product ids of current cart
        $productIds = $original->getLineItems()->filterType(LineItem::PRODUCT_LINE_ITEM_TYPE)->getReferenceIds();

        // remove all product ids which are already fetched from the database
        $filtered = $this->filterAlreadyFetchedPrices($productIds, $data);

        // Skip execution if there are no prices to be requested & saved
        if (empty($filtered)) {
            return;
        }

        foreach ($filtered as $id) {
            $key = $this->buildKey($id);

            // Needs implementation, just an example
            $newPrice = $this->doSomethingToGetNewPrice();

            // we have to set a value for each product id to prevent duplicate queries in next calculation
            $data->set($key, $newPrice);
        }
    }

    private function filterAlreadyFetchedPrices(array $productIds, CartDataCollection $data): array
    {
        $filtered = [];

        foreach ($productIds as $id) {
            $key = $this->buildKey($id);

            // already fetched from database?
            if ($data->has($key)) {
                continue;
            }

            $filtered[] = $id;
        }

        return $filtered;
    }

    private function buildKey(string $id): string
    {
        return 'price-overwrite-'.$id;
    }
}
```

So the example class is called `OverwritePriceCollector` here and it implements the method `collect`. This method's parameters are the following:

* `CartDataCollection`: This is the object, that will contain our new data, which is then processed in the processor.

  Here you're going to save the new price. It contains key-value pairs, so we will save the new price as the value, and its key

  being the line item ID. We will prefix a custom string to the line item ID, so our code will not interfere with other collectors,

  that might also save the line item ID as a key.

* `Cart`: Well, the current cart and its line items.

* `SalesChannelContext`: The current sales channel context, containing information about the currency, the country, etc.

* `CartBehavior`: It contains cart permissions, which are not necessary for our example.

Inside of the `collect` method, we're first fetching all **products** from the `Cart`, named `$original`, since we do not want to change the price of a discount or any other custom type of line item.

Now we're calling a method `filterAlreadyFetchedPrices`. So what it does is basically checking if we already saved a new price for a given line item ID to the `CartDataCollector`. We do this, since your collect method may be executed multiple times per request and we want to prevent multiple database requests here. If you do need to request it multiple times because your prices may have changed in between, you can remove that method.

Afterwards we're iterating over all product IDs, that still need to request a new price, and we do so with an example method. The `doSomethingToGetNewPrice` method is just an example and therefore not implemented. **Make sure to replace this part with any kind of actually fetching a new price.**

The last step is to save that new price to the `CartDataCollector`.

And that's it, we're now collecting the prices for our product line items. Registering the class to the [dependency injection container](../../plugin-fundamentals/dependency-injection) will be done in the [last section](change-price-of-item#Registering%20to%20DI%20container) of this guide.

### The processor

The processor now has to fetch the new prices from the `CartDataCollector` and it has to calculate the actual new price of that line item, e.g. due to taxes. For this case, it will need the `Shopware\Core\Checkout\Cart\Price\QuantityPriceCalculator`.

As already mentioned, we'll use the same class for the processor, which we will do by implementing two interfaces. Of course you could split them into separate classes.

Your processor has to implement the interface `Shopware\Core\Checkout\Cart\CartProcessorInterface`, which forces you to implement the `process` method.

But once, again, let's have a look at the example:

```php
// <plugin root>/src/Core/Checkout/Cart/OverwritePriceCollector.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout\Cart;

use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Cart\CartBehavior;
use Shopware\Core\Checkout\Cart\CartDataCollectorInterface;
use Shopware\Core\Checkout\Cart\CartProcessorInterface;
use Shopware\Core\Checkout\Cart\LineItem\CartDataCollection;
use Shopware\Core\Checkout\Cart\LineItem\LineItem;
use Shopware\Core\Checkout\Cart\Price\QuantityPriceCalculator;
use Shopware\Core\Checkout\Cart\Price\Struct\QuantityPriceDefinition;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class OverwritePriceCollector implements CartDataCollectorInterface, CartProcessorInterface
{
    private QuantityPriceCalculator $calculator;

    public function __construct(QuantityPriceCalculator $calculator) {
        $this->calculator = $calculator;
    }

    public function collect(CartDataCollection $data, Cart $original, SalesChannelContext $context, CartBehavior $behavior): void
    {
        // get all product ids of current cart
        $productIds = $original->getLineItems()->filterType(LineItem::PRODUCT_LINE_ITEM_TYPE)->getReferenceIds();

        // remove all product ids which are already fetched from the database
        $filtered = $this->filterAlreadyFetchedPrices($productIds, $data);

        // Skip execution if there are no prices to be saved
        if (empty($filtered)) {
            return;
        }

        foreach ($filtered as $id) {
            $key = $this->buildKey($id);

            // Needs implementation, just an example
            $newPrice = $this->doSomethingToGetNewPrice();

            // we have to set a value for each product id to prevent duplicate queries in next calculation
            $data->set($key, $newPrice);
        }
    }

    public function process(CartDataCollection $data, Cart $original, Cart $toCalculate, SalesChannelContext $context, CartBehavior $behavior): void
    {
        // get all product line items
        $products = $toCalculate->getLineItems()->filterType(LineItem::PRODUCT_LINE_ITEM_TYPE);

        foreach ($products as $product) {
            $key = $this->buildKey($product->getReferencedId());

            // no overwritten price? continue with next product
            if (!$data->has($key) || $data->get($key) === null) {
                continue;
            }

            $newPrice = $data->get($key);

            // build new price definition
            $definition = new QuantityPriceDefinition(
                $newPrice,
                $product->getPrice()->getTaxRules(),
                $product->getPrice()->getQuantity()
            );

            // build CalculatedPrice over calculator class for overwritten price
            $calculated = $this->calculator->calculate($definition, $context);

            // set new price into line item
            $product->setPrice($calculated);
            $product->setPriceDefinition($definition);
        }
    }

    private function filterAlreadyFetchedPrices(array $productIds, CartDataCollection $data): array
    {
        $filtered = [];

        foreach ($productIds as $id) {
            $key = $this->buildKey($id);

            // already fetched from database?
            if ($data->has($key)) {
                continue;
            }

            $filtered[] = $id;
        }

        return $filtered;
    }

    private function buildKey(string $id): string
    {
        return 'price-overwrite-'.$id;
    }
}
```

First of all, note the second interface we implemented, next to the `CartDataCollectorInterface`. We also added a constructor in order to inject the `QuantityPriceCalculator`.

But now, let's have a look at the `process` method. You should already be familiar with most of its parameters, since they're mostly the same with those of the collector. Yet, there's one main difference: Next to the `$original` `Cart`, you've got another `Cart` parameter being called `$toCalculate`here. Make sure to do all the changes on the `$toCalculate` instance, since this is the cart that's going to be considered in the end. The `$original` one is just there, because it may contain necessary data for the actual cart instance.

Now let's have a look inside the `process` method.

We start by filtering all line items down to only products, just like we did in the `collect` method. Then we're iterating over all products found, building the unique key, which is necessary for fetching the new price from the `CartDataCollector`.

If there's no price to be processed saved in the `CartDataCollector`, there's nothing to do here. Otherwise, we're fetching the new price, we're building a new instance of a `QuantityPriceDefinition` containing the new price. Using that instance, we can calculate the actual new price using the previously injected `QuantityPriceCalculator`.

Only thing left to do now, is to save the newly calculated price to the line item - and that's it!

::: warning
Do not query the database in the `process` method. Make sure to always use a collector for that.
:::

### Registering to DI container

One last thing, we need to register our processor and collector to the DI container. Our collector / processor has to be registered using the two tags `shopware.cart.processor` and `shopware.cart.collector`.

Let's have a look at it:

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Core\Checkout\Cart\OverwritePriceCollector">
            <argument type="service" id="Shopware\Core\Checkout\Cart\Price\QuantityPriceCalculator"/>

            <!-- after product collector/processor -->
            <tag name="shopware.cart.processor" priority="4500" />
            <tag name="shopware.cart.collector" priority="4500" />
        </service>
    </services>
</container>
```

And that's it. Your processor / collector should now be working.

---

---
url: /docs/v6.6/guides/plugins/plugins/checkout/cart/change-price-of-item.md
---

# Change price of items in cart

## Overview

This guide will tackle the issue of changing the price of a line item in the cart dynamically. The following example is **not** recommended if you want to add a discount / surcharge to your products. Make sure to check out the guide about [adding a discount into the cart](add-cart-discounts).

::: warning
Changing the price like it's done in the following example should rarely be done and only with great caution. A live-shopping plugin would be a good example about when to actually change an item's price instead of adding a discount / surcharge.
:::

## Prerequisites

This guide is also built upon the [plugin base guide](../../plugin-base-guide), which creates a plugin first. The namespaces used in the examples of this guide match those of the plugin base guide, yet those are just examples.

Furthermore, you should know how to register a service to the [dependency injection container](../../plugin-fundamentals/dependency-injection).

## Changing the price

In order to change a price of an item in the cart, you'll have to use a cart collector and a cart processor. The collector is used to collect all new prices necessary for your line items and therefore provide this data. It will also take care of reducing duplicated requests, but we'll get into that later.

The processor will then take the new prices, calculate them appropriately and apply them to the line items.

While we will start with the collector part, do not be confused later on in this guide, because we'll use the same class for both collecting the prices and processing the cart.

### The collector

So the collector has to collect all prices necessary in order to overwrite a line item.

This guide will not cover where to actually fetch the new prices from, that's up to you. This could e.g. be an [extension of the product entity](../../framework/data-handling/add-complex-data-to-existing-entities), which contains the new price, or an API call from somewhere else, which will return the new price.

Your collector class has to implement the interface `Shopware\Core\Checkout\Cart\CartDataCollectorInterface` and therefore the method `collect`.

Let's have a look at an example:

```php
// <plugin root>/src/Core/Checkout/Cart/OverwritePriceCollector.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout\Cart;

use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Cart\CartBehavior;
use Shopware\Core\Checkout\Cart\CartDataCollectorInterface;
use Shopware\Core\Checkout\Cart\LineItem\CartDataCollection;
use Shopware\Core\Checkout\Cart\LineItem\LineItem;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class OverwritePriceCollector implements CartDataCollectorInterface
{
    public function collect(CartDataCollection $data, Cart $original, SalesChannelContext $context, CartBehavior $behavior): void
    {
        // get all product ids of current cart
        $productIds = $original->getLineItems()->filterType(LineItem::PRODUCT_LINE_ITEM_TYPE)->getReferenceIds();

        // remove all product ids which are already fetched from the database
        $filtered = $this->filterAlreadyFetchedPrices($productIds, $data);

        // Skip execution if there are no prices to be requested & saved
        if (empty($filtered)) {
            return;
        }

        foreach ($filtered as $id) {
            $key = $this->buildKey($id);

            // Needs implementation, just an example
            $newPrice = $this->doSomethingToGetNewPrice();

            // we have to set a value for each product id to prevent duplicate queries in next calculation
            $data->set($key, $newPrice);
        }
    }

    private function filterAlreadyFetchedPrices(array $productIds, CartDataCollection $data): array
    {
        $filtered = [];

        foreach ($productIds as $id) {
            $key = $this->buildKey($id);

            // already fetched from database?
            if ($data->has($key)) {
                continue;
            }

            $filtered[] = $id;
        }

        return $filtered;
    }

    private function buildKey(string $id): string
    {
        return 'price-overwrite-'.$id;
    }
}
```

So the example class is called `OverwritePriceCollector` here and it implements the method `collect`. This method's parameters are the following:

* `CartDataCollection`: This is the object, that will contain our new data, which is then processed in the processor.

  Here you're going to save the new price. It contains key-value pairs, so we will save the new price as the value, and its key

  being the line item ID. We will prefix a custom string to the line item ID, so our code will not interfere with other collectors,

  that might also save the line item ID as a key.

* `Cart`: Well, the current cart and its line items.

* `SalesChannelContext`: The current sales channel context, containing information about the currency, the country, etc.

* `CartBehavior`: It contains cart permissions, which are not necessary for our example.

Inside of the `collect` method, we're first fetching all **products** from the `Cart`, named `$original`, since we do not want to change the price of a discount or any other custom type of line item.

Now we're calling a method `filterAlreadyFetchedPrices`. So what it does is basically checking if we already saved a new price for a given line item ID to the `CartDataCollector`. We do this, since your collect method may be executed multiple times per request and we want to prevent multiple database requests here. If you do need to request it multiple times because your prices may have changed in between, you can remove that method.

Afterwards we're iterating over all product IDs, that still need to request a new price, and we do so with an example method. The `doSomethingToGetNewPrice` method is just an example and therefore not implemented. **Make sure to replace this part with any kind of actually fetching a new price.**

The last step is to save that new price to the `CartDataCollector`.

And that's it, we're now collecting the prices for our product line items. Registering the class to the [dependency injection container](../../plugin-fundamentals/dependency-injection) will be done in the [last section](change-price-of-item#Registering%20to%20DI%20container) of this guide.

### The processor

The processor now has to fetch the new prices from the `CartDataCollector` and it has to calculate the actual new price of that line item, e.g. due to taxes. For this case, it will need the `Shopware\Core\Checkout\Cart\Price\QuantityPriceCalculator`.

As already mentioned, we'll use the same class for the processor, which we will do by implementing two interfaces. Of course you could split them into separate classes.

Your processor has to implement the interface `Shopware\Core\Checkout\Cart\CartProcessorInterface`, which forces you to implement the `process` method.

But once, again, let's have a look at the example:

```php
// <plugin root>/src/Core/Checkout/Cart/OverwritePriceCollector.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout\Cart;

use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Cart\CartBehavior;
use Shopware\Core\Checkout\Cart\CartDataCollectorInterface;
use Shopware\Core\Checkout\Cart\CartProcessorInterface;
use Shopware\Core\Checkout\Cart\LineItem\CartDataCollection;
use Shopware\Core\Checkout\Cart\LineItem\LineItem;
use Shopware\Core\Checkout\Cart\Price\QuantityPriceCalculator;
use Shopware\Core\Checkout\Cart\Price\Struct\QuantityPriceDefinition;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class OverwritePriceCollector implements CartDataCollectorInterface, CartProcessorInterface
{
    private QuantityPriceCalculator $calculator;

    public function __construct(QuantityPriceCalculator $calculator) {
        $this->calculator = $calculator;
    }

    public function collect(CartDataCollection $data, Cart $original, SalesChannelContext $context, CartBehavior $behavior): void
    {
        // get all product ids of current cart
        $productIds = $original->getLineItems()->filterType(LineItem::PRODUCT_LINE_ITEM_TYPE)->getReferenceIds();

        // remove all product ids which are already fetched from the database
        $filtered = $this->filterAlreadyFetchedPrices($productIds, $data);

        // Skip execution if there are no prices to be saved
        if (empty($filtered)) {
            return;
        }

        foreach ($filtered as $id) {
            $key = $this->buildKey($id);

            // Needs implementation, just an example
            $newPrice = $this->doSomethingToGetNewPrice();

            // we have to set a value for each product id to prevent duplicate queries in next calculation
            $data->set($key, $newPrice);
        }
    }

    public function process(CartDataCollection $data, Cart $original, Cart $toCalculate, SalesChannelContext $context, CartBehavior $behavior): void
    {
        // get all product line items
        $products = $toCalculate->getLineItems()->filterType(LineItem::PRODUCT_LINE_ITEM_TYPE);

        foreach ($products as $product) {
            $key = $this->buildKey($product->getReferencedId());

            // no overwritten price? continue with next product
            if (!$data->has($key) || $data->get($key) === null) {
                continue;
            }

            $newPrice = $data->get($key);

            // build new price definition
            $definition = new QuantityPriceDefinition(
                $newPrice,
                $product->getPrice()->getTaxRules(),
                $product->getPrice()->getQuantity()
            );

            // build CalculatedPrice over calculator class for overwritten price
            $calculated = $this->calculator->calculate($definition, $context);

            // set new price into line item
            $product->setPrice($calculated);
            $product->setPriceDefinition($definition);
        }
    }

    private function filterAlreadyFetchedPrices(array $productIds, CartDataCollection $data): array
    {
        $filtered = [];

        foreach ($productIds as $id) {
            $key = $this->buildKey($id);

            // already fetched from database?
            if ($data->has($key)) {
                continue;
            }

            $filtered[] = $id;
        }

        return $filtered;
    }

    private function buildKey(string $id): string
    {
        return 'price-overwrite-'.$id;
    }
}
```

First of all, note the second interface we implemented, next to the `CartDataCollectorInterface`. We also added a constructor in order to inject the `QuantityPriceCalculator`.

But now, let's have a look at the `process` method. You should already be familiar with most of its parameters, since they're mostly the same with those of the collector. Yet, there's one main difference: Next to the `$original` `Cart`, you've got another `Cart` parameter being called `$toCalculate`here. Make sure to do all the changes on the `$toCalculate` instance, since this is the cart that's going to be considered in the end. The `$original` one is just there, because it may contain necessary data for the actual cart instance.

Now let's have a look inside the `process` method.

We start by filtering all line items down to only products, just like we did in the `collect` method. Then we're iterating over all products found, building the unique key, which is necessary for fetching the new price from the `CartDataCollector`.

If there's no price to be processed saved in the `CartDataCollector`, there's nothing to do here. Otherwise, we're fetching the new price, we're building a new instance of a `QuantityPriceDefinition` containing the new price. Using that instance, we can calculate the actual new price using the previously injected `QuantityPriceCalculator`.

Only thing left to do now, is to save the newly calculated price to the line item - and that's it!

::: warning
Do not query the database in the `process` method. Make sure to always use a collector for that.
:::

### Registering to DI container

One last thing, we need to register our processor and collector to the DI container. Our collector / processor has to be registered using the two tags `shopware.cart.processor` and `shopware.cart.collector`.

Let's have a look at it:

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Core\Checkout\Cart\OverwritePriceCollector">
            <argument type="service" id="Shopware\Core\Checkout\Cart\Price\QuantityPriceCalculator"/>

            <!-- after product collector/processor -->
            <tag name="shopware.cart.processor" priority="4500" />
            <tag name="shopware.cart.collector" priority="4500" />
        </service>
    </services>
</container>
```

And that's it. Your processor / collector should now be working.

---

---
url: /docs/guides/plugins/plugins/checkout/cart/change-price-of-item.md
---

# Change Price of Items in Cart

## Overview

This guide will tackle the issue of changing the price of a line item in the cart dynamically. The following example is **not** recommended if you want to add a discount / surcharge to your products. Make sure to check out the guide about [adding a discount into the cart](add-cart-discounts.md).

::: warning
Changing the price like it's done in the following example should rarely be done and only with great caution. A live-shopping plugin would be a good example about when to actually change an item's price instead of adding a discount / surcharge.
:::

## Prerequisites

This guide is also built upon the [plugin base guide](../../plugin-base-guide), which creates a plugin first. The namespaces used in the examples of this guide match those of the plugin base guide, yet those are just examples.

Furthermore, you should know how to register a service to the [dependency injection container](../../services/dependency-injection.md).

## Changing the price

In order to change a price of an item in the cart, you'll have to use a cart collector and a cart processor. The collector is used to collect all new prices necessary for your line items and therefore provide this data. It will also take care of reducing duplicated requests, but we'll get into that later.

The processor will then take the new prices, calculate them appropriately and apply them to the line items.

While we will start with the collector part, do not be confused later on in this guide, because we'll use the same class for both collecting the prices and processing the cart.

### The collector

So the collector has to collect all prices necessary in order to overwrite a line item.

This guide will not cover where to actually fetch the new prices from, that's up to you. This could e.g. be an [extension of the product entity](../../framework/data-handling/add-complex-data-to-existing-entities), which contains the new price, or an API call from somewhere else, which will return the new price.

Your collector class has to implement the interface `Shopware\Core\Checkout\Cart\CartDataCollectorInterface` and therefore the method `collect`.

Let's have a look at an example:

```php
// <plugin root>/src/Core/Checkout/Cart/OverwritePriceCollector.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout\Cart;

use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Cart\CartBehavior;
use Shopware\Core\Checkout\Cart\CartDataCollectorInterface;
use Shopware\Core\Checkout\Cart\LineItem\CartDataCollection;
use Shopware\Core\Checkout\Cart\LineItem\LineItem;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class OverwritePriceCollector implements CartDataCollectorInterface
{
    public function collect(CartDataCollection $data, Cart $original, SalesChannelContext $context, CartBehavior $behavior): void
    {
        // get all product ids of current cart
        $productIds = $original->getLineItems()->filterType(LineItem::PRODUCT_LINE_ITEM_TYPE)->getReferenceIds();

        // remove all product ids which are already fetched from the database
        $filtered = $this->filterAlreadyFetchedPrices($productIds, $data);

        // Skip execution if there are no prices to be requested & saved
        if (empty($filtered)) {
            return;
        }

        foreach ($filtered as $id) {
            $key = $this->buildKey($id);

            // Needs implementation, just an example
            $newPrice = $this->doSomethingToGetNewPrice();

            // we have to set a value for each product id to prevent duplicate queries in next calculation
            $data->set($key, $newPrice);
        }
    }

    private function filterAlreadyFetchedPrices(array $productIds, CartDataCollection $data): array
    {
        $filtered = [];

        foreach ($productIds as $id) {
            $key = $this->buildKey($id);

            // already fetched from database?
            if ($data->has($key)) {
                continue;
            }

            $filtered[] = $id;
        }

        return $filtered;
    }

    private function buildKey(string $id): string
    {
        return 'price-overwrite-'.$id;
    }
}
```

So the example class is called `OverwritePriceCollector` here and it implements the method `collect`. This method's parameters are the following:

* `CartDataCollection`: This is the object, that will contain our new data, which is then processed in the processor.

  Here you're going to save the new price. It contains key-value pairs, so we will save the new price as the value, and its key

  being the line item ID. We will prefix a custom string to the line item ID, so our code will not interfere with other collectors,

  that might also save the line item ID as a key.

* `Cart`: Well, the current cart and its line items.

* `SalesChannelContext`: The current sales channel context, containing information about the currency, the country, etc.

* `CartBehavior`: It contains cart permissions, which are not necessary for our example.

Inside of the `collect` method, we're first fetching all **products** from the `Cart`, named `$original`, since we do not want to change the price of a discount or any other custom type of line item.

Now we're calling a method `filterAlreadyFetchedPrices`. So what it does is basically checking if we already saved a new price for a given line item ID to the `CartDataCollector`. We do this, since your collect method may be executed multiple times per request and we want to prevent multiple database requests here. If you do need to request it multiple times because your prices may have changed in between, you can remove that method.

Afterwards we're iterating over all product IDs, that still need to request a new price, and we do so with an example method. The `doSomethingToGetNewPrice` method is just an example and therefore not implemented. **Make sure to replace this part with any kind of actually fetching a new price.**

The last step is to save that new price to the `CartDataCollector`.

And that's it, we're now collecting the prices for our product line items. Registering the class to the [dependency injection container](../../services/dependency-injection.md) will be done in the [last section](change-price-of-item#Registering%20to%20DI%20container) of this guide.

### The processor

The processor now has to fetch the new prices from the `CartDataCollector` and it has to calculate the actual new price of that line item, e.g. due to taxes. For this case, it will need the `Shopware\Core\Checkout\Cart\Price\QuantityPriceCalculator`.

As already mentioned, we'll use the same class for the processor, which we will do by implementing two interfaces. Of course you could split them into separate classes.

Your processor has to implement the interface `Shopware\Core\Checkout\Cart\CartProcessorInterface`, which forces you to implement the `process` method.

But once, again, let's have a look at the example:

```php
// <plugin root>/src/Core/Checkout/Cart/OverwritePriceCollector.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Core\Checkout\Cart;

use Shopware\Core\Checkout\Cart\Cart;
use Shopware\Core\Checkout\Cart\CartBehavior;
use Shopware\Core\Checkout\Cart\CartDataCollectorInterface;
use Shopware\Core\Checkout\Cart\CartProcessorInterface;
use Shopware\Core\Checkout\Cart\LineItem\CartDataCollection;
use Shopware\Core\Checkout\Cart\LineItem\LineItem;
use Shopware\Core\Checkout\Cart\Price\QuantityPriceCalculator;
use Shopware\Core\Checkout\Cart\Price\Struct\QuantityPriceDefinition;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class OverwritePriceCollector implements CartDataCollectorInterface, CartProcessorInterface
{
    private QuantityPriceCalculator $calculator;

    public function __construct(QuantityPriceCalculator $calculator) {
        $this->calculator = $calculator;
    }

    public function collect(CartDataCollection $data, Cart $original, SalesChannelContext $context, CartBehavior $behavior): void
    {
        // get all product ids of current cart
        $productIds = $original->getLineItems()->filterType(LineItem::PRODUCT_LINE_ITEM_TYPE)->getReferenceIds();

        // remove all product ids which are already fetched from the database
        $filtered = $this->filterAlreadyFetchedPrices($productIds, $data);

        // Skip execution if there are no prices to be saved
        if (empty($filtered)) {
            return;
        }

        foreach ($filtered as $id) {
            $key = $this->buildKey($id);

            // Needs implementation, just an example
            $newPrice = $this->doSomethingToGetNewPrice();

            // we have to set a value for each product id to prevent duplicate queries in next calculation
            $data->set($key, $newPrice);
        }
    }

    public function process(CartDataCollection $data, Cart $original, Cart $toCalculate, SalesChannelContext $context, CartBehavior $behavior): void
    {
        // get all product line items
        $products = $toCalculate->getLineItems()->filterType(LineItem::PRODUCT_LINE_ITEM_TYPE);

        foreach ($products as $product) {
            $key = $this->buildKey($product->getReferencedId());

            // no overwritten price? continue with next product
            if (!$data->has($key) || $data->get($key) === null) {
                continue;
            }

            $newPrice = $data->get($key);

            // build new price definition
            $definition = new QuantityPriceDefinition(
                $newPrice,
                $product->getPrice()->getTaxRules(),
                $product->getPrice()->getQuantity()
            );

            // build CalculatedPrice over calculator class for overwritten price
            $calculated = $this->calculator->calculate($definition, $context);

            // set new price into line item
            $product->setPrice($calculated);
            $product->setPriceDefinition($definition);
        }
    }

    private function filterAlreadyFetchedPrices(array $productIds, CartDataCollection $data): array
    {
        $filtered = [];

        foreach ($productIds as $id) {
            $key = $this->buildKey($id);

            // already fetched from database?
            if ($data->has($key)) {
                continue;
            }

            $filtered[] = $id;
        }

        return $filtered;
    }

    private function buildKey(string $id): string
    {
        return 'price-overwrite-'.$id;
    }
}
```

First of all, note the second interface we implemented, next to the `CartDataCollectorInterface`. We also added a constructor in order to inject the `QuantityPriceCalculator`.

But now, let's have a look at the `process` method. You should already be familiar with most of its parameters, since they're mostly the same with those of the collector. Yet, there's one main difference: Next to the `$original` `Cart`, you've got another `Cart` parameter being called `$toCalculate`here. Make sure to do all the changes on the `$toCalculate` instance, since this is the cart that's going to be considered in the end. The `$original` one is just there, because it may contain necessary data for the actual cart instance.

Now let's have a look inside the `process` method.

We start by filtering all line items down to only products, just like we did in the `collect` method. Then we're iterating over all products found, building the unique key, which is necessary for fetching the new price from the `CartDataCollector`.

If there's no price to be processed saved in the `CartDataCollector`, there's nothing to do here. Otherwise, we're fetching the new price, we're building a new instance of a `QuantityPriceDefinition` containing the new price. Using that instance, we can calculate the actual new price using the previously injected `QuantityPriceCalculator`.

Only thing left to do now, is to save the newly calculated price to the line item - and that's it!

::: warning
Do not query the database in the `process` method. Make sure to always use a collector for that.
:::

### Registering to DI container

One last thing, we need to register our processor and collector to the DI container. Our collector / processor has to be registered using the two tags `shopware.cart.processor` and `shopware.cart.collector`.

Let's have a look at it:

```php
// <plugin root>/src/Resources/config/services.php
<?php declare(strict_types=1);

use Shopware\Core\Checkout\Cart\Price\QuantityPriceCalculator;
use Swag\BasicExample\Core\Checkout\Cart\OverwritePriceCollector;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(OverwritePriceCollector::class)
        ->args([
            service(QuantityPriceCalculator::class),
        ])
        // after product collector/processor
        ->tag('shopware.cart.processor', ['priority' => 4500])
        ->tag('shopware.cart.collector', ['priority' => 4500]);
};
```

And that's it. Your processor / collector should now be working.

---

---
url: /resources/admin-extension-sdk/CHANGELOG.md
---
# Changelog

## 1.0.0

### Major Changes

* 0e794ae: Add `uiMediaModalOpen` method
  Add `media` option for parameter `entity`, `view` option for parameter `view` of actionButton method

---

---
url: /docs/concepts/commerce/checkout-concept.md
---

# Checkout

The checkout holds a series of steps to purchase items in your store. The checkout in Shopware deals with the entire process of turning a cart into an order and initiating all associated processes like payment, shipping, etc.

This section further focuses on carts, orders and payment.

---

---
url: /docs/guides/plugins/plugins/checkout.md
---

# Checkout

A checkout plugin in Shopware improves the checkout process for customers, offering features like guest checkout, custom fields, multiple payment options, address validation, order summaries, shopping cart, shipping method selection, and promotional code support. It ensures a smooth and efficient checkout experience for customers while providing businesses with the flexibility to meet their specific requirements.

---

---
url: /docs/v6.5/concepts/commerce/checkout-concept.md
---

# Checkout

The checkout holds a series of steps to purchase items in your store. The checkout in Shopware deals with the entire process of turning a cart into an order and initiating all associated processes like payment, shipping, etc.

This section further focuses on carts, orders and payment.

---

---
url: /docs/v6.5/guides/plugins/plugins/checkout.md
---

# Checkout

A checkout plugin in Shopware improves the checkout process for customers, offering features like guest checkout, custom fields, multiple payment options, address validation, order summaries, shopping cart, shipping method selection, and promotional code support. It ensures a smooth and efficient checkout experience for customers while providing businesses with the flexibility to meet their specific requirements.

---

---
url: /docs/v6.6/concepts/commerce/checkout-concept.md
---

# Checkout

The checkout holds a series of steps to purchase items in your store. The checkout in Shopware deals with the entire process of turning a cart into an order and initiating all associated processes like payment, shipping, etc.

This section further focuses on carts, orders and payment.

---

---
url: /docs/v6.6/guides/plugins/plugins/checkout.md
---

# Checkout

A checkout plugin in Shopware improves the checkout process for customers, offering features like guest checkout, custom fields, multiple payment options, address validation, order summaries, shopping cart, shipping method selection, and promotional code support. It ensures a smooth and efficient checkout experience for customers while providing businesses with the flexibility to meet their specific requirements.

---

---
url: /docs/resources/references/adr/2024-04-01-checkout-gateway.md
---

# Checkout gateway

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2024-04-01-checkout-gateway.md)
:::

# ADR: Enhanced Checkout Gateway Feature

## Context

In response to the evolving landscape of checkout decision-making, we propose the introduction of a centralized and opinionated solution.
This solution aims to facilitate informed decisions during the checkout process based on both the cart contents and the current sales channel context.
The app-system, in particular, stands to benefit significantly, enabling seamless communication with the app server.
Presently, achieving such functionality is constrained to app scripts, limiting the capacity for making nuanced decisions during checkout based on app server logic.

Moreover, payment and shipping providers necessitate specific criteria for determining the availability of their respective methods.
These criteria include considerations such as risk assessment related to the current customer and cart, unavailability criteria,
merchant connection status validation (e.g., checking for correct credentials), and service availability testing (e.g., detecting provider outages).
Additionally, these providers require the ability to block carts during checkout based on risk assessment decisions.

While this ADR focuses on the aforementioned features, the implementation is designed to allow for seamless future extensions.

## Decision

### CheckoutGatewayInterface

To address the outlined challenges, we propose the introduction of the CheckoutGatewayInterface.
This interface will be invoked during the checkout process to determine a response tailored to the current cart and sales channel context.

```php
<?php declare(strict_types=1);

namespace Shopware\Core\Checkout\Gateway;

use Shopware\Core\Checkout\Gateway\Command\Struct\CheckoutGatewayPayloadStruct;
use Shopware\Core\Framework\Log\Package;

#[Package('checkout')]
interface CheckoutGatewayInterface
{
    /**
    * The input struct consists of the cart, sales channel context and currently available payment and shipping methods.
    */
    public function process(CheckoutGatewayPayloadStruct): CheckoutGatewayResponse;
}
```

Plugin developers are encouraged to create custom implementations of the `CheckoutGatewayInterface` for their specific checkout logic based on decisions from external systems (e.g., ERP, PIM).

The `CheckoutGatewayResponse` will include an `EntityCollection` of payment and shipping methods suitable for the current context, along with a collection of `CartErrors`.
The input struct and the response is designed for future extension, allowing for more intricate decision-making during checkout.

#### Store-API

A new store API route, `CheckoutGatewayRoute` '/store-api/checkout/gateway', will be introduced.
This route will call a `CheckoutGatewayInterface` implementation and respond accordingly,
and is integral to `CartOrderRoute` requests, ensuring the cart's validity for checkout during the order process.

#### Storefront

The default invocation of the `CheckoutGatewayRoute` will occur during the checkout-confirm page and edit-order page (so-called "after order").
Any changes to the context (e.g., language, currency) will trigger a reload of the payment method selection, calling the app server again.

#### Checkout Gateway Commands

For streamlined response manipulation by plugins and app servers alike, we propose an executable chain of `CheckoutGatewayCommands`.
The implementation of the app-system will heavily rely on the command structure.
However, it is encouraged, but not mandatory for a custom implementation plugin-system implementation of the `CheckoutGatewayInterface` to follow the command structure.

These commands, chosen from a predefined set, can be responded with by plugins and app servers.
The initial release will include the following commands: `add-payment-method`, `remove-payment-method`, `add-shipping-method`, `remove-shipping-method`, and `add-cart-error`.
Depending on the command, the payload may differ, necessitating updates to the documentation.
We propose the use of a handler pattern, to facilitate the execution of these commands.
Commands will be executed in the order provided in the response.

### App-System

For the initial release, Shopware will support a single implementation of the `CheckoutGatewayInterface`, provided by the app-system.
The `AppCheckoutGateway` will sequentially call active apps, but only if the app has a defined `checkout-gateway-url` in its manifest.xml file.

#### App Manifest

To address challenges for apps, a new app endpoint can be defined in the manifest.xml.
A new key `gateways` will be added to the manifest file, with a sub-key `checkout` to define the endpoint.
The `gateways` key signalizes possible future similar endpoints for different purposes.
The checkout gateway endpoint is configured using a new element called `checkout`.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest>
    <!-- ... -->

    <gateways>
        <checkout>https://example.com/checkout/gateway</checkout>
    </gateways>
</manifest>
```

#### Checkout Gateway App Payload

The app server will receive the current `SalesChannelContext`, `Cart`, and available payment and shipping methods as part of the payload.
The `AppCheckoutGateway` will call the app server with this payload.

```json
{
    "salesChannelContext": SalesChannelContextObject,
    "cart": CartObject,
    "paymentMethods": [
        "payment-method-technical-name-1",
        "payment-method-technical-name-2",
        "payment-method-technical-name-3",
        ...
    ],
    "shippingMethods": [
        "shipping-method-technical-name-1",
        "shipping-method-technical-name-2",
        "shipping-method-technical-name-3",
        ...
    ]
}
```

Note that the paymentMethods and shippingMethods arrays will only contain the technical names of the methods, not the full entities.

#### Checkout Gateway App Response

```json
[
  {
    "command": "remove-payment-method",
    "payload": {
      "paymentMethodTechnicalName": "payment-myApp-payment-method"
    }
  },
  {
    "command": "add-cart-error",
    "payload": {
      "reason": "Payment method not available for this cart.",
      "level": 20,
      "blockOrder": true
    }
  }
]
```

#### Event

A new event `CheckoutGatewayCommandsCollectedEvent` will be introduced.
This event is dispatched after the `AppCheckoutGateway` has collected all commands from all app servers.
It allows plugins to manipulate the commands before they are executed, based on the same payload the app servers retrieve.

## Consequences

### App PHP SDK

The app-php-sdk will be enhanced to support the new endpoint and data types, ensuring seamless integration with the command structure.
The following adaptations will be made:

Checkout gateway requests with payload will be deserialized into a `CheckoutGatewayRequest` object.
Checkout gateway responses will be deserialized into a `CheckoutGatewayResponse` object.
Every possible checkout gateway command will have a class representing it, facilitating easy manipulation of its payload.

---

---
url: /docs/v6.6/resources/references/adr/2024-04-01-checkout-gateway.md
---

# Checkout gateway

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2024-04-01-checkout-gateway.md)
:::

# ADR: Enhanced Checkout Gateway Feature

## Context

In response to the evolving landscape of checkout decision-making, we propose the introduction of a centralized and opinionated solution.
This solution aims to facilitate informed decisions during the checkout process based on both the cart contents and the current sales channel context.
The app-system, in particular, stands to benefit significantly, enabling seamless communication with the app server.
Presently, achieving such functionality is constrained to app scripts, limiting the capacity for making nuanced decisions during checkout based on app server logic.

Moreover, payment and shipping providers necessitate specific criteria for determining the availability of their respective methods.
These criteria include considerations such as risk assessment related to the current customer and cart, unavailability criteria,
merchant connection status validation (e.g., checking for correct credentials), and service availability testing (e.g., detecting provider outages).
Additionally, these providers require the ability to block carts during checkout based on risk assessment decisions.

While this ADR focuses on the aforementioned features, the implementation is designed to allow for seamless future extensions.

## Decision

### CheckoutGatewayInterface

To address the outlined challenges, we propose the introduction of the CheckoutGatewayInterface.
This interface will be invoked during the checkout process to determine a response tailored to the current cart and sales channel context.

```php
<?php declare(strict_types=1);

namespace Shopware\Core\Checkout\Gateway;

use Shopware\Core\Checkout\Gateway\Command\Struct\CheckoutGatewayPayloadStruct;
use Shopware\Core\Framework\Log\Package;

#[Package('checkout')]
interface CheckoutGatewayInterface
{
    /**
    * The input struct consists of the cart, sales channel context and currently available payment and shipping methods.
    */
    public function process(CheckoutGatewayPayloadStruct): CheckoutGatewayResponse;
}
```

Plugin developers are encouraged to create custom implementations of the `CheckoutGatewayInterface` for their specific checkout logic based on decisions from external systems (e.g., ERP, PIM).

The `CheckoutGatewayResponse` will include an `EntityCollection` of payment and shipping methods suitable for the current context, along with a collection of `CartErrors`.
The input struct and the response is designed for future extension, allowing for more intricate decision-making during checkout.

#### Store-API

A new store API route, `CheckoutGatewayRoute` '/store-api/checkout/gateway', will be introduced.
This route will call a `CheckoutGatewayInterface` implementation and respond accordingly,
and is integral to `CartOrderRoute` requests, ensuring the cart's validity for checkout during the order process.

#### Storefront

The default invocation of the `CheckoutGatewayRoute` will occur during the checkout-confirm page and edit-order page (so-called "after order").
Any changes to the context (e.g., language, currency) will trigger a reload of the payment method selection, calling the app server again.

#### Checkout Gateway Commands

For streamlined response manipulation by plugins and app servers alike, we propose an executable chain of `CheckoutGatewayCommands`.
The implementation of the app-system will heavily rely on the command structure.
However, it is encouraged, but not mandatory for a custom implementation plugin-system implementation of the `CheckoutGatewayInterface` to follow the command structure.

These commands, chosen from a predefined set, can be responded with by plugins and app servers.
The initial release will include the following commands: `add-payment-method`, `remove-payment-method`, `add-shipping-method`, `remove-shipping-method`, and `add-cart-error`.
Depending on the command, the payload may differ, necessitating updates to the documentation.
We propose the use of a handler pattern, to facilitate the execution of these commands.
Commands will be executed in the order provided in the response.

### App-System

For the initial release, Shopware will support a single implementation of the `CheckoutGatewayInterface`, provided by the app-system.
The `AppCheckoutGateway` will sequentially call active apps, but only if the app has a defined `checkout-gateway-url` in its manifest.xml file.

#### App Manifest

To address challenges for apps, a new app endpoint can be defined in the manifest.xml.
A new key `gateways` will be added to the manifest file, with a sub-key `checkout` to define the endpoint.
The `gateways` key signalizes possible future similar endpoints for different purposes.
The checkout gateway endpoint is configured using a new element called `checkout`.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest>
    <!-- ... -->

    <gateways>
        <checkout>https://example.com/checkout/gateway</checkout>
    </gateways>
</manifest>
```

#### Checkout Gateway App Payload

The app server will receive the current `SalesChannelContext`, `Cart`, and available payment and shipping methods as part of the payload.
The `AppCheckoutGateway` will call the app server with this payload.

```json
{
    "salesChannelContext": SalesChannelContextObject,
    "cart": CartObject,
    "paymentMethods": [
        "payment-method-technical-name-1",
        "payment-method-technical-name-2",
        "payment-method-technical-name-3",
        ...
    ],
    "shippingMethods": [
        "shipping-method-technical-name-1",
        "shipping-method-technical-name-2",
        "shipping-method-technical-name-3",
        ...
    ]
}
```

Note that the paymentMethods and shippingMethods arrays will only contain the technical names of the methods, not the full entities.

#### Checkout Gateway App Response

```json
[
  {
    "command": "remove-payment-method",
    "payload": {
      "paymentMethodTechnicalName": "payment-myApp-payment-method"
    }
  },
  {
    "command": "add-cart-error",
    "payload": {
      "reason": "Payment method not available for this cart.",
      "level": 20,
      "blockOrder": true
    }
  }
]
```

#### Event

A new event `CheckoutGatewayCommandsCollectedEvent` will be introduced.
This event is dispatched after the `AppCheckoutGateway` has collected all commands from all app servers.
It allows plugins to manipulate the commands before they are executed, based on the same payload the app servers retrieve.

## Consequences

### App PHP SDK

The app-php-sdk will be enhanced to support the new endpoint and data types, ensuring seamless integration with the command structure.
The following adaptations will be made:

Checkout gateway requests with payload will be deserialized into a `CheckoutGatewayRequest` object.
Checkout gateway responses will be deserialized into a `CheckoutGatewayResponse` object.
Every possible checkout gateway command will have a class representing it, facilitating easy manipulation of its payload.

---

---
url: /docs/guides/plugins/apps/gateways/checkout/checkout-gateway.md
---

# Checkout Gateway

## Context

As of Shopware version 6.6.3.0, the Checkout Gateway was introduced.

The Checkout Gateway aims to enable a streamlined approach to making informed decisions during the checkout process, based on both the cart contents and the current sales channel context.
In particular, the app system benefits from this solution, enabling seamless communication and decision-making on the app server during checkout.

While this documentation focuses on the app integration of the Checkout Gateway, the design is intended to allow a custom replacement solution via the plugin system."

## Prerequisites

You should be familiar with the concept of Apps, their registration flow, and signing and verifying requests and responses between Shopware and the App backend server.

Your app server must also be accessible for the Shopware server.
You can use a tunneling service like [ngrok](https://ngrok.com/) for development.

## Manifest configuration

To indicate to Shopware that your app uses the checkout gateway, you must provide a `checkout` property inside a `gateways` parent property of your app's `manifest.xml`.

Below is an example definition of a working checkout gateway configuration.

::: code-group

```xml [manifest.xml]
<?xml version="1.0" encoding="UTF-8"?>
<manifest>
    <!-- ... -->

    <gateways>
        <checkout>https://my-app.server.com/checkout/gateway</checkout>
    </gateways>
</manifest>
```

:::

After your app is successfully installed, the checkout gateway will be used during checkout.

## Checkout gateway endpoint

During checkout, Shopware checks for any active checkout gateways and calls the `checkout` URL.
The app server will receive the current `SalesChannelContext`, `Cart`, and available payment and shipping methods as part of the payload.

::: warning
**Connection timeouts**

The Shopware shop will wait for a response for 5 seconds.
Be sure that your checkout gateway implementation on your app server responds in time, otherwise Shopware will time out and drop the connection.
:::

Your app server can then respond with a list of commands to manipulate the cart, payment methods, shipping methods, or add cart errors.

You can find a reference to all currently [available commands](./command-reference.md).

Let's assume that your payment method is not available for carts with a total price above 1000€.

Request content is JSON

```json5
{
  "source": {
    "url": "http:\/\/localhost:8000",
    "shopId": "hRCw2xo1EDZnLco4",
    "appVersion": "1.0.0"
 },
  "cart": {
    //...
 },
  "salesChannelContext": {
    //...
 },
  "availablePaymentMethods": [
    "payment-method-technical-name-1",
    "payment-method-technical-name-2",
    // ...
 ],
  "availableShippingMethods": [
    "shipping-method-technical-name-1",
    "shipping-method-technical-name-2",
    // ...
 ]
}
```

And your response could look like this:

```json5
{
  "commands": [
 {
      "command": "remove-payment-method",
      "payload": {
        "paymentMethodTechnicalName": "payment-myApp-payment-method"
 }
 },
 {
      "command": "add-cart-error",
      "payload": {
        "message": "Payment method 'My App Payment Method' is not available for carts > 1000€.",
        "blocking": false,
        "level": 10,
 }
 }
 ]
}
```

With version `3.0.0`, support for the checkout gateway has been added to the `app-php-sdk`.
The SDK will handle the communication with the Shopware shop and provide you with a convenient way to handle the incoming payload and respond with the necessary commands.

```php
<?php declare(strict_types=1);

use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;
use Shopware\App\SDK\Context\Cart\Error;
use Shopware\App\SDK\Context\ContextResolver;
use Shopware\App\SDK\Framework\Collection;
use Shopware\App\SDK\Gateway\Checkout\CheckoutGatewayCommand;
use Shopware\App\SDK\Gateway\Checkout\Command\AddCartErrorCommand;
use Shopware\App\SDK\Gateway\Checkout\Command\RemovePaymentMethodCommand;
use Shopware\App\SDK\Response\GatewayResponse;
use Shopware\App\SDK\Shop\ShopResolver;

function gatewayController(RequestInterface $request): ResponseInterface
{
    // injected or built by yourself
    $shopResolver = new ShopResolver($repository);
    $contextResolver = new ContextResolver();
    $signer = new ResponseSigner();
    
    $shop = $shopResolver->resolveShop($request);
    
    /** @var Shopware\App\SDK\Context\Gateway\Checkout\CheckoutGatewayAction $action */
    $action = $contextResolver->assembleCheckoutGatewayRequest($request, $shop);

    /** @var Collection<Shopware\App\SDK\Gateway\Checkout\CheckoutGatewayCommand> $commands */
    $commands = new Collection();

    if ($action->paymentMethods->has('payment-myApp-payment-method')) {
        if ($action->cart->getPrice()->getTotalPrice() > 1000) {
            $commands->add(new RemovePaymentMethodCommand('payment-myApp-payment-method'));
            $commands->add(new AddCartErrorCommand('Payment method \'My App Payment Method\' is not available for carts > 1000€.', false, Error::LEVEL_WARNING));
        }
    }

    $response = GatewayResponse::createCheckoutGatewayResponse($commands);

    return $signer->sign($response);
}
```

```php
<?php declare(strict_types=1);

namespace App\Controller;

use Shopware\App\SDK\Context\Cart\Error;
use Shopware\App\SDK\Context\Gateway\Checkout\CheckoutGatewayAction;
use Shopware\App\SDK\Framework\Collection;
use Shopware\App\SDK\Gateway\Checkout\CheckoutGatewayCommand;
use Shopware\App\SDK\Gateway\Checkout\Command\AddCartErrorCommand;
use Shopware\App\SDK\Response\GatewayResponse;
use Symfony\Bridge\PsrHttpMessage\HttpFoundationFactoryInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

#[Route('/api/gateway', name: 'api.gateway.')]
class GatewayController extends AbstractController
{
    public function __construct(
        private readonly HttpFoundationFactoryInterface $httpFoundationFactory
    ) {
    }

 #[Route('/checkout', name: 'checkout', methods: ['POST'])]
    public function checkout(CheckoutGatewayAction $action): Response
    {
        /** @var Collection<CheckoutGatewayCommand> $commands */
        $commands = new Collection();

        if ($action->paymentMethods->has('payment-myApp-payment-method')) {
            if ($action->cart->getPrice()->getTotalPrice() > 1000) {
                $commands->add(new RemovePaymentMethodCommand('payment-myApp-payment-method'));
                $commands->add(new AddCartErrorCommand('Payment method \'My App Payment Method\' is not available for carts > 1000€.', false, Error::LEVEL_WARNING));
            }
        }

        $response = GatewayResponse::createCheckoutGatewayResponse($commands);

        return $this->httpFoundationFactory->createResponse($response);
    }
}
```

## Event

Plugins can listen to the `Shopware\Core\Checkout\Gateway\Command\Event\CheckoutGatewayCommandsCollectedEvent`.
This event is dispatched after the Checkout Gateway has collected all commands from all app servers.
It allows plugins to manipulate the commands before they are executed, based on the same payload that the app servers retrieved.

---

---
url: /docs/v6.6/guides/plugins/apps/gateways/checkout/checkout-gateway.md
---
# Checkout Gateway

## Context

As of Shopware version 6.6.3.0, the Checkout Gateway was introduced.

The Checkout Gateway aims to allow a streamlined implementation for making informed decisions during the checkout process, based on both the cart contents and the current sales channel context.
In particular, the app system benefits from this solution, enabling seamless communication and decision-making on the app server during the checkout.

While this documentation focuses on the app integration of the Checkout Gateway, the design is intended to allow a custom replacement solution via the plugin system."

## Prerequisites

You should be familiar with the concept of Apps, their registration flow as well as signing and verifying requests and responses between Shopware and the App backend server.

Your app server must be also accessible for the Shopware server.
You can use a tunneling service like [ngrok](https://ngrok.com/) for development.

## Manifest configuration

To indicate to Shopware that your app uses the checkout gateway, you must provide a `checkout` property inside a `gateways` parent property of your app's `manifest.xml`.

Below, you can see an example definition of a working checkout gateway configuration.

::: code-group

```xml [manifest.xml]
<?xml version="1.0" encoding="UTF-8"?>
<manifest>
    <!-- ... -->

    <gateways>
        <checkout>https://my-app.server.com/checkout/gateway</checkout>
    </gateways>
</manifest>
```

:::

After successful installation of your app, the checkout gateway will already be used during checkout.

## Checkout gateway endpoint

During checkout, Shopware checks for any active checkout gateways and will call the `checkout` url.
The app server will receive the current `SalesChannelContext`, `Cart`, and available payment and shipping methods as part of the payload.

::: warning
**Connection timeouts**

The Shopware shop will wait for a response for 5 seconds.
Be sure that your checkout gateway implementation on your app server responds in time, otherwise Shopware will time out and drop the connection.
:::

Your app server can then respond with a list of commands to manipulate the cart, payment methods, shipping methods, or add cart errors.

You can find a reference of all currently available commands [here](./command-reference.md).

Let's assume that your payment method is not available for carts with a total price above 1000€.

Request content is JSON

```json5
{
  "source": {
    "url": "http:\/\/localhost:8000",
    "shopId": "hRCw2xo1EDZnLco4",
    "appVersion": "1.0.0"
  },
  "cart": {
    //...
  },
  "salesChannelContext": {
    //...
  },
  "availablePaymentMethods": [
    "payment-method-technical-name-1",
    "payment-method-technical-name-2",
    // ...
  ],
  "availableShippingMethods": [
    "shipping-method-technical-name-1",
    "shipping-method-technical-name-2",
    // ...
  ]
}
```

And your response could look like this:

```json5
{
  "commands": [
    {
      "command": "remove-payment-method",
      "payload": {
        "paymentMethodTechnicalName": "payment-myApp-payment-method"
      }
    },
    {
      "command": "add-cart-error",
      "payload": {
        "message": "Payment method 'My App Payment Method' is not available for carts > 1000€.",
        "blocking": false,
        "level": 10,
      }
    }
  ]
}
```

With version `3.0.0`, support for the checkout gateway has been added to the `app-php-sdk`.
The SDK will handle the communication with the Shopware shop and provide you with a convenient way to handle the incoming payload and respond with the necessary commands.

```php
<?php declare(strict_types=1);

use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;
use Shopware\App\SDK\Context\Cart\Error;
use Shopware\App\SDK\Context\ContextResolver;
use Shopware\App\SDK\Framework\Collection;
use Shopware\App\SDK\Gateway\Checkout\CheckoutGatewayCommand;
use Shopware\App\SDK\Gateway\Checkout\Command\AddCartErrorCommand;
use Shopware\App\SDK\Gateway\Checkout\Command\RemovePaymentMethodCommand;
use Shopware\App\SDK\Response\GatewayResponse;
use Shopware\App\SDK\Shop\ShopResolver;

function gatewayController(RequestInterface $request): ResponseInterface
{
    // injected or build by yourself
    $shopResolver = new ShopResolver($repository);
    $contextResolver = new ContextResolver();
    $signer = new ResponseSigner();
    
    $shop = $shopResolver->resolveShop($request);
    
    /** @var Shopware\App\SDK\Context\Gateway\Checkout\CheckoutGatewayAction $action */
    $action = $contextResolver->assembleCheckoutGatewayRequest($request, $shop);

    /** @var Collection<Shopware\App\SDK\Gateway\Checkout\CheckoutGatewayCommand> $commands */
    $commands = new Collection();

    if ($action->paymentMethods->has('payment-myApp-payment-method')) {
        if ($action->cart->getPrice()->getTotalPrice() > 1000) {
            $commands->add(new RemovePaymentMethodCommand('payment-myApp-payment-method'));
            $commands->add(new AddCartErrorCommand('Payment method \'My App Payment Method\' is not available for carts > 1000€.', false, Error::LEVEL_WARNING));
        }
    }

    $response = GatewayResponse::createCheckoutGatewayResponse($commands);

    return $signer->sign($response);
}
```

```php
<?php declare(strict_types=1);

namespace App\Controller;

use Shopware\App\SDK\Context\Cart\Error;
use Shopware\App\SDK\Context\Gateway\Checkout\CheckoutGatewayAction;
use Shopware\App\SDK\Framework\Collection;
use Shopware\App\SDK\Gateway\Checkout\CheckoutGatewayCommand;
use Shopware\App\SDK\Gateway\Checkout\Command\AddCartErrorCommand;
use Shopware\App\SDK\Response\GatewayResponse;
use Symfony\Bridge\PsrHttpMessage\HttpFoundationFactoryInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

#[Route('/api/gateway', name: 'api.gateway.')]
class GatewayController extends AbstractController
{
    public function __construct(
        private readonly HttpFoundationFactoryInterface $httpFoundationFactory
    ) {
    }

    #[Route('/checkout', name: 'checkout', methods: ['POST'])]
    public function checkout(CheckoutGatewayAction $action): Response
    {
        /** @var Collection<CheckoutGatewayCommand> $commands */
        $commands = new Collection();

        if ($action->paymentMethods->has('payment-myApp-payment-method')) {
            if ($action->cart->getPrice()->getTotalPrice() > 1000) {
                $commands->add(new RemovePaymentMethodCommand('payment-myApp-payment-method'));
                $commands->add(new AddCartErrorCommand('Payment method \'My App Payment Method\' is not available for carts > 1000€.', false, Error::LEVEL_WARNING));
            }
        }

        $response = GatewayResponse::createCheckoutGatewayResponse($commands);

        return $this->httpFoundationFactory->createResponse($response);
    }
}
```

## Event

Plugins can listen to the `Shopware\Core\Checkout\Gateway\Command\Event\CheckoutGatewayCommandsCollectedEvent`.
This event is dispatched after the Checkout Gateway has collected all commands from all app servers.
It allows plugins to manipulate the commands before they are executed, based on the same payload the app servers retrieved.

---

---
url: /docs/guides/plugins/apps/gateways/checkout/command-reference.md
---

# Checkout Gateway Command Reference

| Command                  | Description                                                                                                                                                  | Payload                                                        | Since   |
|:-------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------|:--------|
| `remove-payment-method`  | Removes a payment method from the available payment methods.                                                                                                 | `{"paymentMethodTechnicalName": "string"}`                     | 6.6.3.0 |
| `remove-shipping-method` | Removes a shipping method from the available shipping methods.                                                                                               | `{"shippingMethodTechnicalName": "string"}`                    | 6.6.3.0 |
| `add-cart-error`         | Adds an error to the cart. The level decides the severity of the cart error flash message. Blocking decides, whether to block the checkout for the customer. | `{"message": "string", "level": "int", "blocking": "boolean"}` | 6.6.3.0 |

---

---
url: /docs/v6.6/guides/plugins/apps/gateways/checkout/command-reference.md
---
# Checkout Gateway Command Reference

| Command                  | Description                                                                                                                                                  | Payload                                                        | Since   |
|:-------------------------|:-------------------------------------------------------------------------------------------------------------------------------------------------------------|:---------------------------------------------------------------|:--------|
| `remove-payment-method`  | Removes a payment method from the available payment methods.                                                                                                 | `{"paymentMethodTechnicalName": "string"}`                     | 6.6.3.0 |
| `remove-shipping-method` | Removes a shipping method from the available shipping methods.                                                                                               | `{"shippingMethodTechnicalName": "string"}`                    | 6.6.3.0 |
| `add-cart-error`         | Adds an error to the cart. The level decides the severity of the cart error flash message. Blocking decides, whether to block the checkout for the customer. | `{"message": "string", "level": "int", "blocking": "boolean"}` | 6.6.3.0 |

---

---
url: /docs/resources/guidelines/code/core/ci-workflows.md
---
::: info
This document represents core guidelines and has been mirrored from the core in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/coding-guidelines/core/ci-workflows.md)
:::

# CI workflows

The rules for `.github/` are in [`.github/AGENTS.md`](../../.github/AGENTS).
This document holds only what does not fit there: why the rules are shaped the
way they are, and the examples that make them concrete. Read it when reviewing a
CI change, or before changing one of the rules.

## Fix it at the lowest layer that covers everyone

A unit test ran a Symfony console `Application` through `ApplicationTester`
without `setAutoExit(false)`. `Application::run()` called
`exit(0)`, PHPUnit died mid-suite, no report was written — and the job reported
success. Every later test silently did not run and Codecov stopped receiving
coverage. Full write-up in
[issue #18661](https://github.com/shopware/shopware/issues/18661).

The lesson is not "remember `setAutoExit(false)`". Nobody writing a
console-command test is thinking about job exit-code semantics, and no reviewer
catches it either. The fix has to sit somewhere that does not depend on anyone
remembering — hence the ordering in `.github/AGENTS.md`.

Why the guard ended up in `TestBootstrapper` and not in the workflow is the
clearest illustration. The first attempt asserted that `junit.xml` existed after
the run. That works, but it has to be repeated in every job that needs it, and
the nightlies contain jobs that produce no JUnit report at all — those would have
stayed unprotected. `CompletionGuard` sits in the bootstrapper, so core suites,
plugins, and downstream projects are covered at once with no `phpunit.xml`
wiring. A guard one layer down is worth several assertions one layer up.

The same reasoning applies to assertions you *do* have to write in a job: assert
what the run **produces**, not what the runner set up, and do not assert on an
artifact that some matrix legs legitimately never create — that pushes people
toward weakening the shared assertion until it proves nothing.

Guards are easy to test badly, because a guard is only ever observed *not*
firing. Extract the decision into a pure function and unit-test both branches;
`CompletionGuard::shouldForceFailure()` with `CompletionGuardTest` is the
pattern.

## Why suppression is treated strictly

`continue-on-error`, `|| true`, `set +e`, `if: always()`, and retries are all
legitimate somewhere and corrosive everywhere else, so the rule asks for a
comment on each use rather than banning them.

`|| true` is the one that most often hides a real failure, because it discards
the distinction between "expected non-zero" and "broken". Capture the code and
check it instead:

```bash
# Bad — a crash and a clean "no match" are now the same thing
some-check || true

# Good — exit 1 is the expected "nothing found", anything else is a failure
set +e
some-check
status=$?
set -e
if [ "$status" -ne 0 ] && [ "$status" -ne 1 ]; then
  echo "some-check failed unexpectedly (exit $status)" >&2
  exit "$status"
fi
```

Retries deserve their own argument. A retry around a test run does not just hide
one red run — it removes the flake rate as a measurable quantity, so the
underlying bug never gets prioritised. A flaky test is a bug report; wrapping it
in a retry converts it into a permanently invisible one. Retries are for network
and infrastructure only.

The general form: **do not make a job green by suppressing information.** When a
job genuinely should not run, skip it with a documented `if:` condition — a
skipped job is visible in the UI, a suppressed failure is not.

## Gotchas worth knowing

* `set -euo pipefail` is required, but `pipefail` turns an early-exiting
  downstream command into a `SIGPIPE` failure. Commit `04d02efd2eb` fixed exactly
  this in the markdown-only change detection.
* `.github/actions/phpunit-upload` asks callers for `if: !cancelled()` rather
  than `always()`, so a cancelled run stops instead of continuing to upload.
  Prefer `!cancelled()` wherever you would reach for `always()`.
* Action hash pinning is enforced by zizmor's `unpinned-uses` audit, configured
  in `.github/zizmor.yml` and run from `composer lint:actions`. zizmor is adopted
  one audit at a time; the remaining audits are disabled there and report a few
  hundred findings between them, so enabling one is its own piece of work.
* zizmor cannot parse a workflow whose `strategy:` is a dynamic
  ${{ fromJson(...) }} matrix, and it *warns and exits 0* rather than failing —
  an unparsed file is an unaudited file. `zizmor-collection-guard.ts` reconciles
  those warnings against a known list so a new one fails the lint, and so a
  listed file that starts parsing again is reported as a stale entry.

## Reviewing a CI change

1. **If this step did nothing at all, would the job still be green?** If yes, the
   job is not asserting anything.
2. Does any new `continue-on-error`, `|| true`, `set +e`, `if: always()`, or
   retry carry a comment explaining why?
3. Is there `run:` logic that a unit test could have covered?
4. Are new third-party actions pinned to a hash?
5. Has the change actually been run — and, for a guard, been seen to fail?

## Related

* Tests must not terminate the process: [`unit-tests.md`](unit-tests) and the
  `shopware-phpunit-tests` skill.
* Agent skills and their unattended CI twins: [`agent-skills.md`](agent-skills).
* gh aw setup, pinning, and secrets: [`.github/aw/README.md`](../../.github/aw/).

---

---
url: /docs/v6.5/resources/tooling/cli.md
---

# CLI

---

---
url: /docs/v6.6/resources/tooling/cli.md
---

# CLI

---

---
url: /docs/v6.5/products/paas/cli-setup.md
---

# CLI Setup

The CLI is your tool to connect with your PaaS environment, push changes, trigger deployments, etc.

## Download and install

To install PaaS CLI, run the following command:

```sh
curl -sfS https://cli.shopware.com/installer | php
```

When you run the CLI for the first time, it will ask you to log in via your browser.

You can also generate an SSH key manually and add it in the **My profile > SSH Keys** section of your [PaaS Console](https://console.shopware.com/).

::: info
**Set up SSH keys**

If you are unsure of how to create SSH keys, please follow [this tutorial](https://docs.github.com/en/authentication/connecting-to-github-with-ssh/generating-a-new-ssh-key-and-adding-it-to-the-ssh-agent) provided by GitHub.
:::

## Authenticate

Next, you need to authenticate your CLI. This can be done through your browser. Just run the following command and follow the instructions:

```sh
shopware
```

---

---
url: /docs/v6.6/products/sales-agent/routing.md
---

# Client and Server Routing

Refer to the Nuxt documentation for more information about how [server](https://nuxt.com/docs/guide/directory-structure/server) and [client](https://nuxt.com/docs/guide/directory-structure/pages) routes work internally.

For an up-to-date overview of all routes for this application, you can use the [Nuxt dev tools](https://devtools.nuxt.com/). This should be enabled by default during local development.

---

---
url: /docs/resources/references/adr/2023-06-27-store-api-to-app-server.md
---

# Client side communication to App Server

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2023-06-27-store-api-to-app-server.md)
:::

## Context

Right now only Shopware Backend is able to communicate with the App Server in a secure way.
This is because the App Server is able to verify the origin of the request by checking request signature,
and this signature is generated by the Shopware 6 backend application with a shop to app server secret.

When an app wants to communicate directly with the App Server,
the App Server is not able to verify the origin of the request and has to trust the client.
This works fine for public available data, but not when you reliably need the logged-in customer and other information.

## Decision

We provide a new endpoint `/store-api/app-system/{appName}/generate-token` (`/app-system/{appName}/generate-token` in Storefront) which generates a JWT token for the given app.
This endpoint requires that the customer is logged-in and the app is installed and active.

The JWT token contains claims like:

* `iat` - issued at
* `exp` - expiration time
* `shopId` - the shop id of the current shop
* `salesChannelId` - the sales channel id of the current sales channel
* `customerId` - the customer id of the logged-in customer
* `cartToken` - the cart token of the current cart

The additional claims are bound to app permissions when an app does not have permissions to read a customer,
it does not get the `customerId` claim.

The JWT token is signed with the shop to app server secret key which we use already for the signature.
So the App Server needs to be able to verify the JWT key and use the claims in a secure way.
The request body of the client is still untrusted and has to be properly validated by the app server.

The request cycle would look like this:

```mermaid
sequenceDiagram
    participant Client
    participant Shopware Backend
    participant App Server
    Client->>Shopware Backend: GET /store-api/app-system/TestApp/generate-token
    Shopware Backend->>Client: Responds with Signed JWT Token
    Client->>App Server: Post /product-review/submit containing JWT in header
```

The JWT token is valid for 15 minutes and can be used multiple times until expired.
The client should save it in the [session storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage)
and request it only on expiry again.
Additionally, the API route should be rate limited to not generate too often an expensive JWT key.

## Consequences

* We add a helper for the Storefront to obtain the token and do the expiry and regenerating
* We add support for JWT token verification in our PHP App SDK to make this process simple as possible

---

---
url: /docs/v6.5/resources/references/adr/2023-06-27-store-api-to-app-server.md
---

# Client side communication to App Server

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2023-06-27-store-api-to-app-server.md)
:::

## Context

Right now only Shopware Backend is able to communicate with the App Server in a secure way.
This is because the App Server is able to verify the origin of the request by checking request signature,
and this signature is generated by the Shopware 6 backend application with a shop to app server secret.

When an app wants to communicate directly with the App Server,
the App Server is not able to verify the origin of the request and has to trust the client.
This works fine for public available data, but not when you reliably need the logged-in customer and other information.

## Decision

We provide a new endpoint `/store-api/app-system/{appName}/generate-token` (`/app-system/{appName}/generate-token` in Storefront) which generates a JWT token for the given app.
This endpoint requires that the customer is logged-in and the app is installed and active.

The JWT token contains claims like:

* `iat` - issued at
* `exp` - expiration time
* `shopId` - the shop id of the current shop
* `salesChannelId` - the sales channel id of the current sales channel
* `customerId` - the customer id of the logged-in customer
* `cartToken` - the cart token of the current cart

The additional claims are bound to app permissions when an app does not have permissions to read a customer,
it does not get the `customerId` claim.

The JWT token is signed with the shop to app server secret key which we use already for the signature.
So the App Server needs to be able to verify the JWT key and use the claims in a secure way.
The request body of the client is still untrusted and has to be properly validated by the app server.

The request cycle would look like this:

```mermaid
sequenceDiagram
    participant Client
    participant Shopware Backend
    participant App Server
    Client->>Shopware Backend: GET /store-api/app-system/TestApp/generate-token
    Shopware Backend->>Client: Responds with Signed JWT Token
    Client->>App Server: Post /product-review/submit containing JWT in header
```

The JWT token is valid for 15 minutes and can be used multiple times until expired.
The client should save it in the [session storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage)
and request it only on expiry again.
Additionally, the API route should be rate limited to not generate too often an expensive JWT key.

## Consequences

* We add a helper for the Storefront to obtain the token and do the expiry and regenerating
* We add support for JWT token verification in our PHP App SDK to make this process simple as possible

---

---
url: /docs/v6.6/resources/references/adr/2023-06-27-store-api-to-app-server.md
---

# Client side communication to App Server

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2023-06-27-store-api-to-app-server.md)
:::

## Context

Right now only Shopware Backend is able to communicate with the App Server in a secure way.
This is because the App Server is able to verify the origin of the request by checking request signature,
and this signature is generated by the Shopware 6 backend application with a shop to app server secret.

When an app wants to communicate directly with the App Server,
the App Server is not able to verify the origin of the request and has to trust the client.
This works fine for public available data, but not when you reliably need the logged-in customer and other information.

## Decision

We provide a new endpoint `/store-api/app-system/{appName}/generate-token` (`/app-system/{appName}/generate-token` in Storefront) which generates a JWT token for the given app.
This endpoint requires that the customer is logged-in and the app is installed and active.

The JWT token contains claims like:

* `iat` - issued at
* `exp` - expiration time
* `shopId` - the shop id of the current shop
* `salesChannelId` - the sales channel id of the current sales channel
* `customerId` - the customer id of the logged-in customer
* `cartToken` - the cart token of the current cart

The additional claims are bound to app permissions when an app does not have permissions to read a customer,
it does not get the `customerId` claim.

The JWT token is signed with the shop to app server secret key which we use already for the signature.
So the App Server needs to be able to verify the JWT key and use the claims in a secure way.
The request body of the client is still untrusted and has to be properly validated by the app server.

The request cycle would look like this:

```mermaid
sequenceDiagram
    participant Client
    participant Shopware Backend
    participant App Server
    Client->>Shopware Backend: GET /store-api/app-system/TestApp/generate-token
    Shopware Backend->>Client: Responds with Signed JWT Token
    Client->>App Server: Post /product-review/submit containing JWT in header
```

The JWT token is valid for 15 minutes and can be used multiple times until expired.
The client should save it in the [session storage](https://developer.mozilla.org/en-US/docs/Web/API/Window/sessionStorage)
and request it only on expiry again.
Additionally, the API route should be rate limited to not generate too often an expensive JWT key.

## Consequences

* We add a helper for the Storefront to obtain the token and do the expiry and regenerating
* We add support for JWT token verification in our PHP App SDK to make this process simple as possible

---

---
url: /docs/v6.5/guides/plugins/apps/clientside-to-app-backend.md
---

# Client-App backend communication

Direct communication from the browser to the app backend involves generating a JSON Web Token (JWT).
This token contains session-specific information, as [claims](#the-json-web-token), and is securely signed by the shop.
This mechanism ensures a secure exchange of data between the client and the app backend.

::: warning
The JWT can be only generated when in the browser the user is logged-in.
:::

## The Flow

```mermaid
sequenceDiagram
    participant Client
    participant Shopware Backend
    participant App Server
    Client->>Shopware Backend: POST /store-api/app-system/MyApp/generate-token
    Shopware Backend->>Client: Responds with signed JWT
    Client->>App Server: Post /product-review/submit containing JWT in header
```

## The JSON Web Token

The JWT contains the following claims:

* `languageId` - the language ID of the current session
* `currencyId` - the currency ID of the current session
* `customerId` - the customer ID of the current session
* `countryId` - the country ID of the current session
* `salesChannelId` - the sales channel ID of the current session

The claims are only set when the app has permission to that specific entity like `sales_channel:read` for `salesChannelId` claim.

The JWT is signed with `SHA256-HMAC` and the secret is the `appSecret` from the app registration and the `issued by` is the shopId also from the registration.

## Generate JSON Web Token

The JWT is generated with a POST request against `/store-api/app-system/{name}/generate-token` or `/app-system/{name}/generate-token`.

For the Storefront usage, there is a HTTP client helper, which handles the token generation and lets you directly call your app backend.

```javascript
import AppClient from 'src/service/app-client.service.ts';

const client = new AppClient('MyAppName');

// the second parameter is 
client.get('https://my-app-backend.com/foo', {
    headers: {}, // the parameters are same as https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch
})
client.put('https://my-app-backend.com/foo')
client.post('https://my-app-backend.com/foo')
client.patch('https://my-app-backend.com/foo')
client.delete('https://my-app-backend.com/foo')
```

If you want to generate the JWT yourself, you can use the following code snippet:

```javascript
const response = await fetch('/store-api/app-system/{name}/generate-token', {
    method: 'POST'
});

// send token as 'shopware-app-token' header and shopId as 'shopware-app-shop-id' header to your app server.
const { token, shopId } = await response.json();
```

::: info
Requesting from the browser to the app backend is only possible when your app backend allows [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) requests. Example:

* Access-Control-Allow-Origin: \*
* Access-Control-Allow-Methods: GET, POST, OPTIONS
* Access-Control-Allow-Headers: shopware-app-shop-id, shopware-app-token
  :::

## Validate the JSON Web Token

```php
$shop = $shopResolver->resolveShop($serverRequest);

$storefront = $contextResolver->assembleStorefrontRequest($serverRequest, $shop);

$storefront->claims->getCustomerId();
```

The request from the Storefront to your app server will require that you set up CORS on your application.
We recommend [NelmioCorsBundle](https://symfony.com/bundles/NelmioCorsBundle/current/index.html) for this with allowed headers:
`shopware-app-shop-id, shopware-app-token` and allowed origin `*`.

```php
use Shopware\App\SDK\Context\Storefront\StorefrontAction;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\AsController;
use Symfony\Component\Routing\Annotation\Route;

#[AsController]
class StorefrontController {
    #[Route('/storefront/action')]
    public function handle(StorefrontAction $webhook): Response
    {
        // handle action
        
        return new Response(null, 204);
    }
}
```

Fetch the shop by the `shopware-app-shop-id` header and create a JWT verifier with the app secret as `HMAC-SHA256` secret.
Verify the JWT (shopware-app-token) with the verifier.

---

---
url: /docs/v6.6/guides/plugins/apps/clientside-to-app-backend.md
---

# Client-App backend communication

Direct communication from the browser to the app backend involves generating a JSON Web Token (JWT).
This token contains session-specific information, as [claims](#the-json-web-token), and is securely signed by the shop.
This mechanism ensures a secure exchange of data between the client and the app backend.

::: warning
The JWT can be only generated when in the browser the user is logged-in.
:::

## The Flow

```mermaid
sequenceDiagram
    participant Client
    participant Shopware Backend
    participant App Server
    Client->>Shopware Backend: POST /store-api/app-system/MyApp/generate-token
    Shopware Backend->>Client: Responds with signed JWT
    Client->>App Server: Post /product-review/submit containing JWT in header
```

## The JSON Web Token

The JWT contains the following claims:

* `languageId` - the language ID of the current session
* `currencyId` - the currency ID of the current session
* `customerId` - the customer ID of the current session
* `countryId` - the country ID of the current session
* `salesChannelId` - the sales channel ID of the current session

The claims are only set when the app has permission to that specific entity like `sales_channel:read` for `salesChannelId` claim.

The JWT is signed with `SHA256-HMAC` and the secret is the `appSecret` from the app registration and the `issued by` is the shopId also from the registration.

## Generate JSON Web Token

The JWT is generated with a POST request against `/store-api/app-system/{name}/generate-token` or `/app-system/{name}/generate-token`.

For the Storefront usage, there is a HTTP client helper, which handles the token generation and lets you directly call your app backend.

```javascript
import AppClient from 'src/service/app-client.service.ts';

const client = new AppClient('MyAppName');

// the second parameter is 
client.get('https://my-app-backend.com/foo', {
    headers: {}, // the parameters are same as https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch
})
client.put('https://my-app-backend.com/foo')
client.post('https://my-app-backend.com/foo')
client.patch('https://my-app-backend.com/foo')
client.delete('https://my-app-backend.com/foo')
```

If you want to generate the JWT yourself, you can use the following code snippet:

```javascript
const response = await fetch('/store-api/app-system/{name}/generate-token', {
    method: 'POST'
});

// send token as 'shopware-app-token' header and shopId as 'shopware-app-shop-id' header to your app server.
const { token, shopId } = await response.json();
```

::: info
Requesting from the browser to the app backend is only possible when your app backend allows [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) requests. Example:

* Access-Control-Allow-Origin: \*
* Access-Control-Allow-Methods: GET, POST, OPTIONS
* Access-Control-Allow-Headers: shopware-app-shop-id, shopware-app-token
  :::

## Validate the JSON Web Token

```php
$shop = $shopResolver->resolveShop($serverRequest);

$storefront = $contextResolver->assembleStorefrontRequest($serverRequest, $shop);

$storefront->claims->getCustomerId();
```

The request from the Storefront to your app server will require that you set up CORS on your application.
We recommend [NelmioCorsBundle](https://symfony.com/bundles/NelmioCorsBundle/current/index.html) for this with allowed headers:
`shopware-app-shop-id, shopware-app-token` and allowed origin `*`.

```php
use Shopware\App\SDK\Context\Storefront\StorefrontAction;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\AsController;
use Symfony\Component\Routing\Attribute\Route;

#[AsController]
class StorefrontController {
    #[Route('/storefront/action')]
    public function handle(StorefrontAction $webhook): Response
    {
        // handle action
        
        return new Response(null, 204);
    }
}
```

Fetch the shop by the `shopware-app-shop-id` header and create a JWT verifier with the app secret as `HMAC-SHA256` secret.
Verify the JWT (shopware-app-token) with the verifier.

---

---
url: /docs/guides/plugins/apps/lifecycle/clientside-to-app-backend.md
---

# Client-Side App Backend Communication

## Overview

Direct communication from the browser to the app backend involves generating a JSON Web Token (JWT).
This token contains session-specific information, as [claims](#the-json-web-token), and is securely signed by the shop.
This mechanism ensures a secure exchange of data between the client and the app backend.

::: warning
The JWT can be only generated when in the browser the user is logged-in.
:::

## The Flow

```mermaid
sequenceDiagram
    participant Client
    participant Shopware Backend
    participant App Server
    Client->>Shopware Backend: POST /store-api/app-system/MyApp/generate-token
    Shopware Backend->>Client: Responds with signed JWT
    Client->>App Server: Post /product-review/submit containing JWT in header
```

## The JSON Web Token

The JWT contains the following claims:

* `languageId` - the language ID of the current session
* `currencyId` - the currency ID of the current session
* `customerId` - the customer ID of the current session
* `countryId` - the country ID of the current session
* `salesChannelId` - the sales channel ID of the current session

The claims are only set when the app has permission to that specific entity like `sales_channel:read` for `salesChannelId` claim.

The JWT is signed with `SHA256-HMAC` and the secret is the `appSecret` from the app registration and the `issued by` is the shopId also from the registration.

## Generate JSON Web Token

::: info
This feature has been introduced with Shopware version 6.5.5.0
:::

The JWT is generated with a POST request against `/store-api/app-system/{name}/generate-token` or `/app-system/{name}/generate-token`.

For the Storefront usage, there is a HTTP client helper, which handles the token generation and lets you directly call your app backend.

```javascript
import AppClient from 'src/service/app-client.service.ts';

const client = new AppClient('MyAppName');

// the second parameter is 
client.get('https://my-app-backend.com/foo', {
    headers: {}, // the parameters are same as https://developer.mozilla.org/en-US/docs/Web/API/Fetch_API/Using_Fetch
})
client.put('https://my-app-backend.com/foo')
client.post('https://my-app-backend.com/foo')
client.patch('https://my-app-backend.com/foo')
client.delete('https://my-app-backend.com/foo')
```

If you want to generate the JWT yourself, you can use the following code snippet:

```javascript
const response = await fetch('/store-api/app-system/{name}/generate-token', {
    method: 'POST'
});

// send token as 'shopware-app-token' header and shopId as 'shopware-app-shop-id' header to your app server.
const { token, shopId } = await response.json();
```

::: info
Requesting from the browser to the app backend is only possible when your app backend allows [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/Guides/CORS) requests. Example:

* Access-Control-Allow-Origin: \*
* Access-Control-Allow-Methods: GET, POST, OPTIONS
* Access-Control-Allow-Headers: shopware-app-shop-id, shopware-app-token
  :::

## Validate the JSON Web Token

```php
$shop = $shopResolver->resolveShop($serverRequest);

$storefront = $contextResolver->assembleStorefrontRequest($serverRequest, $shop);

$storefront->claims->getCustomerId();
```

The request from the Storefront to your app server will require that you set up CORS on your application.
We recommend [NelmioCorsBundle](https://symfony.com/bundles/NelmioCorsBundle/current/index.html) for this with allowed headers:
`shopware-app-shop-id, shopware-app-token` and allowed origin `*`.

```php
use Shopware\App\SDK\Context\Storefront\StorefrontAction;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\HttpKernel\Attribute\AsController;
use Symfony\Component\Routing\Attribute\Route;

#[AsController]
class StorefrontController {
    #[Route('/storefront/action')]
    public function handle(StorefrontAction $webhook): Response
    {
        // handle action
        
        return new Response(null, 204);
    }
}
```

Fetch the shop by the `shopware-app-shop-id` header and create a JWT verifier with the app secret as `HMAC-SHA256` secret.
Verify the JWT (shopware-app-token) with the verifier.

---

---
url: /docs/products/paas/shopware/guides/clone-application.md
---

# Clone Application in PaaS Native

This guide explains how to clone an application in Shopware PaaS Native. Cloning creates a copy of an existing application, including its codebase and data, to a new application within the same organization.

:::info
Cloning can only take place between applications within the same organization. You cannot clone applications across different organizations.
:::

The cloning process works by creating a snapshot of the source application and then restoring that snapshot to the target application.

## Use cases

Common scenarios for cloning applications include:

* **Feature testing**: Clone an application to test new features without affecting the original
* **Disaster recovery**: Create backups by cloning applications to different projects
* **Development environments**: Clone production data to development environments for realistic testing

## Prerequisites

Before cloning an application, ensure that:

* Both the source and target applications are within the same organization
* You have access to both the source and target projects
* The target application already exists (or you have permissions to create it)
* The latest deployment of the source application was successful (state: `DEPLOYING_STORE_SUCCESS`)

You can check the deployment status with the following command:

```shell
sw-paas app deploy list
```

:::warning
If the state is `DEPLOYING_STORE_FAILED`, you should **NOT** proceed with cloning. Fix the deployment issues first or proceed with an earlier deployment that was successful.
:::

## Clone an application

You can clone an application using either interactive mode or manual mode

### Interactive mode

If you run the clone command without any parameters, the CLI will guide you through an interactive selection process:

```shell
sw-paas application clone
```

The interactive mode will prompt you to select:

1. **Source application selection**:
   * Organization (if you have access to multiple)
   * Project within the organization
   * Application within the project
   * Deployment

2. **Target application selection**:
   * Project within the same organization (only projects from the selected organization will be shown)
   * Application within the project (the target application must already exist)

This interactive mode is recommended if you're unsure about the specific IDs or prefer a guided experience.

### Manual mode

If you know the specific IDs, you can provide them directly as command-line flags:

```shell
sw-paas application clone \
  --organization-id <organization-id> \
  --project-id <source-project-id> \
  --application-id <source-application-id> \
  --target-application-id <target-application-id> \
  --target-project-id <target-project-id>
```

## Clone process

The cloning process happens in two stages:

1. **Snapshot creation**: The system creates a snapshot of the source application, including its database and filesystem data
2. **Snapshot restoration**: The snapshot is then restored to the target application, overwriting any existing data

This ensures that the target application receives an exact copy of the source application's state at the time of the selected deployment.

:::warning
Cloning does not anonymize database content. The restored snapshot includes the full database state and filesystem data from the source application, including scheduled task data stored in the database.
:::

### Monitor clone progress

After initiating the clone, you can monitor the progress using:

```shell
sw-paas app deploy list
```

Or get detailed information about a specific deployment:

```shell
sw-paas app deploy get
```

The clone operation may take some time, depending on the size of the application data. Wait until the deployment status shows `DEPLOYING_STORE_SUCCESS` before considering the clone to be complete.

## Post-clone tasks

After the clone is successfully completed, you must perform the following tasks:

### Update admin password

For clarity, we'll refer to the source application as **App A** and the cloned (target) application as **App B**.

App B will have the same admin password as App A. For security reasons, you should update the admin password in App B.

To access the Shopware Administration and retrieve the admin credentials for App B, select the correct App, in this case App A, from the interactive menu:

```shell
sw-paas open admin
```

To log in to the Admin dashboard the first time after cloning, you can use the password from App A. Just rerun the `sw-paas open admin` command for App A to fetch the admin password.

You can update the admin password through the UI:

1. Log in to the Shopware Administration of App B using the credentials shown by the `sw-paas open admin` command for App A
2. Navigate to your user profile (click on your username in the bottom left corner)
3. Go to **Your profile** and scroll to the **Password** section
4. Enter the password displayed by the `sw-paas open admin` command for App B as the new password
5. Next, in the verification modal that opens, use the password for App A

Alternatively, you can update the admin password using the Shopware console command. Open an exec session:

```shell
sw-paas exec --new
```

Once you're in the session, run the following command to update the admin password:

```shell
bin/console user:change-password admin
```

Follow the prompts to set a new password for the admin user.

### Reindex OpenSearch

If your shop has OpenSearch enabled, you will need to reindex after cloning. Open an exec session:

```shell
sw-paas exec --new
```

Once you're in the session, run the following command to reindex:

```shell
bin/console dal:refresh:index --use-queue
```

### Update domain in sales channel

The cloned application will have the same domain configuration as the source application. You need to update the domain in the sales channel to match the cloned application's domain.

1. Access the Shopware Administration of the cloned application
2. From the left hand side menu pick the sales channel you want to update
3. Scroll to the **Domains** section
4. Update the domain to match the cloned application's domain (e.g., the `shopware.shop` domain assigned to the cloned application, or your custom domain if configured)

---

---
url: /docs/products/saas.md
---

# Cloud

With the SaaS platform, Shopware provides updates, hosting, and infrastructure. Also, there are ways to extend it.

The [App system](../concepts/extensions/apps-concept) gives you great freedom to develop extensions for SaaS stores.

---

---
url: /docs/v6.5/products/saas.md
---

# Cloud

With the SaaS platform, Shopware provides updates, hosting, and infrastructure. Also, there are ways to extend it.

The [App system](../concepts/extensions/apps-concept) gives you great freedom to develop extensions for SaaS stores.

---

---
url: /docs/v6.6/products/saas.md
---

# Cloud

With the SaaS platform, Shopware provides updates, hosting, and infrastructure. Also, there are ways to extend it.

The [App system](../concepts/extensions/apps-concept) gives you great freedom to develop extensions for SaaS stores.

---

---
url: /docs/guides/hosting/installation-updates/cluster-setup.md
---

# Cluster Setup

The setup of high-scaling systems differs from a normal installation of Shopware.
They are completely customized stores with individual templates and extensions.

This guide contains information for everyone who intends to start with such a project.

## Shopware configuration

::: info
This configuration is available starting with Shopware version 6.5.6.0
:::

To configure Shopware for a cluster setup, you have to set the following configuration in your shopware.yaml file:

```yaml
shopware:
    deployment:
        cluster_setup: true
```

This option prevents Shopware from running operations locally (meaning only on one node in a cluster), that potentially can corrupt the state of the cluster by having the state of the nodes diverge from each other, e.g. clearing Symfony cache files at runtime.

## Symfony Flex template

Use the [Symfony Flex template](https://github.com/shopware/template) and pin the Shopware versions in the `composer.json` file.
This prevents unwanted updates when deploying (without a `composer.lock`).

## Sources

The following folders are available in the production template:

* **/src**: Here, the project-specific bundles and sources can be stored.
* **/config**: Here are the .yaml config files and other possible configurations (routing, admin configs, etc).
* **/config/bundles.php**: In this file, all Symfony bundles are defined, which should be included in the project.

## Third-party sources

Most big-scale projects have a development team assigned.
It is responsible for the stability and performance of the system.
The integration of external sources via apps or plugins can be useful but should always be viewed with a critical eye.
By including those sources, the development team relinquishes control over parts of the system.
We recommend including the necessary plugins as Composer packages instead of user-managed plugins.

## Composer plugin loader

Shopware loads by default all plugins via the database and allows enabling / disabling plugins at runtime.
This needs to be fixed in a multi-app server environment.
Therefore, we recommend using the Composer plugin loader.
The Composer plugin loader loads the plugin state from Composer, so when a plugin is installed using Composer, we assume that it is enabled.
That allows you to deploy plugins to all app servers by deploying with installing them using Composer.
The plugins must be installed while deployment using `bin/console plugin:install --activate <name>`, so they are ready to use after the deployment.
To use the composer plugin loader, add the environment variable `COMPOSER_PLUGIN_LOADER=1` to your `.env` file.

## Redis

We recommend setting up at least five Redis servers for the following resources:

1. [Session](../performance/session) + [cart](../performance/cart-storage#using-redis-as-storage)
2. [cache.object](../performance/caches#using-redis)
3. [Lock](../performance/lock-store) + [Increment storage](../performance/increment)
4. [Number Ranges](../performance/number-ranges)
5. [Message Queue](../infrastructure/message-queue)

The PHP Redis extension provides persistent Redis connections.
Persistent connections can help in high load scenarios as each request doesn't have to open and close connections.
Using non-persistent Redis connections can also hit the system's maximum open sockets.
Because of these limitations, the Redis extension is preferred over Predis.

When a Redis cluster is in usage, the `php.ini` setting `redis.clusters.cache_slots=1` should be set to skip the cluster node lookup on each connection.

## Database cluster

We have compiled some best practices and configurations to allow you to operate Shopware in a clustered database environment.
Please refer to the guide below.

## Filesystem

In a multi-app-server system, manage specific directories over a shared filesystem.
This includes assets, theme files, and private as well as public filesystems. The recommendation is to use an S3 compatible bucket.

For more information, refer to the [filesystems](../infrastructure/filesystem) section of this guide. If you are moving an existing single-server shop to a shared S3 bucket, follow the [migration guide](../infrastructure/filesystem#migrating-an-existing-filesystem-to-a-new-adapter) to copy the existing files and switch the configuration without losing media.

### Shared directories

Besides the S3 bucket, it is also necessary to create certain directories for the app servers as shared filesystem.

#### `var/services`

`<project-root>/var/services/` holds the source files of installed services. It must be writable by the app server.

When a service is installed or updated, only the node that ran the install or update writes to this directory. We therefore recommend sharing it across app servers. If it is not shared, every other node will re-download the source files from the service registry the first time it performs an operation that needs them — for example compiling a service-managed theme, or rotating the app secret. This still works correctly, but produces redundant downloads.

## Shopware updates + security

To update your project, we always recommend using a staging environment.
However, updates for a project should only be obtained if there are critical problems with the system or if essential features have been provided by Shopware.
Updates of such systems require a certain amount of effort, as issues often arise during deployments to production systems.

### Security plugin

For obtaining security fixes, without version upgrades, we provide a dedicated Security plugin.
It is compatible with all Shopware versions, and the included fixes only activate on versions that are affected. In cluster setups, install it through Composer so all application servers receive the same code.

### Update of composer dependencies

To ensure the security of your Shopware installation, it's essential to be vigilant about third-party dependencies that might be affected by security vulnerabilities.
In that case, a new Shopware version will be released with updated dependencies.
If an update to the latest Shopware version in a timely manner is not possible, it is recommended to update the affected dependency manually.
This can be done by using the following command:

```bash
 composer update <dependency-name>
```

To identify any potential security risk in your current dependencies, it's a good practice to regularly run the [`composer audit`](https://getcomposer.org/doc/03-cli.md#audit) command.
This command scans your dependencies and alerts you if there are any known vulnerabilities that need to be addressed.

### Disable auto-update

Shopware's integrated auto-update functionality should be disabled to prevent unwanted updates.
Also, this feature is not multi-app server compatible and should be controlled via deployment.

```yaml
shopware:
    auto_update:
        enabled: false
```

## Message queue

On a productive system, the [message queue](../infrastructure/message-queue) should be processed via CLI processes instead of the [Admin worker](../infrastructure/message-queue#admin-worker).
This way, messages are completed regardless of logged-in Administration users and CPU load, as messages can be regulated through the amount of worker processes.
Furthermore, you can change the transport to another system like [RabbitMQ](https://www.rabbitmq.com/).

It is recommended to run multiple `messenger:consume` workers.
To automatically start the processes again after they stopped because of exceeding the given limits you can use a process control system like [systemd](https://www.freedesktop.org/wiki/Software/systemd/) or [supervisor](http://supervisord.org/running.html).

### Own queue

It is also recommended to define your own message queue in addition to the standard message queue.
This gives you more control over the load distribution and allows you to prioritize your own processes higher than the data indexing of Shopware.

## Monitoring

Likewise, we recommend setting up an appropriate monitoring dashboard with well-known software such as:

* [Blackfire](https://www.blackfire.io/)
* [Tideways](https://tideways.com/)
* [Datadog](https://www.datadoghq.com/)
* [Elastic](https://www.elastic.co/)

## Local machines

It is important to keep the local development environments of the developers similar to the live environments.
A development environment without Redis or Elasticsearch is always too far away from reality and often leads to complications after deployment.
Therefore, it is advisable to maintain internal documentation on how to deploy the server structure and how to set up local machines.

## Theme compiling

The [theme compilation](deployments/build-w-o-db#compiling-the-storefront-without-database) in Shopware by default depends on the settings in the database.
However, since a connection to the database is usually not guaranteed during deployment, we recommend configuring static theme compilation.

## Strong CPU

For the server setup, pay special attention to CPU speed.
This applies to all servers (app, SQL, Elasticsearch, Redis).
Usually, it is more optimal to choose a slightly stronger CPU.
This has to be determined more precisely depending on the project and load.
Experience has shown that systems with powerful CPUs finish processes faster and can release resources sooner.

## Health Check

Use the Shopware-provided Health Check API (`/api/_info/health-check`) to monitor the health of your Shopware app server.
It responds with HTTP status `200` when the Shopware Application is working and `50x` when it is not.
For docker, you can use: `HEALTHCHECK CMD curl --fail http://localhost/api/_info/health-check || exit 1`

## Performance tweaks

When setting up big-scale projects, there are some settings and conditions that should be taken into account with regard to performance.

Read more on [performance tweaks](../performance/performance-tweaks).

---

---
url: /docs/v6.5/guides/hosting/installation-updates/cluster-setup.md
---

# Cluster Setup

The setup of high-scaling systems differs from a normal installation of Shopware. They are completely customized stores with individual templates and extensions.

This guide contains information for everyone who intends to start with such a project.

## Shopware configuration

::: info
This configuration is available starting with Shopware version 6.5.6.0
:::

To configure Shopware for a cluster setup, you have to set the following configuration in your shopware.yaml file:

```yaml
shopware:
    deployment:
        cluster_setup: true
```

This option prevents shopware from running operations locally (meaning only on one node in a cluster), that potentially can corrupt the state of the cluster by having the state of the nodes diverge from each other, e.g. clearing symfony cache files at runtime.

## Symfony Flex template

Use the [Symfony Flex template](../../installation/template) and pin the Shopware versions in the `composer.json` file. This prevents unwanted updates when deploying (without a composer.lock).

## Sources

The following folders are available in the production template:

* **/src**: Here, the project specific bundles and sources can be stored.
* **/config**: Here are the .yaml config files and other possible configurations (routing, admin configs, etc).
* **/config/bundles.php**: In this file, all Symfony bundles are defined, which should be included in the project.

## Third-party sources

Most big-scale projects have a development team assigned. It is responsible for the stability and performance of the system. The integration of external sources via apps or plugins can be useful but should always be viewed with a critical eye. By including those sources, the development team relinquishes control over parts of the system. We recommend including necessary plugins as Composer packages instead of user-managed plugins.

## Composer plugin loader

Shopware loads by default all plugins via the database and allows to enable/disable plugins at runtime. This needs to be fixed in a multi-app server environment. Therefore, we recommend using the Composer plugin loader. The Composer plugin loader loads the plugin state from Composer, so when a plugin is installed using Composer we assume that it is enabled.
That allows you to deploy plugins to all app servers by deploying with installing them using Composer. The plugins must be installed while deployment using `bin/console plugin:install --activate <name>`, so they are ready to use after the deployment. To use the composer plugin loader, add the environment variable `COMPOSER_PLUGIN_LOADER=1` to your `.env` file.

## Redis

We recommend setting up at least five Redis servers for the following resources:

1. [Session](../performance/session) + [cart](../infrastructure/database-cluster#cart-in-redis)
2. [cache.object](../performance/caches#example-replace-some-cache-with-redis)
3. [Lock](../performance/lock-store)) + [Increment storage](../performance/increment))
4. [Number Ranges](../performance/number-ranges)
5. [Message Queue](../infrastructure/message-queue#transport-redis-example)\
   Instead of setting up a Redis server for `messenger`, you can also work directly with [RabbitMQ](../infrastructure/message-queue#transport-rabbitmq-example)

The PHP Redis extension provides persistent Redis connections. Persistent connections can help in high load scenarios as each request doesn't have to open and close connections. Using non-persistent Redis connections can also hit the system's maximum open sockets. Because of these limitations, the Redis extension is preferred over Predis.

When a Redis cluster is in usage, the `php.ini` setting `redis.clusters.cache_slots=1` should be set to skip the cluster node lookup on each connection.

## Database cluster

We have compiled some best practices and configurations to allow you to operate Shopware in a clustered database environment. Please refer to the guide below.

## Filesystem

In a multi-app-server system, manage specific directories over a shared filesystem. This includes assets, theme files, and private as well as public filesystems. The recommendation is to use an S3 compatible bucket.

For more information, refer to the [filesystems](../infrastructure/filesystem) section of this guide.

### Shared directories

Besides the S3 bucket, it is also necessary to create certain directories for the app servers as shared filesystem.

## Shopware updates + security

To update your project, we always recommend using a staging environment. However, updates for a project should only be obtained if there are critical problems with the system or if essential features have been provided by Shopware.
Updates of such systems require a certain amount of effort, as issues often arise during deployments to production systems.

### Security plugin

For obtaining security fixes, without version upgrades, we provide a dedicated [Security plugin](https://store.shopware.com/swag136939272659f/shopware-6-sicherheits-plugin.html). This is compatible with all Shopware versions and corresponding hot fixes are only included in versions that are affected.

### Update of composer dependencies

To ensure the security of your Shopware installation, it's essential to be vigilant about third-party dependencies that might be affected by security vulnerabilities. In that case, a new Shopware version will be released with updated dependencies. If an update to the latest Shopware version in a timely manner is not possible, it is recommended to update the affected dependency manually. This can be done by using the following command:

```bash
 composer update <dependency-name>
```

To identify any potential security risk in your current dependencies, it's a good practice to regularly run the [`composer audit`](https://getcomposer.org/doc/03-cli.md#audit) command. This command scans your dependencies and alerts you if there are any known vulnerabilities that need to be addressed.

### Disable auto-update

Shopware's integrated auto-update functionality should be disabled to prevent unwanted updates. Also, this feature is not multi-app server compatible and should be controlled via deployment.

```yaml
shopware:
    auto_update:
        enabled: false
```

## Message queue

On a productive system, the [message queue](../infrastructure/message-queue) should be processed via CLI processes instead of the [Admin worker](../infrastructure/message-queue#admin-worker). This way, messages are completed regardless of logged-in Administration users and CPU load, as messages can be regulated through the amount of worker processes. Furthermore, you can change the transport to another system like [RabbitMQ](https://www.rabbitmq.com/).

It is recommended to run multiple `messenger:consume` workers. To automatically start the processes again after they stopped because of exceeding the given limits you can use a process control system like [systemd](https://www.freedesktop.org/wiki/Software/systemd/) or [supervisor](http://supervisord.org/running.html).

### Own queue

It is also recommended to define your own message queue in addition to the standard message queue. This gives you more control over the load distribution and allows you to prioritize your own processes higher than the data indexing of Shopware.

## Monitoring

Likewise, we recommend setting up an appropriate monitoring dashboard with well-known software such as:

* [Blackfire](https://www.blackfire.io/)
* [Tideways](https://tideways.com/)
* [Datadog](https://www.datadoghq.com/)
* [Elastic](https://www.elastic.co/)

## Local machines

It is important to keep the local development environments of the developers similar to the live environments. A development environment without Redis or Elasticsearch is always too far away from reality and often leads to complications after deployment. Therefore, it is advisable to maintain internal documentation on how to deploy the server structure and how to set up local machines.

## Theme compiling

The [theme compilation](deployments/build-w-o-db#compiling-the-storefront-without-database) in Shopware by default depends on the settings in the database. However, since a connection to the database is usually not guaranteed during deployment, we recommend configuring static theme compilation.

## Strong CPU

For the server setup, pay special attention to CPU speed. This applies to all servers (app, SQL, Elasticsearch, Redis). Usually, it is more optimal to choose a slightly stronger CPU. This has to be determined more precisely depending on the project and load. Experience has shown that systems with powerful CPUs finish processes faster and can release resources sooner.

## Health Check

::: info
This feature is available starting with Shopware version 6.5.5.0
:::

Use the Shopware-provided Health Check API (`/api/_info/health-check`) to monitor the health of your Shopware app server. It responds with HTTP status `200` when the Shopware Application is working and `50x` when it is not.
For docker, you can use: `HEALTHCHECK CMD curl --fail http://localhost/api/_info/health-check || exit 1`

## Performance tweaks

When setting up big-scale projects, there are some settings and conditions that should be taken into account with regard to performance.

Read more on [performance tweaks](../performance/performance-tweaks).

---

---
url: /docs/v6.6/guides/hosting/installation-updates/cluster-setup.md
---

# Cluster Setup

The setup of high-scaling systems differs from a normal installation of Shopware. They are completely customized stores with individual templates and extensions.

This guide contains information for everyone who intends to start with such a project.

## Shopware configuration

::: info
This configuration is available starting with Shopware version 6.5.6.0
:::

To configure Shopware for a cluster setup, you have to set the following configuration in your shopware.yaml file:

```yaml
shopware:
    deployment:
        cluster_setup: true
```

This option prevents shopware from running operations locally (meaning only on one node in a cluster), that potentially can corrupt the state of the cluster by having the state of the nodes diverge from each other, e.g. clearing symfony cache files at runtime.

## Symfony Flex template

Use the [Symfony Flex template](../../installation/template) and pin the Shopware versions in the `composer.json` file. This prevents unwanted updates when deploying (without a composer.lock).

## Sources

The following folders are available in the production template:

* **/src**: Here, the project specific bundles and sources can be stored.
* **/config**: Here are the .yaml config files and other possible configurations (routing, admin configs, etc).
* **/config/bundles.php**: In this file, all Symfony bundles are defined, which should be included in the project.

## Third-party sources

Most big-scale projects have a development team assigned. It is responsible for the stability and performance of the system. The integration of external sources via apps or plugins can be useful but should always be viewed with a critical eye. By including those sources, the development team relinquishes control over parts of the system. We recommend including necessary plugins as Composer packages instead of user-managed plugins.

## Redis

We recommend setting up at least five Redis servers for the following resources:

1. [Session](../performance/session) + [cart](../infrastructure/database-cluster#cart-in-redis)
2. [cache.object](../performance/caches#example-replace-some-cache-with-redis)
3. [Lock](../performance/lock-store) + [Increment storage](../performance/increment)
4. [Number Ranges](../performance/number-ranges)
5. [Message Queue](../infrastructure/message-queue#transport-redis-example)\
   Instead of setting up a Redis server for `messenger`, you can also work directly with [RabbitMQ](../infrastructure/message-queue#transport-rabbitmq-example)

The PHP Redis extension provides persistent Redis connections. Persistent connections can help in high load scenarios as each request doesn't have to open and close connections. Using non-persistent Redis connections can also hit the system's maximum open sockets. Because of these limitations, the Redis extension is preferred over Predis.

When a Redis cluster is in usage, the `php.ini` setting `redis.clusters.cache_slots=1` should be set to skip the cluster node lookup on each connection.

## Database cluster

We have compiled some best practices and configurations to allow you to operate Shopware in a clustered database environment. Please refer to the guide below.

## Filesystem

In a multi-app-server system, manage specific directories over a shared filesystem. This includes assets, theme files, and private as well as public filesystems. The recommendation is to use an S3 compatible bucket.

For more information, refer to the [filesystems](../infrastructure/filesystem) section of this guide.

### Shared directories

Besides the S3 bucket, it is also necessary to create certain directories for the app servers as shared filesystem.

## Shopware updates + security

To update your project, we always recommend using a staging environment. However, updates for a project should only be obtained if there are critical problems with the system or if essential features have been provided by Shopware.
Updates of such systems require a certain amount of effort, as issues often arise during deployments to production systems.

### Security plugin

For obtaining security fixes, without version upgrades, we provide a dedicated [Security plugin](https://store.shopware.com/swag136939272659f/shopware-6-sicherheits-plugin.html). This is compatible with all Shopware versions and corresponding hot fixes are only included in versions that are affected.

### Update of composer dependencies

To ensure the security of your Shopware installation, it's essential to be vigilant about third-party dependencies that might be affected by security vulnerabilities. In that case, a new Shopware version will be released with updated dependencies. If an update to the latest Shopware version in a timely manner is not possible, it is recommended to update the affected dependency manually. This can be done by using the following command:

```bash
 composer update <dependency-name>
```

To identify any potential security risk in your current dependencies, it's a good practice to regularly run the [`composer audit`](https://getcomposer.org/doc/03-cli.md#audit) command. This command scans your dependencies and alerts you if there are any known vulnerabilities that need to be addressed.

### Disable auto-update

Shopware's integrated auto-update functionality should be disabled to prevent unwanted updates. Also, this feature is not multi-app server compatible and should be controlled via deployment.

```yaml
shopware:
    auto_update:
        enabled: false
```

## Message queue

On a productive system, the [message queue](../infrastructure/message-queue) should be processed via CLI processes instead of the [Admin worker](../infrastructure/message-queue#admin-worker). This way, messages are completed regardless of logged-in Administration users and CPU load, as messages can be regulated through the amount of worker processes. Furthermore, you can change the transport to another system like [RabbitMQ](https://www.rabbitmq.com/).

It is recommended to run multiple `messenger:consume` workers. To automatically start the processes again after they stopped because of exceeding the given limits you can use a process control system like [systemd](https://www.freedesktop.org/wiki/Software/systemd/) or [supervisor](http://supervisord.org/running.html).

### Own queue

It is also recommended to define your own message queue in addition to the standard message queue. This gives you more control over the load distribution and allows you to prioritize your own processes higher than the data indexing of Shopware.

## Monitoring

Likewise, we recommend setting up an appropriate monitoring dashboard with well-known software such as:

* [Blackfire](https://www.blackfire.io/)
* [Tideways](https://tideways.com/)
* [Datadog](https://www.datadoghq.com/)
* [Elastic](https://www.elastic.co/)

## Local machines

It is important to keep the local development environments of the developers similar to the live environments. A development environment without Redis or Elasticsearch is always too far away from reality and often leads to complications after deployment. Therefore, it is advisable to maintain internal documentation on how to deploy the server structure and how to set up local machines.

## Theme compiling

The [theme compilation](deployments/build-w-o-db#compiling-the-storefront-without-database) in Shopware by default depends on the settings in the database. However, since a connection to the database is usually not guaranteed during deployment, we recommend configuring static theme compilation.

## Strong CPU

For the server setup, pay special attention to CPU speed. This applies to all servers (app, SQL, Elasticsearch, Redis). Usually, it is more optimal to choose a slightly stronger CPU. This has to be determined more precisely depending on the project and load. Experience has shown that systems with powerful CPUs finish processes faster and can release resources sooner.

## Health Check

::: info
This feature is available starting with Shopware version 6.5.5.0
:::

Use the Shopware-provided Health Check API (`/api/_info/health-check`) to monitor the health of your Shopware app server. It responds with HTTP status `200` when the Shopware Application is working and `50x` when it is not.
For docker, you can use: `HEALTHCHECK CMD curl --fail http://localhost/api/_info/health-check || exit 1`

## Performance tweaks

When setting up big-scale projects, there are some settings and conditions that should be taken into account with regard to performance.

Read more on [performance tweaks](../performance/performance-tweaks).

---

---
url: /docs/guides/plugins/apps/content/cms.md
---

# CMS

Shopware allows you to extend the platform's content management capabilities by adding custom CMS blocks or elements from an app.
By creating a custom app, you can define and integrate your own unique CMS blocks. These blocks can contain custom content, such as text, images, or HTML, and can be positioned within the CMS layout according to your requirements.

Once the app is installed and activated, the custom CMS block becomes available in the Shopware Administration, allowing you to create tailored content for your online store.

---

---
url: /docs/guides/plugins/plugins/content/cms.md
---

# CMS

In general, Shopware CMS creates and manages content using blocks and elements.

The CMS plugin allows you to easily add and organize these CMS blocks, which are reusable sections of content that can be placed on multiple pages. You can customize the appearance and layout of these blocks. To create engaging and visually appealing pages within these blocks, you can add and configure various content elements such as text, images, videos, sliders, and more. Additionally, the CMS plugin enables you to add data to their content elements, such as product information, categories, or dynamic content from APIs.

Furthermore, the CMS feature core functions can be accessed and managed through the Shopware Admin SDK. This provides developers with tools and APIs to interact with the CMS functionality, allowing for more advanced customization.

Overall, the plugin facilitates you to create, customize, and manage engaging content on your website. Through blocks, elements, and the flexibility the Admin SDK provides, businesses can create visually appealing pages with dynamic and relevant content to enhance the user experience.

---

---
url: /docs/v6.5/guides/plugins/apps/content/cms.md
---

# CMS

Shopware allows you to extend the content management capabilities of the platform by adding a custom CMS block from an app. By creating a custom app, you can define and integrate your own unique CMS blocks. These blocks can contain custom content, such as text, images, or HTML, and can be positioned within the CMS layout according to your requirements. Once the app is installed and activated, the custom CMS block becomes available within the Shopware administration panel, empowering you to create engaging and tailored content for your online store.

---

---
url: /docs/v6.5/guides/plugins/plugins/content/cms.md
---

# CMS

In general, Shopware CMS creates and manages content using blocks and elements.

The CMS plugin allows you to easily add and organize these CMS blocks, which are reusable sections of content that can be placed on multiple pages. You can customize the appearance and layout of these blocks. To create engaging and visually appealing pages within these blocks, you can add and configure various content elements such as text, images, videos, sliders, and more. Additionally, the CMS plugin enables you to add data to their content elements, such as product information, categories, or dynamic content from APIs.

Furthermore, the CMS feature core functions can be accessed and managed through the Shopware Admin SDK. This provides developers with tools and APIs to interact with the CMS functionality, allowing for more advanced customization.

Overall, the plugin facilitates you to create, customize, and manage engaging content on your website. Through blocks, elements, and the flexibility the Admin SDK provides, businesses can create visually appealing pages with dynamic and relevant content to enhance the user experience.

---

---
url: /docs/v6.6/guides/plugins/apps/content/cms.md
---

# CMS

Shopware allows you to extend the content management capabilities of the platform by adding a custom CMS block from an app. By creating a custom app, you can define and integrate your own unique CMS blocks. These blocks can contain custom content, such as text, images, or HTML, and can be positioned within the CMS layout according to your requirements. Once the app is installed and activated, the custom CMS block becomes available within the Shopware administration panel, empowering you to create engaging and tailored content for your online store.

---

---
url: /docs/v6.6/guides/plugins/plugins/content/cms.md
---

# CMS

In general, Shopware CMS creates and manages content using blocks and elements.

The CMS plugin allows you to easily add and organize these CMS blocks, which are reusable sections of content that can be placed on multiple pages. You can customize the appearance and layout of these blocks. To create engaging and visually appealing pages within these blocks, you can add and configure various content elements such as text, images, videos, sliders, and more. Additionally, the CMS plugin enables you to add data to their content elements, such as product information, categories, or dynamic content from APIs.

Furthermore, the CMS feature core functions can be accessed and managed through the Shopware Admin SDK. This provides developers with tools and APIs to interact with the CMS functionality, allowing for more advanced customization.

Overall, the plugin facilitates you to create, customize, and manage engaging content on your website. Through blocks, elements, and the flexibility the Admin SDK provides, businesses can create visually appealing pages with dynamic and relevant content to enhance the user experience.

---

---
url: /frontends/guides/cms.md
---

# CMS

Everything related to CMS ([Shopping Experiences](../../concepts/shopping-experiences.html)).







---

---
url: /frontends/integrations/cms.md
---

# CMS Integrations

Composable Frontends does not force one content source. Shopware can render its
own Shopping Experiences, and your storefront can also read from a headless CMS
such as Storyblok, Strapi, Sanity, Contentful, Hygraph, Builder.io, or a custom
editorial API.

The important architectural rule is simple:

**let the CMS own editorial content, and let Shopware own live commerce data.**

That means the CMS can decide what appears on a page, but product names, prices,
availability, variants, cart, checkout, customer data, and promotions should still
come from the Shopware Store API at request time.

## Existing examples

## Choose an integration model

Most integrations fit into one of these patterns:

| Pattern                   | Good for                                                                 | How it works                                                                                                  |
| ------------------------- | ------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- |
| CMS as page source        | Landing pages, editorial homepages, campaign pages                       | The external CMS resolves the route and returns a page builder payload. Vue components render each CMS block. |
| CMS as section source     | Global banners, teasers, content slots in product/category pages         | Shopware still resolves the main page. The external CMS fills specific areas.                                 |
| Shopware CMS fallback     | Mixed migrations, gradual adoption, legacy Shopware Shopping Experiences | Try the external CMS first or only when Shopware does not resolve a route.                                    |
| Product references in CMS | Merchandising sections, product carousels, buying guides                 | The CMS stores Shopware product IDs. The frontend resolves live product data with Shopware composables.       |

Use the smallest pattern that solves the project. A global campaign banner should
not need a full route resolver. A full editorial site with nested pages usually
should.

## Recommended architecture

Keep the integration as a thin adapter between three layers:

1. **CMS client**: fetches typed content from the external CMS.
2. **CMS resolver**: maps a route, locale, and request context to a normalized page.
3. **Vue renderer**: maps CMS block types to Vue components.

This keeps vendor SDKs out of your components and makes it easier to replace a
CMS later.

```ts
type CmsRouteContext = {
  path: string;
  locale: string;
  salesChannelId?: string;
};

type CmsBlock = {
  id: string;
  type: string;
  props: Record<string, unknown>;
};

type CmsPage = {
  title?: string;
  seo?: {
    title?: string;
    description?: string;
  };
  blocks: CmsBlock[];
};

type CmsAdapter = {
  resolvePage(context: CmsRouteContext): Promise<CmsPage | null>;
};
```

Then implement the adapter with the CMS tooling your project uses. The rest of
the storefront should only depend on the normalized contract:

```ts
export function createCmsResolver(adapter: CmsAdapter) {
  return async (context: CmsRouteContext) => {
    const page = await adapter.resolvePage(context);

    if (!page) return null;

    return {
      ...page,
      blocks: page.blocks.filter((block) => Boolean(block.type)),
    };
  };
}
```

The adapter can call a REST API, GraphQL API, SDK, or internal service. Keep that
vendor-specific code in one place:

```ts
const cmsAdapter: CmsAdapter = {
  async resolvePage(context) {
    const rawPage = await fetchFromYourCms(context);

    if (!rawPage) return null;

    return normalizeCmsPage(rawPage);
  },
};
```

## Rendering CMS blocks

A page builder should be explicit. Map every external block type to one Vue
component, and render nothing for unknown blocks in production. In development,
show a small placeholder so the missing component is obvious.

```vue
<!-- app/components/ExternalCmsPage.vue -->
<script setup lang="ts">
import type { Component } from "vue";
import CmsHero from "./external-cms/CmsHero.vue";
import CmsRichText from "./external-cms/CmsRichText.vue";
import CmsFeaturedProducts from "./external-cms/CmsFeaturedProducts.vue";

defineProps<{
  blocks: Array<{
    id: string;
    type: string;
    props: Record<string, unknown>;
  }>;
}>();

const components: Record<string, Component> = {
  hero: CmsHero,
  richText: CmsRichText,
  featuredProducts: CmsFeaturedProducts,
};
</script>

<template>
  <template v-for="block in blocks" :key="block.id">
    <component
      :is="components[block.type]"
      v-if="components[block.type]"
      v-bind="block.props"
    />
    <div v-else-if="import.meta.dev" class="border border-dashed p-4 text-sm">
      Missing external CMS component: {{ block.type }}
    </div>
  </template>
</template>
```

This is the same idea used by the [Sanity example](./sanity.html): Sanity
provides a `pageBuilder` array, while Vue maps each `_type` to a section
component.

## Resolving routes

If the external CMS owns complete pages, resolve it from the catch-all route.
If Shopware should remain the primary router, use the [Multiple CMS](../../guides/cms/multiple-cms)
middleware pattern and only render the external CMS when Shopware does not return
a route component.

```vue
<!-- app/pages/[...all].vue -->
<script setup lang="ts">
const route = useRoute();
const { locale } = useI18n();
const { resolvePage } = useExternalCms();

const path =
  route.path.replace(`/${locale.value}`, "").replace(/^\//, "") || "home";

const { data: page } = await useAsyncData(
  `external-cms-${locale.value}-${path}`,
  () => resolvePage(path, locale.value),
);

if (!page.value) {
  throw createError({ statusCode: 404, statusMessage: "Page not found" });
}

useSeoMeta({
  title: page.value.seo?.title ?? page.value.title,
  description: page.value.seo?.description,
});
</script>

<template>
  <ExternalCmsPage :blocks="page?.blocks ?? []" />
</template>
```

## Connecting content with commerce

Do not copy product data into the CMS. Store stable Shopware identifiers and
resolve them during SSR with Shopware composables.

```vue
<!-- app/components/external-cms/CmsFeaturedProducts.vue -->
<script setup lang="ts">
import type { Schemas } from "#shopware";

const props = defineProps<{
  heading?: string;
  productIds: string[];
}>();

const { search } = useProductSearch();

const { data: products } = await useAsyncData(
  `external-cms-products-${props.productIds.join("-")}`,
  async () => {
    const resolved = await Promise.all(
      props.productIds.map((id) =>
        search(id)
          .then((response) => response.product)
          .catch(() => null),
      ),
    );

    return resolved.filter(
      (product): product is Schemas["Product"] => !!product,
    );
  },
);
</script>

<template>
  <section>
    <h2 v-if="heading">{{ heading }}</h2>
    <ProductCard
      v-for="product in products"
      :key="product.id"
      :product="product"
    />
  </section>
</template>
```

This is the safest split for commerce projects:

* CMS stores product IDs, copy, layout, campaign images, and editorial order.
* Shopware resolves price, stock, translated product names, media, variants, and
  purchase actions.
* Cart, checkout, and customer account flows stay entirely in Shopware
  composables.

::: warning Match the sales channel
Product IDs must belong to the same Shopware sales channel as the access token
used by the storefront. If editors paste IDs from another environment, the Store
API can return `404` or products that are not visible in the current channel.
:::

## Caching strategy

Treat CMS content and commerce data differently.

| Data                         | Cache recommendation                                                     |
| ---------------------------- | ------------------------------------------------------------------------ |
| Published CMS pages          | Cache on the server or CDN, then revalidate on publish webhooks.         |
| Draft CMS pages              | Never share-cache. Use `private, no-store`.                              |
| Product cards resolved by ID | Render during SSR, but keep freshness aligned with Shopware cache rules. |
| Cart, customer, wishlist     | Client/session data only. Do not include it in cacheable HTML.           |

When using Nuxt `routeRules`, cache public editorial routes but keep personalized
routes such as `/checkout`, `/account/**`, and cart flows out of ISR.

## Localization

Pass the active storefront locale to the CMS resolver and keep a clear fallback
policy:

```ts
const { locale } = useI18n();
const page = await resolvePage(path, locale.value);
```

For multi-language storefronts, align:

* Nuxt route prefixes
* Shopware sales channel language
* CMS locale codes
* canonical URLs and `hreflang`
* translated product IDs or product references, if the CMS stores environment
  specific references

## Content modeling checklist

Before implementing the integration, define these contracts with the content
team:

* Which system owns each route?
* Which CMS blocks are allowed on product and category pages?
* What is the stable reference for Shopware products: product ID, product number,
  or a custom field?
* Should editors select products manually, through a filtered query, or through a
  curated list?
* How are draft, published, scheduled, and archived entries represented?
* Which fields are required for SEO, Open Graph, breadcrumbs, and structured data?
* How should the frontend behave when a CMS block references a missing product?

## Security and reliability

External CMS data is still untrusted input. Render it carefully:

* sanitize rich text if the CMS returns HTML instead of structured rich text
* allowlist block types and component props
* keep private tokens in server runtime config
* validate webhook signatures before purging caches
* handle missing CMS entries with real `404` responses
* add observability around CMS fetch failures and slow responses
* keep checkout and account flows independent from CMS availability

## Where to go next

* [Sanity integration](./sanity.html): page builder, live Shopware products, cart,
  and a runnable Nuxt example.
* [Strapi integration](./strapi.html): global banner and route fallback example.
* [Storyblok integration](./storyblok.html): Nuxt module setup and visual editor
  oriented component rendering.
* [Multiple CMS](../../guides/cms/multiple-cms): render an external
  CMS as a fallback next to Shopware Shopping Experiences.
* [Shopping Experiences](../../concepts/shopping-experiences): customize the
  Shopware CMS renderer and default CMS components.

---

---
url: /docs/resources/references/app-reference/cms-reference.md
---

# CMS Reference

```xml
// cms.xml
<?xml version="1.0" encoding="utf-8" ?>
<cms xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Cms/Schema/cms-1.0.xsd">
    <blocks>
        <block>
            <!-- A unique technical name for your block. We recommend to use a shorthand prefix for your company, e.g. "Swag" for shopware AG. -->
            <name>my-first-block</name>
            <!-- The category your block is associated with. See the XSD for available categories. -->
            <category>text-image</category>

            <!-- Your block's label which will be shown in the CMS module in the Administration. -->
            <label>First block from app</label>
            <!-- The label is translatable by providing ISO codes. -->
            <label lang="de-DE">Erster Block einer App</label>

            <!-- The slots that your block holds which again hold CMS elements. -->
            <slots>
                <!-- A slot requires a unique name and a type which refers to the CMS element it shows. Right now you can only use the CMS elements provided by Shopware but at a later point you will be able to add custom elements too. -->
                <slot name="left" type="manufacturer-logo">
                    <!-- The slot requires some basic configuration. The following config-value elements highly depend on which element the slot holds. -->
                    <config>
                        <!-- The following config-value will be interpreted as "displayMode: { source: "static", value: "cover"}" in the JavaScript. -->
                        <config-value name="display-mode" source="static" value="cover"/>
                    </config>
                </slot>
                <slot name="middle" type="image-gallery">
                    <config>
                        <config-value name="display-mode" source="static" value="auto"/>
                        <config-value name="min-height" source="static" value="300px"/>
                    </config>
                </slot>
                <slot name="right" type="buy-box">
                    <config>
                        <config-value name="display-mode" source="static" value="contain"/>
                    </config>
                </slot>
            </slots>

            <!-- Each block comes with a default configuration which is pre-filled and customizable when adding a block to a section in the CMS module in the Administration. -->
            <default-config>
                <margin-bottom>20px</margin-bottom>
                <margin-top>20px</margin-top>
                <margin-left>20px</margin-left>
                <margin-right>20px</margin-right>
                <!-- The sizing mode of your block. Allowed values are "boxed" or "full_width". -->
                <sizing-mode>boxed</sizing-mode>
                <background-color>#000</background-color>
            </default-config>
        </block>

        <block>
            <name>my-second-block</name>
            <category>text-image</category>

            <label>Second block from app</label>
            <label lang="de-DE">Zweiter Block einer App</label>

            <slots>
                <slot name="left" type="form">
                    <config>
                        <config-value name="display-mode" source="static" value="cover"/>
                    </config>
                </slot>
                <slot name="middle" type="image">
                    <config>
                        <config-value name="display-mode" source="static" value="auto"/>
                        <config-value name="background-color" source="static" value="red"/>
                    </config>
                </slot>
                <slot name="right" type="youtube-video">
                    <config>
                        <config-value name="display-mode" source="static" value="contain"/>
                    </config>
                </slot>
            </slots>

            <default-config>
                <margin-bottom>20px</margin-bottom>
                <margin-top>20px</margin-top>
                <margin-left>20px</margin-left>
                <margin-right>20px</margin-right>
                <sizing-mode>boxed</sizing-mode>
                <background-color>#000</background-color>
            </default-config>
        </block>
    </blocks>
</cms>
```

---

---
url: /docs/v6.5/resources/references/app-reference/cms-reference.md
---

# CMS Reference

```xml
// cms.xml
<?xml version="1.0" encoding="utf-8" ?>
<cms xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Cms/Schema/cms-1.0.xsd">
    <blocks>
        <block>
            <!-- A unique technical name for your block. We recommend to use a shorthand prefix for your company, e.g. "Swag" for shopware AG. -->
            <name>my-first-block</name>
            <!-- The category your block is associated with. See the XSD for available categories. -->
            <category>text-image</category>

            <!-- Your block's label which will be shown in the CMS module in the Administration. -->
            <label>First block from app</label>
            <!-- The label is translatable by providing ISO codes. -->
            <label lang="de-DE">Erster Block einer App</label>

            <!-- The slots that your block holds which again hold CMS elements. -->
            <slots>
                <!-- A slot requires a unique name and a type which refers to the CMS element it shows. Right now you can only use the CMS elements provided by Shopware but at a later point you will be able to add custom elements too. -->
                <slot name="left" type="manufacturer-logo">
                    <!-- The slot requires some basic configuration. The following config-value elements highly depend on which element the slot holds. -->
                    <config>
                        <!-- The following config-value will be interpreted as "displayMode: { source: "static", value: "cover"}" in the JavaScript. -->
                        <config-value name="display-mode" source="static" value="cover"/>
                    </config>
                </slot>
                <slot name="middle" type="image-gallery">
                    <config>
                        <config-value name="display-mode" source="static" value="auto"/>
                        <config-value name="min-height" source="static" value="300px"/>
                    </config>
                </slot>
                <slot name="right" type="buy-box">
                    <config>
                        <config-value name="display-mode" source="static" value="contain"/>
                    </config>
                </slot>
            </slots>

            <!-- Each block comes with a default configuration which is pre-filled and customizable when adding a block to a section in the CMS module in the Administration. -->
            <default-config>
                <margin-bottom>20px</margin-bottom>
                <margin-top>20px</margin-top>
                <margin-left>20px</margin-left>
                <margin-right>20px</margin-right>
                <!-- The sizing mode of your block. Allowed values are "boxed" or "full_width". -->
                <sizing-mode>boxed</sizing-mode>
                <background-color>#000</background-color>
            </default-config>
        </block>

        <block>
            <name>my-second-block</name>
            <category>text-image</category>

            <label>Second block from app</label>
            <label lang="de-DE">Zweiter Block einer App</label>

            <slots>
                <slot name="left" type="form">
                    <config>
                        <config-value name="display-mode" source="static" value="cover"/>
                    </config>
                </slot>
                <slot name="middle" type="image">
                    <config>
                        <config-value name="display-mode" source="static" value="auto"/>
                        <config-value name="background-color" source="static" value="red"/>
                    </config>
                </slot>
                <slot name="right" type="youtube-video">
                    <config>
                        <config-value name="display-mode" source="static" value="contain"/>
                    </config>
                </slot>
            </slots>

            <default-config>
                <margin-bottom>20px</margin-bottom>
                <margin-top>20px</margin-top>
                <margin-left>20px</margin-left>
                <margin-right>20px</margin-right>
                <sizing-mode>boxed</sizing-mode>
                <background-color>#000</background-color>
            </default-config>
        </block>
    </blocks>
</cms>
```

---

---
url: /docs/v6.6/resources/references/app-reference/cms-reference.md
---

# CMS Reference

```xml
// cms.xml
<?xml version="1.0" encoding="utf-8" ?>
<cms xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Cms/Schema/cms-1.0.xsd">
    <blocks>
        <block>
            <!-- A unique technical name for your block. We recommend to use a shorthand prefix for your company, e.g. "Swag" for shopware AG. -->
            <name>my-first-block</name>
            <!-- The category your block is associated with. See the XSD for available categories. -->
            <category>text-image</category>

            <!-- Your block's label which will be shown in the CMS module in the Administration. -->
            <label>First block from app</label>
            <!-- The label is translatable by providing ISO codes. -->
            <label lang="de-DE">Erster Block einer App</label>

            <!-- The slots that your block holds which again hold CMS elements. -->
            <slots>
                <!-- A slot requires a unique name and a type which refers to the CMS element it shows. Right now you can only use the CMS elements provided by Shopware but at a later point you will be able to add custom elements too. -->
                <slot name="left" type="manufacturer-logo">
                    <!-- The slot requires some basic configuration. The following config-value elements highly depend on which element the slot holds. -->
                    <config>
                        <!-- The following config-value will be interpreted as "displayMode: { source: "static", value: "cover"}" in the JavaScript. -->
                        <config-value name="display-mode" source="static" value="cover"/>
                    </config>
                </slot>
                <slot name="middle" type="image-gallery">
                    <config>
                        <config-value name="display-mode" source="static" value="auto"/>
                        <config-value name="min-height" source="static" value="300px"/>
                    </config>
                </slot>
                <slot name="right" type="buy-box">
                    <config>
                        <config-value name="display-mode" source="static" value="contain"/>
                    </config>
                </slot>
            </slots>

            <!-- Each block comes with a default configuration which is pre-filled and customizable when adding a block to a section in the CMS module in the Administration. -->
            <default-config>
                <margin-bottom>20px</margin-bottom>
                <margin-top>20px</margin-top>
                <margin-left>20px</margin-left>
                <margin-right>20px</margin-right>
                <!-- The sizing mode of your block. Allowed values are "boxed" or "full_width". -->
                <sizing-mode>boxed</sizing-mode>
                <background-color>#000</background-color>
            </default-config>
        </block>

        <block>
            <name>my-second-block</name>
            <category>text-image</category>

            <label>Second block from app</label>
            <label lang="de-DE">Zweiter Block einer App</label>

            <slots>
                <slot name="left" type="form">
                    <config>
                        <config-value name="display-mode" source="static" value="cover"/>
                    </config>
                </slot>
                <slot name="middle" type="image">
                    <config>
                        <config-value name="display-mode" source="static" value="auto"/>
                        <config-value name="background-color" source="static" value="red"/>
                    </config>
                </slot>
                <slot name="right" type="youtube-video">
                    <config>
                        <config-value name="display-mode" source="static" value="contain"/>
                    </config>
                </slot>
            </slots>

            <default-config>
                <margin-bottom>20px</margin-bottom>
                <margin-top>20px</margin-top>
                <margin-left>20px</margin-left>
                <margin-right>20px</margin-right>
                <sizing-mode>boxed</sizing-mode>
                <background-color>#000</background-color>
            </default-config>
        </block>
    </blocks>
</cms>
```

---

---
url: >-
  /docs/resources/references/adr/2025-10-14-colocate-administration-technical-docs.md
---

# Co-locate Administration Technical Documentation with Source Code

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2025-10-14-colocate-administration-technical-docs.md)
:::

## Context

The Shopware Administration codebase contains AGENTS.md files throughout the source tree (`src/Administration/Resources/app/administration/src/**`) that serve as concise reference guides for AI assistants and developers. These files provide quick architectural guidance, critical rules, and key patterns.

However, comprehensive technical documentation traditionally lives in a separate documentation repository. This separation creates several challenges:

1. **Difficult Cross-Referencing**: AGENTS.md files cannot easily reference detailed documentation when it lives in a different repository, requiring absolute URLs or external links that may break.
2. **Information Duplication**: Without easy references, AGENTS.md files would need to duplicate detailed explanations, leading to maintenance overhead and potential inconsistencies.
3. **AI Context Limitations**: AI assistants working with the codebase cannot easily access external documentation repositories, limiting their ability to understand complex architectural patterns and make informed suggestions.
4. **Version Synchronization**: Keeping documentation in sync with code changes across repositories is error-prone, especially for rapidly evolving areas.

## Decision

We will co-locate the technical documentation for the Administration component directly within the source tree at `src/Administration/Resources/app/administration/technical-docs/` instead of maintaining it in a separate documentation repository.

This approach enables:

* **Direct References**: AGENTS.md files can reference detailed documentation using relative paths (e.g., `> **Detailed Docs**: technical-docs/04-data-layer/`)
* **Single Source of Truth**: Documentation lives alongside the code it describes, ensuring version alignment
* **AI-Accessible Context**: AI assistants can access both code and comprehensive documentation in a single workspace, improving code understanding and suggestions
* **Atomic Changes**: Documentation updates can be committed with related code changes in the same pull request

The technical documentation is organized in numbered sections (01-overview, 02-architecture, etc.) to provide structured, comprehensive guides that AGENTS.md files can reference without duplication.

## Consequences

### Positive

* AGENTS.md files remain concise while providing access to detailed documentation through references
* AI assistants have complete context when analyzing or modifying Administration code
* Documentation changes are automatically synchronized with code changes
* Reduced duplication between AGENTS.md files and detailed documentation
* Easier for developers to find relevant documentation when working in the codebase

### Neutral

* This is an experimental pattern initially applied only to the Administration component
* If successful, this pattern may be adopted for other parts of Shopware 6 (Core, Storefront, etc.)
* The effectiveness of this approach will be evaluated based on real-world usage

### Trade-offs

* Documentation for the technical Administration component is separated from the central documentation repository

We will monitor the effectiveness of this pattern for the Administration component before deciding whether to expand it to other areas of the codebase.

---

---
url: /docs/resources/guidelines/code.md
---

# Code

Code guidelines is a comprehensive developer handbook that includes dos and don'ts and a clear description of how the code functions, blocks, class, method, argument, return value, and files may be used. It enhances code readability, reproducibility, and usability.

Refer to the following different sections to know more about it.

---

---
url: /docs/v6.5/resources/guidelines/code.md
---

# Code

Code guidelines is a comprehensive developer handbook that includes dos and don'ts and a clear description of how the code functions, blocks, class, method, argument, return value, and files may be used. It enhances code readability, reproducibility, and usability.

Refer to the following different sections to know more about it.

---

---
url: /docs/v6.6/resources/guidelines/code.md
---

# Code

Code guidelines is a comprehensive developer handbook that includes dos and don'ts and a clear description of how the code functions, blocks, class, method, argument, return value, and files may be used. It enhances code readability, reproducibility, and usability.

Refer to the following different sections to know more about it.

---

---
url: /docs/guides/development/testing/store/code-quality.md
---

# Code quality

Extensions must pass automated code review (PHPStan, SonarQube) and manual review for security, standards, UX, and behavior. Configurations used during submission are [public on GitHub](https://github.com/shopwareLabs/store-plugin-codereview).

* Do not ship development-only files or unused resources in the archive.
* Include only necessary dependencies.
* Use secure cookie settings (see [Cookies and privacy](./cookies-and-privacy.md)).

## SonarQube rules (blocker)

The following are prohibited and will fail review:

* `die`
* `exit`
* `var_dump`

[List of blocker patterns](https://s3.eu-central-1.amazonaws.com/wiki-assets.shopware.com/1657519735/blocker.txt)

## Error messages and logging

* Log errors and informational messages only under Shopware’s log directory (`/var/log/`).
* Do not write to Shopware’s default logs or paths outside the logging system (logs must not be reachable via URL).
* Use the pattern `MyExtension-Year-Month-Day.log`.
* Payment extensions must use the **plugin logger** service.
* Database logging is allowed; avoid custom log tables. If you use them, add scheduled cleanup and keep data at most **six months**.

## JavaScript delivery

* Deliver **uncompiled, readable** JavaScript together with compiled assets. Store sources in a **separate folder** for review.
* Shopware must be able to access **unminified** sources at all times.
* Follow [Loading the JS files](../../../plugins/plugins/administration/module-component-management/add-custom-field.md#loading-the-js-files) and [Injecting into the Administration](../../../plugins/plugins/administration/module-component-management/add-custom-field.md#injecting-into-the-administration) when building `main.js` and minified output.

## Cross-domain communication

Limit cross-domain use to explicit, trusted domains. For `postMessage()` and similar APIs, verify message origins; never use `*` as the target origin.

## Plugin-specific requirements {#plugin-specific-requirements}

These apply to **plugins** only:

* Declare [Composer dependencies](../../../plugins/plugins/dependencies/using-composer-dependencies.md) in `composer.json` so code is traceable. If `executeComposerCommands()` returns true, dependencies may be installed dynamically and need not all be bundled.
* Do **not** include `composer.lock` in the archive.
* Ship **production** artifacts only in the ZIP.
* Write unified logs under `/var/log/` as described above.

For `composer.json` structure, ZIP layout, and common mistakes, see [Common Store review errors](./store-review-errors.md).

---

---
url: /docs/guides/development/extensions/code-structure.md
---

# Code Structure

## Shared patterns

* **Namespaces and autoloading**: Match PSR-4 to folder names; avoid deep nesting that hides ownership.
* **Configuration**: Centralize defaults; document override points. Use environment variables only in the project layer, not in Store plugins.
* **Documentation**: Each extension should ship a brief README with purpose, install/update steps, and known constraints.

## Choose the right extension type

* **Custom project/bundle**: Suitable for bespoke installations you fully control. See the [bundle guide](../../plugins/plugins/bundle.md) for the bundle layout and when to embed project-specific logic.
* **Static plugin**: Project-specific, customized plugins; the recommended option. Use the standard plugin skeleton for reusable features across a few projects. Start with the [plugin base guide](../../plugins/plugins/plugin-base-guide.md) and keep project overrides as thin as possible.
* **Managed plugin**: Same plugin layout, but [hardened for Store review](../../plugins/plugins/index.md#managed-plugins): strict metadata, no project-only hacks, testability, and BC guarantees.
* **App**: Prefer when you cannot host PHP in the shop or need SaaS-style isolation. Follow the [app base guide](../../plugins/apps/app-base-guide.md) for manifest and server structure.
* **Theme**: To customize the visual appearance of the Shopware \[Storefront] only. Follow the [theme base guide](../../plugins/themes/theme-base-guide.md) for guidance.

## Project/bundle structure

* Keep domain logic in bundles, not in templates or controllers; expose services via dependency injection. See the [bundle guide](../../plugins/plugins/bundle.md) for further guidance.
* Use Composer `type: shopware-platform-plugin` or `shopware-bundle` consistently; align namespaces with the bundle name.
* Isolate integration points (events, DAL extensions) behind service classes so upgrades only touch narrow surfaces.

## Plugin structure (static/custom and managed/Store)

* Start from the default plugin skeleton ([plugin base guide](../../plugins/plugins/plugin-base-guide.md)); avoid bespoke auto-loaders or custom entrypoints.
* Keep configuration, migrations, administration, and storefront assets in their default folders; avoid cross-wiring plugins.
* Encapsulate database schema changes with migrations; ship idempotent install/update code.
* For Store plugins, avoid hard project assumptions (hostnames, queues, cron timing, file access); document requirements and provide safe fallbacks.

## App structure

* Keep the manifest minimal and explicit: permissions, webhooks, actions, and extensions should match the documented entrypoints. See the [app base guide](../../plugins/apps/app-base-guide.md) for further guidance.
* Separate app backend (API/webhook handlers) from UI assets.
* Avoid stateful coupling to shop runtime; design for multi-tenant hosting.

## Upgrade-oriented structure

To reduce upgrade friction:

* Avoid scattering related logic across multiple independent plugins.
* Prefer a single repository with consistent tooling.
* Keep integration points (events, decorators, DAL extensions) isolated behind service classes.
* Minimize cross-plugin dependencies.

The more surface area exposed to the platform, the more upgrade effort is created.

---

---
url: /docs/resources/references/adr/2023-08-03-collecting-entity-data.md
---

# Collecting and dispatching entity data

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2023-08-03-collecting-entity-data.md)
:::

## Context

*shopware AG* aims to provide data-driven features to its merchants.
The foundation for these features are data that our merchants provide to us with their consent.
A subset and primary pillar of these data lies within the entities, stored within each and every Shopware shop.
This ADR addresses main concepts of extracting the information out of the shops and transferring it to *shopware AG*.

## Decision

### No data sharing without consent

Merchants must explicitly agree and consent to share their data with *shopware AG*.
As long as there is no consent, no data will be collected or transferred.
The consent to data sharing can be revoked at any time by the merchants.

We will actively prompt Administration users to decide whether they are willing to give their consent to data sharing on the Administration's dashboard.
Changing the consent state later is possible via the system settings. To keep track of the consent changes, we will send to and store it on our gateway.

### No collection of sensitive information

Data stored in all types of entities might contain sensitive information including e.g. personal or business critical information.
This kind of data is excluded.

### Personally identifiable information (PII)

Data that would enable *shopware AG* to identify a person is modified in such a way that it is no longer possible to draw conclusions about the person.
A so-called *personal unique identifier (PUID)* is generated to identify users across multiple sources (e.g. entity data, on-site tracking) with the goal of analyzing their behavior which is used for generating insights and making predictions.
Again, it is not possible to find out **who** the person is, just that it is the **same** person.

### Transitioning to data pulling

The processes described in this ADR can be viewed as an approach of *data pushing*.
Data is fetched from the database and prepared on the merchant's servers and infrastructure before it is sent to *shopware AG*.

To be more flexible and to reduce the load on our merchant's infrastructure, we plan to transition to a *data pulling* approach.
With this approach we are planning to use Shopware's Admin API to fetch the data, rather than fetching it from the database directly.

### Providing data-driven features via the app system

The features built upon the data that is collected, will be rolled out as an extension based on the app system.
This way, we make feature releases independent of the Shopware 6 release cycle and can provide new features faster.

### Including entities and fields

By default, entities are not considered for data collection.
Only entities and their fields listed in an allow-list will be included in the data collection.

The format looks as follows:

```json
{
    "entity_one": [
        "fieldOne",
        "fieldTwo",
        "fieldThree"
    ],
    "entity_two": [
        "fieldOne",
        "fieldTwo"
    ],
    "entity_three": [
        "fieldOne"
    ]
}
```

Example:

```json
{
    "category": [
        "id",
        "parentId",
        "type"
    ],
    "product": [
        "id",
        "parentId",
        "name"
    ]
}
```

#### Many-to-many associations

Entities representing many-to-many associations between other entities should not be included in the allow-list.
Instead, they are either fetched from the database directly or resolved by querying the associated entity table.

When adding a many-to-many association to the allow-list, the referenced field is the `associationName` instead of the `propertyName`.

Example:

```php
class ProductDefinition
{
    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            // ...
            (new ManyToManyIdField('category_ids', 'categoryIds', associationName: 'categories'))->addFlags(new ApiAware(), new Inherited()),
            (new ManyToManyAssociationField('categories', CategoryDefinition::class, ProductCategoryDefinition::class, 'product_id', 'category_id'))->addFlags(new ApiAware(), new CascadeDelete(), new Inherited(), new SearchRanking(SearchRanking::ASSOCIATION_SEARCH_RANKING)),
            // ...
            (new ManyToManyAssociationField('tags', TagDefinition::class, ProductTagDefinition::class, 'product_id', 'tag_id'))->addFlags(new CascadeDelete(), new Inherited(), new SearchRanking(SearchRanking::ASSOCIATION_SEARCH_RANKING), new ApiAware()),
            // ...
        ]);
    }
}
```

```json
{
    "product": [
        "categories",
        "tags"
    ]
}
```

The allow-list contains the `categories` and the `tags` field of the product entity. When the data is queried from the database, the many-to-many associations are resolved as follows:

* Identifiers of many-to-many associations that have a corresponding `ManyToManyIdField` are fetched from the database directly.
* Other many-to-many associations are resolved by fetching the associated entities from the database beforehand and matching them against the currently processed entity.

#### Associations problem: product -> category

#### Translated fields

Translated fields are not resolved automatically.
Instead, translation entities must be added to the allow-list explicitly.

## Consequences

#### Activating and deactivating the data collecting process

The process will be triggered once a day by a scheduled task as long as the consent is given.
It will also be triggered right away when the consent is given.
The merchant can revoke the consent at any time, which will prevent the process from starting.

#### Collecting data asynchronously

Once the process is running, for each entity definition, some messages will be added to a low priority message queue, and so they will be processed asynchronously.
The process will create batches of up to 50 entities (configurable) before sending them to the gateway.

#### First run and consecutive runs

Deltas of the data are calculated after the first time the data is sent, so consecutive runs are lighter and faster.
In order to achieve this, the process will keep track of the last time the data was sent and will only send the data that was created or updated after that time.

For deletions, an event subscriber will take care of storing the deletions of the entities.
These deletions will be sent and deleted when the process is run.
No deletion will be stored if the consent for collecting data is revoked or not given in the first place.

#### Remote kill-switch

A kill-switch on the Gateway enables us to (temporarily) stop shops from sending us data.
Messages already dispatched to the queue will still be handled but no new messages will be added by the scheduled task if the kill-switch is enabled.

---

---
url: /docs/v6.5/resources/references/adr/2023-08-03-collecting-entity-data.md
---

# Collecting and dispatching entity data

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2023-08-03-collecting-entity-data.md)
:::

## Context

*shopware AG* aims to provide data-driven features to its merchants.
The foundation for these features are data that our merchants provide to us with their consent.
A subset and primary pillar of these data lies within the entities, stored within each and every Shopware shop.
This ADR addresses main concepts of extracting the information out of the shops and transferring it to *shopware AG*.

## Decision

### No data sharing without consent

Merchants must explicitly agree and consent to share their data with *shopware AG*.
As long as there is no consent, no data will be collected or transferred.
The consent to data sharing can be revoked at any time by the merchants.

We will actively prompt Administration users to decide whether they are willing to give their consent to data sharing on the Administration's dashboard.
Changing the consent state later is possible via the system settings. To keep track of the consent changes, we will send to and store it on our gateway.

### No collection of sensitive information

Data stored in all types of entities might contain sensitive information including e.g. personal or business critical information.
This kind of data is excluded.

### Personally identifiable information (PII)

Data that would enable *shopware AG* to identify a person is modified in such a way that it is no longer possible to draw conclusions about the person.
A so-called *personal unique identifier (PUID)* is generated to identify users across multiple sources (e.g. entity data, on-site tracking) with the goal of analyzing their behavior which is used for generating insights and making predictions.
Again, it is not possible to find out **who** the person is, just that it is the **same** person.

### Transitioning to data pulling

The processes described in this ADR can be viewed as an approach of *data pushing*.
Data is fetched from the database and prepared on the merchant's servers and infrastructure before it is sent to *shopware AG*.

To be more flexible and to reduce the load on our merchant's infrastructure, we plan to transition to a *data pulling* approach.
With this approach we are planning to use Shopware's Admin API to fetch the data, rather than fetching it from the database directly.

### Providing data-driven features via the app system

The features built upon the data that is collected, will be rolled out as an extension based on the app system.
This way, we make feature releases independent of the Shopware 6 release cycle and can provide new features faster.

### Including entities and fields

By default, entities are not considered for data collection.
Only entities and their fields listed in an allow-list will be included in the data collection.

The format looks as follows:

```json
{
    "entity_one": [
        "fieldOne",
        "fieldTwo",
        "fieldThree"
    ],
    "entity_two": [
        "fieldOne",
        "fieldTwo"
    ],
    "entity_three": [
        "fieldOne"
    ]
}
```

Example:

```json
{
    "category": [
        "id",
        "parentId",
        "type"
    ],
    "product": [
        "id",
        "parentId",
        "name"
    ]
}
```

#### Many-to-many associations

Entities representing many-to-many associations between other entities should not be included in the allow-list.
Instead, they are either fetched from the database directly or resolved by querying the associated entity table.

When adding a many-to-many association to the allow-list, the referenced field is the `associationName` instead of the `propertyName`.

Example:

```php
class ProductDefinition
{
    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            // ...
            (new ManyToManyIdField('category_ids', 'categoryIds', associationName: 'categories'))->addFlags(new ApiAware(), new Inherited()),
            (new ManyToManyAssociationField('categories', CategoryDefinition::class, ProductCategoryDefinition::class, 'product_id', 'category_id'))->addFlags(new ApiAware(), new CascadeDelete(), new Inherited(), new SearchRanking(SearchRanking::ASSOCIATION_SEARCH_RANKING)),
            // ...
            (new ManyToManyAssociationField('tags', TagDefinition::class, ProductTagDefinition::class, 'product_id', 'tag_id'))->addFlags(new CascadeDelete(), new Inherited(), new SearchRanking(SearchRanking::ASSOCIATION_SEARCH_RANKING), new ApiAware()),
            // ...
        ]);
    }
}
```

```json
{
    "product": [
        "categories",
        "tags"
    ]
}
```

The allow-list contains the `categories` and the `tags` field of the product entity. When the data is queried from the database, the many-to-many associations are resolved as follows:

* Identifiers of many-to-many associations that have a corresponding `ManyToManyIdField` are fetched from the database directly.
* Other many-to-many associations are resolved by fetching the associated entities from the database beforehand and matching them against the currently processed entity.

#### Associations problem: product -> category

#### Translated fields

Translated fields are not resolved automatically.
Instead, translation entities must be added to the allow-list explicitly.

## Consequences

#### Activating and deactivating the data collecting process

The process will be triggered once a day by a scheduled task as long as the consent is given.
It will also be triggered right away when the consent is given.
The merchant can revoke the consent at any time, which will prevent the process from starting.

#### Collecting data asynchronously

Once the process is running, for each entity definition, some messages will be added to a low priority message queue, and so they will be processed asynchronously.
The process will create batches of up to 50 entities (configurable) before sending them to the gateway.

#### First run and consecutive runs

Deltas of the data are calculated after the first time the data is sent, so consecutive runs are lighter and faster.
In order to achieve this, the process will keep track of the last time the data was sent and will only send the data that was created or updated after that time.

For deletions, an event subscriber will take care of storing the deletions of the entities.
These deletions will be sent and deleted when the process is run.
No deletion will be stored if the consent for collecting data is revoked or not given in the first place.

#### Remote kill-switch

A kill-switch on the Gateway enables us to (temporarily) stop shops from sending us data.
Messages already dispatched to the queue will still be handled but no new messages will be added by the scheduled task if the kill-switch is enabled.

---

---
url: /docs/v6.6/resources/references/adr/2023-08-03-collecting-entity-data.md
---

# Collecting and dispatching entity data

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2023-08-03-collecting-entity-data.md)
:::

## Context

*shopware AG* aims to provide data-driven features to its merchants.
The foundation for these features are data that our merchants provide to us with their consent.
A subset and primary pillar of these data lies within the entities, stored within each and every Shopware shop.
This ADR addresses main concepts of extracting the information out of the shops and transferring it to *shopware AG*.

## Decision

### No data sharing without consent

Merchants must explicitly agree and consent to share their data with *shopware AG*.
As long as there is no consent, no data will be collected or transferred.
The consent to data sharing can be revoked at any time by the merchants.

We will actively prompt Administration users to decide whether they are willing to give their consent to data sharing on the Administration's dashboard.
Changing the consent state later is possible via the system settings. To keep track of the consent changes, we will send to and store it on our gateway.

### No collection of sensitive information

Data stored in all types of entities might contain sensitive information including e.g. personal or business critical information.
This kind of data is excluded.

### Personally identifiable information (PII)

Data that would enable *shopware AG* to identify a person is modified in such a way that it is no longer possible to draw conclusions about the person.
A so-called *personal unique identifier (PUID)* is generated to identify users across multiple sources (e.g. entity data, on-site tracking) with the goal of analyzing their behavior which is used for generating insights and making predictions.
Again, it is not possible to find out **who** the person is, just that it is the **same** person.

### Transitioning to data pulling

The processes described in this ADR can be viewed as an approach of *data pushing*.
Data is fetched from the database and prepared on the merchant's servers and infrastructure before it is sent to *shopware AG*.

To be more flexible and to reduce the load on our merchant's infrastructure, we plan to transition to a *data pulling* approach.
With this approach we are planning to use Shopware's Admin API to fetch the data, rather than fetching it from the database directly.

### Providing data-driven features via the app system

The features built upon the data that is collected, will be rolled out as an extension based on the app system.
This way, we make feature releases independent of the Shopware 6 release cycle and can provide new features faster.

### Including entities and fields

By default, entities are not considered for data collection.
Only entities and their fields listed in an allow-list will be included in the data collection.

The format looks as follows:

```json
{
    "entity_one": [
        "fieldOne",
        "fieldTwo",
        "fieldThree"
    ],
    "entity_two": [
        "fieldOne",
        "fieldTwo"
    ],
    "entity_three": [
        "fieldOne"
    ]
}
```

Example:

```json
{
    "category": [
        "id",
        "parentId",
        "type"
    ],
    "product": [
        "id",
        "parentId",
        "name"
    ]
}
```

#### Many-to-many associations

Entities representing many-to-many associations between other entities should not be included in the allow-list.
Instead, they are either fetched from the database directly or resolved by querying the associated entity table.

When adding a many-to-many association to the allow-list, the referenced field is the `associationName` instead of the `propertyName`.

Example:

```php
class ProductDefinition
{
    protected function defineFields(): FieldCollection
    {
        return new FieldCollection([
            // ...
            (new ManyToManyIdField('category_ids', 'categoryIds', associationName: 'categories'))->addFlags(new ApiAware(), new Inherited()),
            (new ManyToManyAssociationField('categories', CategoryDefinition::class, ProductCategoryDefinition::class, 'product_id', 'category_id'))->addFlags(new ApiAware(), new CascadeDelete(), new Inherited(), new SearchRanking(SearchRanking::ASSOCIATION_SEARCH_RANKING)),
            // ...
            (new ManyToManyAssociationField('tags', TagDefinition::class, ProductTagDefinition::class, 'product_id', 'tag_id'))->addFlags(new CascadeDelete(), new Inherited(), new SearchRanking(SearchRanking::ASSOCIATION_SEARCH_RANKING), new ApiAware()),
            // ...
        ]);
    }
}
```

```json
{
    "product": [
        "categories",
        "tags"
    ]
}
```

The allow-list contains the `categories` and the `tags` field of the product entity. When the data is queried from the database, the many-to-many associations are resolved as follows:

* Identifiers of many-to-many associations that have a corresponding `ManyToManyIdField` are fetched from the database directly.
* Other many-to-many associations are resolved by fetching the associated entities from the database beforehand and matching them against the currently processed entity.

#### Associations problem: product -> category

#### Translated fields

Translated fields are not resolved automatically.
Instead, translation entities must be added to the allow-list explicitly.

## Consequences

#### Activating and deactivating the data collecting process

The process will be triggered once a day by a scheduled task as long as the consent is given.
It will also be triggered right away when the consent is given.
The merchant can revoke the consent at any time, which will prevent the process from starting.

#### Collecting data asynchronously

Once the process is running, for each entity definition, some messages will be added to a low priority message queue, and so they will be processed asynchronously.
The process will create batches of up to 50 entities (configurable) before sending them to the gateway.

#### First run and consecutive runs

Deltas of the data are calculated after the first time the data is sent, so consecutive runs are lighter and faster.
In order to achieve this, the process will keep track of the last time the data was sent and will only send the data that was created or updated after that time.

For deletions, an event subscriber will take care of storing the deletions of the entities.
These deletions will be sent and deleted when the process is run.
No deletion will be stored if the consent for collecting data is revoked or not given in the first place.

#### Remote kill-switch

A kill-switch on the Gateway enables us to (temporarily) stop shops from sending us data.
Messages already dispatched to the queue will still be handled but no new messages will be added by the scheduled task if the kill-switch is enabled.

---

---
url: /docs/products/tools/cli/command-types.md
---

# Command Types

Shopware CLI is organized into three main command scopes that cover the most common development and maintenance workflows:

* Project commands: interact with your Shopware project (e.g., build, dump DB, or sync configuration)
* Extension commands: build and validate Shopware extensions
* Store commands: publish or update extensions in the Shopware Store

## Automatic refactoring

Shopware CLI also includes an automatic refactoring tool for PHP, JavaScript, and Admin Twig files. It uses:

* [Rector](https://getrector.org/) for PHP
* [ESLint](https://eslint.org/) for JavaScript
* Custom rules for Admin Twig

You can run it on an extension or a full project:

```bash
# Example: refactor an extension
shopware-cli extension fix /path/to/your/extension

# Example: refactor an entire project
shopware-cli project fix /path/to/your/project
```

Always back up or version your code before running refactoring commands, as they will modify files in place. [Learn more here](automatic-refactoring.md).

### Project commands

Work directly with your [Shopware project](../../../guides/hosting/installation-updates/deployments/index.md) to automate setup and maintenance tasks. Available commands include:

```bash
shopware-cli project create         # Create a new Shopware 6 project
shopware-cli project dump       # Dumps the Shopware database
shopware-cli project ci          # Build Shopware in the CI
shopware-cli project sbom        # Generate a CycloneDX SBOM from composer.lock
```

### Extension commands

Create, build, and validate Shopware [extensions](../../../guides/plugins/index.md) and prepare them for the [Shopware Store](https://store.shopware.com/de/) or for distribution. Available commands include:

```bash
shopware-cli extension fix   # Fix an extension
shopware-cli extension build    # Builds assets for extensions
shopware-cli extension validate         # Validate an extension
```

### Store commands

Publish and manage your extensions in the [Store](https://store.shopware.com/de/), with commands such as:

```bash
shopware-cli account login    # Log in to the Shopware Store (account.shopware.com)
shopware-cli token            # Manage tokens for Store authentication
```

Run any command with `--help` to see its available options. Example: `shopware-cli extension --help`

---

---
url: /docs/resources/references/core-reference/commands-reference.md
---

# Commands Reference

These commands can be executed using the Shopware command line interface (CLI), located within your Shopware project.

```bash
$ bin/console [command] [parameters]
```

## Commands

### General

| Command      | Description                                    |
|:-------------|:-----------------------------------------------|
| `about`      | Displays information about the current project |
| `completion` | Dumps the shell completion script              |
| `help`       | Displays help for a command                    |
| `list`       | Lists commands                                 |

### Administration

| Command                                              | Description                                                                                                                                                   |
|:-----------------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `administration:delete-extension-local-public-files` | Deletes all files in the local public folder of the extension. This command should run after assets:install so the assets are available in the public folder. |
| `administration:delete-files-after-build`            | Deletes all unnecessary files of the administration after the build process                                                                                   |

### App

| Command                  | Description                                                              |
|:-------------------------|:-------------------------------------------------------------------------|
| `app:activate`           | Activates the app in the folder with the given name                      |
| `app:create`             | Creates an app skeleton                                                  |
| `app:deactivate`         | Deactivates the app in the folder with the given name                    |
| `app:install`            | Installs the app in the folder with the given name                       |
| `app:list`               | Lists all apps                                                           |
| `app:refresh`            | \[app:update] Refreshes the installed apps                              |
| `app:uninstall`          | Uninstalls the app                                                       |
| `app:url-change:resolve` | Resolves changes in the app URL and how the app system should handle it. |
| `app:validate`           | Checks manifests for errors                                              |

### Assets

| Command          | Description                                              |
|:-----------------|:---------------------------------------------------------|
| `assets:install` | Installs bundles web assets under a public web directory |

### Bundle

| Command       | Description                                                                                                                              |
|:--------------|:-----------------------------------------------------------------------------------------------------------------------------------------|
| `bundle:dump` | \[administration:dump:plugins|administration:dump:bundles] Creates a JSON file with the configuration for each active Shopware bundle. |

### Cache

| Command                      | Description                                                                             |
|:-----------------------------|:----------------------------------------------------------------------------------------|
| `cache:clear`                | Clears the cache                                                                        |
| `cache:clear:all`            | Clears all caches/pools, invalidates expired tags, removes old kernel cache directories |
| `cache:clear:delayed`        | Invalidates the delayed cache keys/tags                                                 |
| `cache:clear:http`           | Clears only the HTTP cache                                                              |
| `cache:pool:clear`           | Clears cache pools                                                                      |
| `cache:pool:delete`          | Deletes an item from a cache pool                                                       |
| `cache:pool:invalidate-tags` | Invalidates cache tags for all or a specific pool                                       |
| `cache:pool:list`            | Lists available cache pools                                                             |
| `cache:pool:prune`           | Prunes cache pools                                                                      |
| `cache:warmup`               | Warms up an empty cache                                                                 |
| `cache:watch:delayed`        | Watches the delayed cache keys/tags                                                     |

### Cart

| Command        | Description                           |
|:---------------|:--------------------------------------|
| `cart:migrate` | Migrates carts from redis to database |

### Changelog

| Command             | Description                                                                                            |
|:--------------------|:-------------------------------------------------------------------------------------------------------|
| `changelog:change`  | Returns all changes made in a specific / unreleased version.                                           |
| `changelog:check`   | Checks the validation of a given changelog file or of all files in the "changelog/\_unreleased" folder |
| `changelog:create`  | Creates a changelog markdown file in `/changelog/_unreleased`                                          |
| `changelog:release` | Creates or updates the final changelog for a new release                                               |

### Config

| Command                 | Description                                      |
|:------------------------|:-------------------------------------------------|
| `config:dump-reference` | Dumps the default configuration for an extension |

### Customer

| Command                         | Description                    |
|:--------------------------------|:-------------------------------|
| `customer:delete-unused-guests` | Deletes unused guest customers |

### Dal

| Command                | Description                            |
|:-----------------------|:---------------------------------------|
| `dal:create:entities`  | Creates the entity classes             |
| `dal:create:hydrators` | Creates the hydrator classes           |
| `dal:migration:create` | Creates migration for entity schema    |
| `dal:create:schema`    | Creates the database schema            |
| `dal:refresh:index`    | Refreshes the index for a given entity |
| `dal:validate`         | Validates the DAL definitions          |

### Database

| Command                        | Description                            |
|:-------------------------------|:---------------------------------------|
| `database:clean-personal-data` | Cleans personal data from the database |
| `database:create-migration`    | Creates a new migration file           |
| `database:migrate`             | Executes all migrations                |
| `database:migrate-destructive` | Executes all migrations                |
| `database:refresh-migration`   | Refreshes the migration state          |

### Debug

| Command                  | Description                                                |
|:-------------------------|:-----------------------------------------------------------|
| `debug:autowiring`       | Lists classes/interfaces you can use for autowiring        |
| `debug:business-events`  | Dumps all business events                                  |
| `debug:config`           | Dumps the current configuration for an extension           |
| `debug:container`        | Displays current services for an application               |
| `debug:dotenv`           | Lists all dotenv files with variables and values           |
| `debug:event-dispatcher` | Displays configured listeners for an application           |
| `debug:messenger`        | Lists messages you can dispatch using the message buses    |
| `debug:router`           | Displays current routes for an application                 |
| `debug:scheduler`        | Lists schedules and their recurring messages               |
| `debug:serializer`       | Displays serialization information for classes             |
| `debug:translation`      | Displays translation messages information                  |
| `debug:twig`             | Shows a list of twig functions, filters, globals and tests |
| `debug:validator`        | Displays validation constraints for classes                |

### Dotenv

| Command       | Description                           |
|:--------------|:--------------------------------------|
| `dotenv:dump` | Compiles .env files to .env.local.php |

### Error

| Command      | Description                                                                       |
|:-------------|:----------------------------------------------------------------------------------|
| `error:dump` | Dumps error pages to plain HTML files that can be directly served by a web server |

### Es

| Command                   | Description                                    |
|:--------------------------|:-----------------------------------------------|
| `es:admin:index`          | Indexes the elasticsearch for the admin search |
| `es:admin:mapping:update` | Updates the Elasticsearch indices mapping      |
| `es:admin:reset`          | Resets Admin Elasticsearch indexing            |
| `es:admin:test`           | Allows you to test the admin search index      |
| `es:create:alias`         | Creates the elasticsearch alias                |
| `es:index`                | Reindexes all entities to elasticsearch        |
| `es:index:cleanup`        | Cleans outdated indices                        |
| `es:mapping:update`       | Update the Elasticsearch indices mapping       |
| `es:reset`                | Resets the elasticsearch index                 |
| `es:status`               | Shows the status of the elasticsearch index    |
| `es:test:analyzer`        | Allows to test an elasticsearch analyzer       |

### Feature

| Command           | Description                                                                                                            |
|:------------------|:-----------------------------------------------------------------------------------------------------------------------|
| `feature:disable` | Disables feature flags                                                                                                 |
| `feature:dump`    | \[administration:dump:features] Creates a JSON file with feature config for JS testing and hot reloading capabilities |
| `feature:enable`  | Enables feature flags                                                                                                  |
| `feature:list`    | Lists all registered features                                                                                          |

### Framework

| Command                       | Description                              |
|:------------------------------|:-----------------------------------------|
| `framework:demodata`          | Generates demo data                      |
| `framework:dump:class:schema` | Dumps the schema of the given entity     |
| `framework:schema`            | Dumps the api definition to a json file. |

### Http

| Command              | Description             |
|:---------------------|:------------------------|
| `http:cache:warm:up` | Warms up the HTTP cache |

### Import

| Command         | Description                      |
|:----------------|:---------------------------------|
| `import:entity` | Imports entities from a CSV file |

### Import-export

| Command                        | Description                             |
|:-------------------------------|:----------------------------------------|
| `import-export:delete-expired` | Deletes all expired import/export files |

### Integration

| Command              | Description                                        |
|:---------------------|:---------------------------------------------------|
| `integration:create` | Creates an integration and dump the key and secret |

### Lint

| Command             | Description                                                           |
|:--------------------|:----------------------------------------------------------------------|
| `lint:container`    | Ensures that arguments injected into services match type declarations |
| `lint:translations` | Lints translations files syntax and outputs encountered errors        |
| `lint:twig`         | Lints a Twig template and outputs encountered errors                  |
| `lint:xliff`        | Lints a XLIFF file and outputs encountered errors                     |
| `lint:yaml`         | Lints a YAML file and outputs encountered errors                      |

### Mailer

| Command       | Description                                 |
|:--------------|:--------------------------------------------|
| `mailer:test` | Tests Mailer transports by sending an email |

### Make plugin

Generating the skeletons and essential files needed to create and structure a Shopware plugin.

| Command                             | Description                                     |
|:------------------------------------|:------------------------------------------------|
| `make:plugin:admin-module`          | Generates an administration module skeleton     |
| `make:plugin:command`               | Generates a plugin CLI command skeleton         |
| `make:plugin:composer`              | Generates a composer configuration for a plugin |
| `make:plugin:config`                | Generates a plugin system config skeleton       |
| `make:plugin:custom-fieldset`       | Generates a custom field set for a plugin       |
| `make:plugin:entity`                | Generates entity scaffolding for a plugin       |
| `make:plugin:event-subscriber`      | Generates an event subscriber skeleton          |
| `make:plugin:javascript-plugin`     | Generates a JavaScript plugin skeleton          |
| `make:plugin:plugin-class`          | Generates the base plugin class                 |
| `make:plugin:scheduled-task`        | Generates a scheduled task skeleton             |
| `make:plugin:store-api-route`       | Generates a Store API route skeleton            |
| `make:plugin:storefront-controller` | Generates a Storefront controller skeleton      |
| `make:plugin:tests`                 | Generates a plugin tests skeleton               |

### Media

| Command                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
|:--------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `media:delete-local-thumbnails` | Deletes all physical media thumbnails when remote thumbnails is enabled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `media:delete-unused`           | Deletes all media files that are never used. Use the `--dry-run` flag to see a paginated list of files that will be deleted, without actually deleting them. Use the `--grace-period-days=10` to set a grace period for unused media, meaning only media uploaded before the current date and time minus 10 days will be considered for deletion. The default is 20 and therefore any media uploaded in the previous 20 days will not be considered for deletion even if it is unused. Use the `--folder-entity` flag to target only a specific folder (e.g. `--folder-entity=PRODUCT` to purge all product images) |
| `media:generate-media-types`    | Generates the media types for all media entities                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `media:generate-thumbnails`     | Generates the thumbnails for all media entities                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `media:update-path`             | Iterates over the media and updates the path column.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |

### Messenger

| Command                      | Description                                             |
|:-----------------------------|:--------------------------------------------------------|
| `messenger:consume`          | Consumes messages                                       |
| `messenger:failed:remove`    | Removes given messages from the failure transport       |
| `messenger:failed:retry`     | Retries one or more messages from the failure transport |
| `messenger:failed:show`      | Shows one or more messages from the failure transport   |
| `messenger:setup-transports` | Prepares the required infrastructure for the transport  |
| `messenger:stats`            | Shows the message count for one or more transports      |
| `messenger:stop-workers`     | Stops workers after their current message               |

### Number-range

| Command                | Description                                      |
|:-----------------------|:-------------------------------------------------|
| `number-range:migrate` | Migrates the increment storage of a number range |

### Plugin

| Command             | Description                                                    |
|:--------------------|:---------------------------------------------------------------|
| `plugin:activate`   | Activates given plugins                                        |
| `plugin:create`     | Creates a plugin skeleton                                      |
| `plugin:deactivate` | Deactivates given plugins                                      |
| `plugin:install`    | Installs given plugins                                         |
| `plugin:list`       | Lists all plugins                                              |
| `plugin:refresh`    | Refreshes the plugins list in the storage from the file system |
| `plugin:uninstall`  | Uninstalls given plugins                                       |
| `plugin:update`     | Updates given plugins                                          |
| `plugin:update:all` | Install all available plugin updates                           |
| `plugin:zip-import` | Imports a plugin from a zip file                               |

### Product-export

| Command                   | Description                     |
|:--------------------------|:--------------------------------|
| `product-export:generate` | Generates a product export file |

### Router

| Command        | Description                                        |
|:---------------|:---------------------------------------------------|
| `router:match` | Helps debug routes by simulating a path info match |

### S3

| Command             | Description                                                     |
|:--------------------|:----------------------------------------------------------------|
| `s3:set-visibility` | Sets the visibility of all files in the s3 filesystem to public |

### Sales-channel

| Command                             | Description                                   |
|:------------------------------------|:----------------------------------------------|
| `sales-channel:create`              | Creates a new sales channel                   |
| `sales-channel:create:storefront`   | Creates a new storefront sales channel        |
| `sales-channel:list`                | Lists all sales channels                      |
| `sales-channel:maintenance:disable` | Disables maintenance mode for a sales channel |
| `sales-channel:maintenance:enable`  | Enables maintenance mode for a sales channel  |
| `sales-channel:update:domain`       | Updates a sales channel domain                |

### Scheduled-task

| Command                     | Description                   | Version |
|:----------------------------|:------------------------------|:--------|
| `scheduled-task:deactivate` | Deactivate a scheduled task   | 6.7.2.0 |
| `scheduled-task:register`   | Registers all scheduled tasks |
| `scheduled-task:run`        | Runs scheduled tasks          |
| `scheduled-task:run-single` | Runs single scheduled tasks   | 6.5.5.0 |
| `scheduled-task:list`       | Lists all scheduled tasks     | 6.5.5.0 |
| `scheduled-task:schedule`   | Schedule a scheduled task     | 6.7.2.0 |

### Secrets

| Command                      | Description                                             |
|:-----------------------------|:--------------------------------------------------------|
| `secrets:decrypt-to-local`   | Decrypts all secrets and stores them in the local vault |
| `secrets:encrypt-from-local` | Encrypts all local secrets to the vault                 |
| `secrets:generate-keys`      | Generates new encryption keys                           |
| `secrets:list`               | Lists all secrets                                       |
| `secrets:remove`             | Removes a secret from the vault                         |
| `secrets:reveal`             | Reveals the value of a secret                           |
| `secrets:set`                | Sets a secret in the vault                              |

### Server

| Command       | Description                                                             |
|:--------------|:------------------------------------------------------------------------|
| `server:dump` | Starts a dump server that collects and displays dumps in a single place |
| `server:log`  | Starts a log server that displays logs in real time                     |

### Services

| Command            | Description           |
|:-------------------|:----------------------|
| `services:install` | Installs all services |

### Sitemap

| Command            | Description                                                |
|:-------------------|:-----------------------------------------------------------|
| `sitemap:generate` | Generates sitemaps for a given shop (or all active ones) |

### Snippets

| Command             | Description        |
|:--------------------|:-------------------|
| `snippets:validate` | Validates snippets |

### State-machine

| Command              | Description                              |
|:---------------------|:-----------------------------------------|
| `state-machine:dump` | Dumps a state machine to a graphviz file |

### Store

| Command          | Description                       |
|:-----------------|:----------------------------------|
| `store:download` | Downloads a plugin from the store |
| `store:login`    | Login for the store               |

### System

| Command                      | Description                                                                        |
|:-----------------------------|:-----------------------------------------------------------------------------------|
| `system:check`               | Checks the shopware application system health                                      |
| `system:config:get`          | Gets a config value                                                                |
| `system:config:set`          | Sets a config value                                                                |
| `system:configure-shop`      | Configures the shop                                                                |
| `system:generate-app-secret` | Generates a new app secret                                                         |
| `system:install`             | Installs the Shopware 6 system                                                     |
| `system:is-installed`        | Checks if the system is installed and returns exit code 0 if Shopware is installed |
| `system:setup`               | Starts system setup                                                                |
| `system:setup:staging`       | Installs the Shopware 6 system in staging mode                                     |
| `system:update:finish`       | Finishes the update process                                                        |
| `system:update:prepare`      | Prepares the update process                                                        |

### Theme

| Command               | Description                                  |
|:----------------------|:---------------------------------------------|
| `theme:change`        | Changes the active theme for a sales channel |
| `theme:compile`       | Compiles the theme                           |
| `theme:create`        | Creates a theme skeleton                     |
| `theme:dump`          | Dumps the theme configuration                |
| `theme:prepare-icons` | Prepares the theme icons                     |
| `theme:refresh`       | Refreshes the theme configuration            |

### Translation

| Command               | Description                                                                                                                    |
|:----------------------|:-------------------------------------------------------------------------------------------------------------------------------|
| `translation:extract` | Extracts missing translations keys from code to translation files                                                              |
| `translation:install` | Downloads and installs translations from the translations GitHub repository for the specified locales or all available locales |
| `translation:pull`    | Pulls translations from a given provider.                                                                                      |
| `translation:push`    | Pushes translations to a given provider.                                                                                       |

### User

| Command                | Description                    |
|:-----------------------|:-------------------------------|
| `user:change-password` | Changes the password of a user |
| `user:create`          | Creates a new user             |
| `user:list`            | Lists current users            |

---

---
url: /docs/v6.5/resources/references/core-reference/commands-reference.md
---

# Commands Reference

These commands can be executed using the Shopware command line interface (CLI), located within your Shopware project.

```bash
$ bin/console [command] [parameters]
```

## Commands

### General

| Command | Description |
| :--- | :--- |
| `about` | Displays information about the current project |
| `help` | Displays help for a command |
| `list` | Lists commands |

### Administration

| Command | Description |
| :--- | :--- |
| `administration:delete-files-after-build` | Deletes all unnecessary files of the administration after the build process |

### App

| Command | Description |
| :--- | :--- |
| `app:activate` | Activates the app in the folder with the given name |
| `app:create` | Creates an app skeleton |
| `app:deactivate` | Deactivates the app in the folder with the given name |
| `app:install` | Installs the app in the folder with the given name |
| `app:refresh` | \[app:update] Refreshes the installed apps |
| `app:uninstall` | Uninstalls the app |
| `app:url-change:resolve` | Resolves changes in the app URL and how the app system should handle it. |
| `app:validate` | Checks manifests for errors |

### Assets

| Command | Description |
| :--- | :--- |
| `assets:install` |  |

### Bundle

| Command | Description |
| :--- | :--- |
| `bundle:dump` | \[administration:dump:plugins|administration:dump:bundles] Creates a JSON file with the configuration for each active Shopware bundle. |

### Cache

| Command | Description |
| :--- | :--- |
| `cache:clear` | Clears the cache |
| `cache:pool:clear` | Clears cache pools |
| `cache:pool:delete` | Deletes an item from a cache pool |
| `cache:pool:list` | Lists available cache pools |
| `cache:pool:prune` | Prunes cache pools |
| `cache:warmup` | Warms up an empty cache |

### Cart

| Command | Description |
| :--- | :--- |
| `cart:migrate` | Migrates carts from redis to database |

### Changelog

| Command | Description |
| :--- | :--- |
| `changelog:change` | Returns all changes made in a specific / unreleased version. |
| `changelog:check` | Checks the validation of a given changelog file or of all files in the "changelog/\_unreleased" folder |
| `changelog:create` | Creates a changelog markdown file in `/changelog/_unreleased` |
| `changelog:release` | Creates or updates the final changelog for a new release |

### Config

| Command | Description |
| :--- | :--- |
| `config:dump-reference` | Dumps the default configuration for an extension |

### Customer

| Command | Description |
| :--- | :--- |
| `customer:delete-unused-guests` | Deletes unused guest customers |

### Dal

| Command | Description |
| :--- | :--- |
| `dal:create:entities` | Creates the entity classes |
| `dal:create:hydrators` | Creates the hydrator classes |
| `dal:create:schema` | Creates the database schema |
| `dal:refresh:index` | Refreshes the index for a given entity |
| `dal:validate` | Validates the DAL definitions |

### Database

| Command | Description |
| :--- | :--- |
| `database:clean-personal-data` | Cleans personal data from the database |
| `database:create-migration` | Creates a new migration file |
| `database:migrate` | Executes all migrations |
| `database:migrate-destructive` | Executes all migrations |
| `database:refresh-migration` | Refreshes the migration state |

### Debug

| Command | Description |
| :--- | :--- |
| `debug:autowiring` | Lists classes/interfaces you can use for autowiring |
| `debug:business-events` | Dumps all business events |
| `debug:config` | Dumps the current configuration for an extension |
| `debug:container` | Displays current services for an application |
| `debug:event-dispatcher` | Displays configured listeners for an application |
| `debug:messenger` | Lists messages you can dispatch using the message buses |
| `debug:router` | Displays current routes for an application |
| `debug:translation` | Displays translation messages information |
| `debug:twig` | Shows a list of twig functions, filters, globals and tests |

### Es

| Command | Description |
| :--- | :--- |
| `es:admin:index` | Indexes the elasticsearch for the admin search |
| `es:admin:reset` | Reset Admin Elasticsearch indexing |
| `es:admin:test` | Allows you to test the admin search index |
| `es:create:alias` | Creates the elasticsearch alias |
| `es:index` | Reindexes all entities to elasticsearch |
| `es:index:cleanup` | Cleans outdated indices |
| `es:reset` | Resets the elasticsearch index |
| `es:status` | Shows the status of the elasticsearch index |
| `es:test:analyzer` | Allows to test an elasticsearch analyzer |

### Feature

| Command | Description |
| :--- | :--- |
| `feature:dump` | \[administration:dump:features] Creates a JSON file with feature config for JS testing and hot reloading capabilities |

### Framework

| Command | Description |
| :--- | :--- |
| `framework:demodata` | Generates demo data |
| `framework:dump:class:schema` | Dumps the schema of the given entity |
| `framework:schema` | Dumps the api definition to a json file. |

### Http

| Command | Description |
| :--- | :--- |
| `http:cache:warm:up` | Warms up the HTTP cache |

### Import

| Command | Description |
| :--- | :--- |
| `import:entity` | Imports entities from a CSV file |

### Import-export

| Command | Description |
| :--- | :--- |
| `import-export:delete-expired` | Deletes all expired import/export files |

### Lint

| Command | Description |
| :--- | :--- |
| `lint:container` | Ensures that arguments injected into services match type declarations |
| `lint:twig` | Lints a Twig template and outputs encountered errors |
| `lint:xliff` | Lints a XLIFF file and outputs encountered errors |
| `lint:yaml` | Lints a YAML file and outputs encountered errors |

### Mailer

| Command | Description |
| :--- | :--- |
| `mailer:test` | Tests Mailer transports by sending an email |

### Media

| Command                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
|:-----------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `media:delete-unused`        |  Deletes all media files that are never used. Use the `--dry-run` flag to see a paginated list of files that will be deleted, without actually deleting them. Use the `--grace-period-days=10` to set a grace period for unused media, meaning only media uploaded before the current date and time minus 10 days will be considered for deletion. The default is 20 and therefore any media uploaded in the previous 20 days will not be considered for deletion even if it is unused. Use the `--folder-entity` flag to target only a specific folder (e.g. `--folder-entity=PRODUCT` to purge all product images) |
| `media:generate-media-types` | Generates the media types for all media entities                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `media:generate-thumbnails`  | Generates the thumbnails for all media entities                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### Messenger

| Command | Description |
| :--- | :--- |
| `messenger:consume` | Consumes messages |
| `messenger:failed:remove` | Removes given messages from the failure transport |
| `messenger:failed:retry` | Retries one or more messages from the failure transport |
| `messenger:failed:show` | Shows one or more messages from the failure transport |
| `messenger:setup-transports` | Prepares the required infrastructure for the transport |
| `messenger:stats` | Shows the message count for one or more transports |
| `messenger:stop-workers` | Stops workers after their current message |

### Number-range

| Command | Description |
| :--- | :--- |
| `number-range:migrate` | Migrates the increment storage of a number range |

### Plugin

| Command | Description |
| :--- | :--- |
| `plugin:activate` | Activates given plugins |
| `plugin:create` | Creates a plugin skeleton |
| `plugin:deactivate` | Deactivates given plugins |
| `plugin:install` | Installs given plugins |
| `plugin:list` | Lists all plugins |
| `plugin:refresh` | Refreshes the plugins list in the storage from the file system |
| `plugin:uninstall` | Uninstalls given plugins |
| `plugin:update` | Updates given plugins |
| `plugin:zip-import` | Imports a plugin from a zip file |

### Product-export

| Command | Description |
| :--- | :--- |
| `product-export:generate` | Generates a product export file |

### Router

| Command | Description |
| :--- | :--- |
| `router:match` | Helps debug routes by simulating a path info match |

### S3

| Command | Description |
| :--- | :--- |
| `s3:set-visibility` | Sets the visibility of all files in the s3 filesystem to public |

### Sales-channel

| Command | Description |
| :--- | :--- |
| `sales-channel:create` | Creates a new sales channel |
| `sales-channel:create:storefront` | Creates a new storefront sales channel |
| `sales-channel:list` | Lists all sales channels |
| `sales-channel:maintenance:disable` | Disables maintenance mode for a sales channel |
| `sales-channel:maintenance:enable` | Enables maintenance mode for a sales channel |
| `sales-channel:update:domain` | Updates a sales channel domain |

### Scheduled-task

| Command | Description | Version |
| :--- | :--- | :--- |
| `scheduled-task:register` | Registers all scheduled tasks |
| `scheduled-task:run` | Runs scheduled tasks |
| `scheduled-task:run-single` | Runs single scheduled tasks | 6.5.5.0 |
| `scheduled-task:list` | Lists all scheduled tasks | 6.5.5.0 |

### Secrets

| Command | Description |
| :--- | :--- |
| `secrets:decrypt-to-local` | Decrypts all secrets and stores them in the local vault |
| `secrets:encrypt-from-local` | Encrypts all local secrets to the vault |
| `secrets:generate-keys` | Generates new encryption keys |
| `secrets:list` | Lists all secrets |
| `secrets:remove` | Removes a secret from the vault |
| `secrets:set` | Sets a secret in the vault |

### Sitemap

| Command | Description |
| :--- | :--- |
| `sitemap:generate` | Generates sitemaps for a given shop (or all active ones) |

### Snippets

| Command | Description |
| :--- | :--- |
| `snippets:validate` | Validates snippets |

### State-machine

| Command | Description |
| :--- | :--- |
| `state-machine:dump` | Dumps a state machine to a graphviz file |

### Store

| Command | Description |
| :--- | :--- |
| `store:download` | Downloads a plugin from the store |
| `store:login` | Login for the store |

### System

| Command | Description |
| :--- | :--- |
| `system:config:get` | Gets a config value |
| `system:config:set` | Sets a config value |
| `system:configure-shop` | Configures the shop |
| `system:generate-app-secret` | Generates a new app secret |
| `system:generate-jwt-secret` | Generates a new JWT secret |
| `system:install` | Installs the Shopware 6 system |
| `system:setup` | Setup the system |
| `system:update:finish` | Finishes the update process |
| `system:update:prepare` | Prepares the update process |

### Theme

| Command | Description |
| :--- | :--- |
| `theme:change` | Changes the active theme for a sales channel |
| `theme:compile` | Compiles the theme |
| `theme:create` | Creates a theme skeleton |
| `theme:dump` | Dumps the theme configuration |
| `theme:prepare-icons` | Prepares the theme icons |
| `theme:refresh` | Refreshes the theme configuration |

### User

| Command | Description |
| :--- | :--- |
| `user:change-password` | Changes the password of a user |
| `user:create` | Creates a new user |

---

---
url: /docs/v6.6/resources/references/core-reference/commands-reference.md
---

# Commands Reference

These commands can be executed using the Shopware command line interface (CLI), located within your Shopware project.

```bash
$ bin/console [command] [parameters]
```

## Commands

### General

| Command | Description |
| :--- | :--- |
| `about` | Displays information about the current project |
| `help` | Displays help for a command |
| `list` | Lists commands |

### Administration

| Command | Description |
| :--- | :--- |
| `administration:delete-files-after-build` | Deletes all unnecessary files of the administration after the build process |

### App

| Command | Description |
| :--- | :--- |
| `app:activate` | Activates the app in the folder with the given name |
| `app:create` | Creates an app skeleton |
| `app:deactivate` | Deactivates the app in the folder with the given name |
| `app:install` | Installs the app in the folder with the given name |
| `app:refresh` | \[app:update] Refreshes the installed apps |
| `app:uninstall` | Uninstalls the app |
| `app:url-change:resolve` | Resolves changes in the app URL and how the app system should handle it. |
| `app:validate` | Checks manifests for errors |

### Assets

| Command | Description |
| :--- | :--- |
| `assets:install` |  |

### Bundle

| Command | Description |
| :--- | :--- |
| `bundle:dump` | \[administration:dump:plugins|administration:dump:bundles] Creates a JSON file with the configuration for each active Shopware bundle. |

### Cache

| Command | Description |
| :--- | :--- |
| `cache:clear` | Clears the cache |
| `cache:pool:clear` | Clears cache pools |
| `cache:pool:delete` | Deletes an item from a cache pool |
| `cache:pool:list` | Lists available cache pools |
| `cache:pool:prune` | Prunes cache pools |
| `cache:warmup` | Warms up an empty cache |

### Cart

| Command | Description |
| :--- | :--- |
| `cart:migrate` | Migrates carts from redis to database |

### Changelog

| Command | Description |
| :--- | :--- |
| `changelog:change` | Returns all changes made in a specific / unreleased version. |
| `changelog:check` | Checks the validation of a given changelog file or of all files in the "changelog/\_unreleased" folder |
| `changelog:create` | Creates a changelog markdown file in `/changelog/_unreleased` |
| `changelog:release` | Creates or updates the final changelog for a new release |

### Config

| Command | Description |
| :--- | :--- |
| `config:dump-reference` | Dumps the default configuration for an extension |

### Customer

| Command | Description |
| :--- | :--- |
| `customer:delete-unused-guests` | Deletes unused guest customers |

### Dal

| Command | Description |
| :--- | :--- |
| `dal:create:entities` | Creates the entity classes |
| `dal:create:hydrators` | Creates the hydrator classes |
| `dal:create:schema` | Creates the database schema |
| `dal:refresh:index` | Refreshes the index for a given entity |
| `dal:validate` | Validates the DAL definitions |

### Database

| Command | Description |
| :--- | :--- |
| `database:clean-personal-data` | Cleans personal data from the database |
| `database:create-migration` | Creates a new migration file |
| `database:migrate` | Executes all migrations |
| `database:migrate-destructive` | Executes all migrations |
| `database:refresh-migration` | Refreshes the migration state |

### Debug

| Command | Description |
| :--- | :--- |
| `debug:autowiring` | Lists classes/interfaces you can use for autowiring |
| `debug:business-events` | Dumps all business events |
| `debug:config` | Dumps the current configuration for an extension |
| `debug:container` | Displays current services for an application |
| `debug:event-dispatcher` | Displays configured listeners for an application |
| `debug:messenger` | Lists messages you can dispatch using the message buses |
| `debug:router` | Displays current routes for an application |
| `debug:translation` | Displays translation messages information |
| `debug:twig` | Shows a list of twig functions, filters, globals and tests |

### Es

| Command | Description |
| :--- | :--- |
| `es:admin:index` | Indexes the elasticsearch for the admin search |
| `es:admin:reset` | Reset Admin Elasticsearch indexing |
| `es:admin:test` | Allows you to test the admin search index |
| `es:create:alias` | Creates the elasticsearch alias |
| `es:index` | Reindexes all entities to elasticsearch |
| `es:index:cleanup` | Cleans outdated indices |
| `es:reset` | Resets the elasticsearch index |
| `es:status` | Shows the status of the elasticsearch index |
| `es:test:analyzer` | Allows to test an elasticsearch analyzer |

### Feature

| Command | Description |
| :--- | :--- |
| `feature:dump` | \[administration:dump:features] Creates a JSON file with feature config for JS testing and hot reloading capabilities |

### Framework

| Command | Description |
| :--- | :--- |
| `framework:demodata` | Generates demo data |
| `framework:dump:class:schema` | Dumps the schema of the given entity |
| `framework:schema` | Dumps the api definition to a json file. |

### Http

| Command | Description |
| :--- | :--- |
| `http:cache:warm:up` | Warms up the HTTP cache |

### Import

| Command | Description |
| :--- | :--- |
| `import:entity` | Imports entities from a CSV file |

### Import-export

| Command | Description |
| :--- | :--- |
| `import-export:delete-expired` | Deletes all expired import/export files |

### Lint

| Command | Description |
| :--- | :--- |
| `lint:container` | Ensures that arguments injected into services match type declarations |
| `lint:twig` | Lints a Twig template and outputs encountered errors |
| `lint:xliff` | Lints a XLIFF file and outputs encountered errors |
| `lint:yaml` | Lints a YAML file and outputs encountered errors |

### Mailer

| Command | Description |
| :--- | :--- |
| `mailer:test` | Tests Mailer transports by sending an email |

### Media

| Command                      | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
|:-----------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
| `media:delete-unused`        |  Deletes all media files that are never used. Use the `--dry-run` flag to see a paginated list of files that will be deleted, without actually deleting them. Use the `--grace-period-days=10` to set a grace period for unused media, meaning only media uploaded before the current date and time minus 10 days will be considered for deletion. The default is 20 and therefore any media uploaded in the previous 20 days will not be considered for deletion even if it is unused. Use the `--folder-entity` flag to target only a specific folder (e.g. `--folder-entity=PRODUCT` to purge all product images) |
| `media:generate-media-types` | Generates the media types for all media entities                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `media:generate-thumbnails`  | Generates the thumbnails for all media entities                                                                                                                                                                                                                                                                                                                                                                                                                                                 |

### Messenger

| Command | Description |
| :--- | :--- |
| `messenger:consume` | Consumes messages |
| `messenger:failed:remove` | Removes given messages from the failure transport |
| `messenger:failed:retry` | Retries one or more messages from the failure transport |
| `messenger:failed:show` | Shows one or more messages from the failure transport |
| `messenger:setup-transports` | Prepares the required infrastructure for the transport |
| `messenger:stats` | Shows the message count for one or more transports |
| `messenger:stop-workers` | Stops workers after their current message |

### Number-range

| Command | Description |
| :--- | :--- |
| `number-range:migrate` | Migrates the increment storage of a number range |

### Plugin

| Command | Description |
| :--- | :--- |
| `plugin:activate` | Activates given plugins |
| `plugin:create` | Creates a plugin skeleton |
| `plugin:deactivate` | Deactivates given plugins |
| `plugin:install` | Installs given plugins |
| `plugin:list` | Lists all plugins |
| `plugin:refresh` | Refreshes the plugins list in the storage from the file system |
| `plugin:uninstall` | Uninstalls given plugins |
| `plugin:update` | Updates given plugins |
| `plugin:zip-import` | Imports a plugin from a zip file |

### Product-export

| Command | Description |
| :--- | :--- |
| `product-export:generate` | Generates a product export file |

### Router

| Command | Description |
| :--- | :--- |
| `router:match` | Helps debug routes by simulating a path info match |

### S3

| Command | Description |
| :--- | :--- |
| `s3:set-visibility` | Sets the visibility of all files in the s3 filesystem to public |

### Sales-channel

| Command | Description |
| :--- | :--- |
| `sales-channel:create` | Creates a new sales channel |
| `sales-channel:create:storefront` | Creates a new storefront sales channel |
| `sales-channel:list` | Lists all sales channels |
| `sales-channel:maintenance:disable` | Disables maintenance mode for a sales channel |
| `sales-channel:maintenance:enable` | Enables maintenance mode for a sales channel |
| `sales-channel:update:domain` | Updates a sales channel domain |

### Scheduled-task

| Command | Description | Version |
| :--- | :--- | :--- |
| `scheduled-task:register` | Registers all scheduled tasks |
| `scheduled-task:run` | Runs scheduled tasks |
| `scheduled-task:run-single` | Runs single scheduled tasks | 6.5.5.0 |
| `scheduled-task:list` | Lists all scheduled tasks | 6.5.5.0 |

### Secrets

| Command | Description |
| :--- | :--- |
| `secrets:decrypt-to-local` | Decrypts all secrets and stores them in the local vault |
| `secrets:encrypt-from-local` | Encrypts all local secrets to the vault |
| `secrets:generate-keys` | Generates new encryption keys |
| `secrets:list` | Lists all secrets |
| `secrets:remove` | Removes a secret from the vault |
| `secrets:set` | Sets a secret in the vault |

### Sitemap

| Command | Description |
| :--- | :--- |
| `sitemap:generate` | Generates sitemaps for a given shop (or all active ones) |

### Snippets

| Command | Description |
| :--- | :--- |
| `snippets:validate` | Validates snippets |

### State-machine

| Command | Description |
| :--- | :--- |
| `state-machine:dump` | Dumps a state machine to a graphviz file |

### Store

| Command | Description |
| :--- | :--- |
| `store:download` | Downloads a plugin from the store |
| `store:login` | Login for the store |

### System

| Command | Description |
| :--- | :--- |
| `system:config:get` | Gets a config value |
| `system:config:set` | Sets a config value |
| `system:configure-shop` | Configures the shop |
| `system:generate-app-secret` | Generates a new app secret |
| `system:generate-jwt-secret` | Generates a new JWT secret |
| `system:install` | Installs the Shopware 6 system |
| `system:setup` | Setup the system |
| `system:update:finish` | Finishes the update process |
| `system:update:prepare` | Prepares the update process |

### Theme

| Command | Description |
| :--- | :--- |
| `theme:change` | Changes the active theme for a sales channel |
| `theme:compile` | Compiles the theme |
| `theme:create` | Creates a theme skeleton |
| `theme:dump` | Dumps the theme configuration |
| `theme:prepare-icons` | Prepares the theme icons |
| `theme:refresh` | Refreshes the theme configuration |

### User

| Command | Description |
| :--- | :--- |
| `user:change-password` | Changes the password of a user |
| `user:create` | Creates a new user |

---

---
url: /docs/concepts/commerce.md
---

# Commerce

At core, Shopware is an **ecommerce platform**. If you want to understand the commerce-related concepts of our software, make sure to go here.

::: info
The **Concepts** section does not contain code examples, instead we focus on conveying the concepts and ideas behind the software. If you want more guided, step-by-step tutorials, please head to the [Guides](../../guides/installation/) section.
:::

---

---
url: /docs/v6.5/concepts/commerce.md
---

# Commerce

At core, Shopware is an **ecommerce platform**. If you want to understand the commerce-related concepts of our software, make sure to go here.

::: info
The **Concepts** section does not contain code examples, instead we focus on conveying the concepts and ideas behind the software. If you want more guided, step-by-step tutorials, please head to the [Guides](../../guides/installation/) section.
:::

---

---
url: /docs/v6.6/concepts/commerce.md
---

# Commerce

At core, Shopware is an **ecommerce platform**. If you want to understand the commerce-related concepts of our software, make sure to go here.

::: info
The **Concepts** section does not contain code examples, instead we focus on conveying the concepts and ideas behind the software. If you want more guided, step-by-step tutorials, please head to the [Guides](../../guides/installation/) section.
:::

---

---
url: /docs/products/extensions/commercial.md
---

# Commercial

The Shopware 6 commercial feature-set comprises myriad features, the sum of which provide additional support for businesses which require extended functionality within the Shopware 6 ecosystem.

## Plugin structure

The commercial plugin is structured as a group of nested sub-bundles. [Plugins](../../../concepts/extensions/plugins-concept) concept explains you more about this.

## Setup

Installation of the commercial plugin does not require special guidance. The installation steps are detailed in our [Plugin Base Guide](../../../guides/plugins/plugins/plugin-base-guide#install-your-plugin).

This plugin contains various features, which are covered in our docs as well.

::: warning
In accordance with a Shopware merchant's active account configuration, features within the plugin will be in *active* or *inactive* (whilst still being installed within the Shopware codebase). Pay close attention to any install information or special conditions for the provided features.
:::

## Licensing

On installation, the commercial plugin tries to fetch the license key using the logged-in Shopware Account. If this can't be fetched, the plugin can be installed, but all features are deactivated. If you log into your Shopware Account, you can fetch the license key again using `bin/console commercial:license:update`.

For further debugging you can run the command:

```bash
bin/console commercial:license:info
```

which will show the current license key, whether it is set, and when it expires.

## Disable Features

::: info
This Feature is available since 6.6.10.0
:::

The commercial plugin consists of multiple features. Since you may not need all the Features included with the plugin, you can specify with the `SHOPWARE_COMMERCIAL_ENABLED_BUNDLES` environment variable all commercial bundles you want to be enabled.

Example environment variable:

```text
SHOPWARE_COMMERCIAL_ENABLED_BUNDLES=CustomPricing,Subscription
```

You can find all bundle names using this command:

```bash
./bin/console debug:container --parameter kernel.bundles --format=json
```

---

---
url: /docs/v6.5/products/plugins/commercial.md
---

# Commercial

The Shopware 6 commercial feature-set comprises myriad features, the sum of which provide additional support for businesses which require extended functionality within the Shopware 6 ecosystem.

## Plugin structure

The commercial plugin is structured as a group of nested sub-bundles. [Plugins](../../../concepts/extensions/plugins-concept) concept explains you more about this.

## Setup

Installation of the commercial plugin does not require special guidance. The installation steps are detailed in our [Plugin Base Guide](../../../guides/plugins/plugins/plugin-base-guide#install-your-plugin).

This plugin contains various feature, which are also covered in our docs as well.

::: warning
In accordance with a Shopware merchant's active account configuration, features within the plugin will be in *active* or *inactive* (whilst still being installed within the Shopware codebase). Pay close attention to any install information or special conditions for the provided features.
:::

---

---
url: /docs/v6.6/products/extensions/commercial.md
---

# Commercial

The Shopware 6 commercial feature-set comprises myriad features, the sum of which provide additional support for businesses which require extended functionality within the Shopware 6 ecosystem.

## Plugin structure

The commercial plugin is structured as a group of nested sub-bundles. [Plugins](../../../concepts/extensions/plugins-concept) concept explains you more about this.

## Setup

Installation of the commercial plugin does not require special guidance. The installation steps are detailed in our [Plugin Base Guide](../../../guides/plugins/plugins/plugin-base-guide#install-your-plugin).

This plugin contains various features, which are covered in our docs as well.

::: warning
In accordance with a Shopware merchant's active account configuration, features within the plugin will be in *active* or *inactive* (whilst still being installed within the Shopware codebase). Pay close attention to any install information or special conditions for the provided features.
:::

## Licensing

On installation, the commercial plugin tries to fetch the license key using the logged-in Shopware Account. If this can't be fetched, the plugin can be installed, but all features are deactivated. If you log into your Shopware Account, you can fetch the license key again using `bin/console commercial:license:update`.

For further debugging you can run the command:

```bash
bin/console commercial:license:info
```

which will show the current license key, whether it is set, and when it expires.

## Disable Features

::: info
This Feature is available since 6.6.10.0
:::

The commercial plugin consists of multiple features. Since you may not need all the Features included with the plugin, you can specify with the `SHOPWARE_COMMERCIAL_ENABLED_BUNDLES` environment variable all commercial bundles you want to be enabled.

Example environment variable:

```text
SHOPWARE_COMMERCIAL_ENABLED_BUNDLES=CustomPricing,Subscription
```

You can find all bundle names using this command:

```bash
./bin/console debug:container --parameter kernel.bundles --format=json
```

---

---
url: /frontends/integrations/commercial.md
---

# Commercial Integrations

Here you will find all integration documents for the commercial features of Rise, Evolve and Beyond Plans for Shopware.

* [B2B Quick-Order](b2b-quick-order.html)
* [B2B Quote-Management](b2b-quote-management.html)
* [Custom Products](custom-products.html)
* [Digital Sales Rooms](digital-sales-rooms.html)

---

---
url: /docs/guides/plugins/plugins/integrations/commercial.md
---

# Commercial Plugins

The Commercial plugin extends Shopware with advanced enterprise features available in Shopware Commercial plans.

This section documents the API-first features provided by the Commercial plugin and how to integrate them into your systems:

* [Customer-specific Pricing](./customer-specific-pricing.md)
* [Multi-Inventory](./multi-inventory.md)

---

---
url: /docs/guides/development/testing/store/store-review-errors.md
---

# Common Store Review Errors

These errors apply to all extensions submitted to the Shopware Store (plugins and apps).

## Composer and bootstrap issues

### Missing or invalid `composer.json`

Typical causes:

* `composer.json` missing.
* Technical name mismatch between Store and `composer.json`.
* Wrong `extra.shopware-plugin-class`.
* The extension archive has an incorrect ZIP structure.

Check:

* Store technical name matches the `composer.json` name.
* `extra.shopware-plugin-class` points to the correct bootstrap class.
* Namespace matches exactly (case-sensitive).
* Archive contains correct root folder structure.

Example [reference](https://github.com/FriendsOfShopware/FroshPlatformPerformance/blob/master/composer.json#L20):

**Correct**: `Swag\\MyPlugin\\SwagMyPlugin`
**Incorrect**: `Swag\\MyPlugin\\SwagMyPluginSW6`

[Extension Meta Information – Explanation of the properties](../../../plugins/plugins/plugin-base-guide.md#the-composerjson-file)

### Missing bootstrap class

Common causes include:

* Wrong ZIP structure.
* A typo.
* Case-sensitive filename mismatch.
* Namespace mismatch.

### `composer.lock` Problems

Rules:

* `composer.lock` must NOT be included in the archive.
* Lock file must match `composer.json` before packaging.
* Run `composer update` if lock is outdated.

## Dependency and version errors

### Missing Shopware packages

An example error might look like `Class Shopware\Storefront\* not found`. To fix:

* Declare required packages correctly and explicitly in `composer.json`: e.g., `"require": {"shopware/frontend": "*"}`.
* Avoid "*" version constraints. Using "*" may resolve to Early Access (EA) versions, causing review failures.
* Use proper version ranges (e.g., `~6.1.0`).
* If needed, set `"minimum-stability": "RC"`.

This example shows the correct format:

```xml
<pre>"require": {

 "shopware/core": "~6.1.0",

 "shopware/storefront": "~6.1.0"

},

"minimum-stability": "RC"</pre>
```

### Class Not Found (EA Version Issue)

In the Shopware 6 Early Access (EA) version,`Class Shopware\Core\System\Snippet\Files\SnippetFileInterface` is not found and cannot be autoloaded, causing the code review to fail.

**Cause**: Composer resolved an Early Access version due to wildcard constraints.

**Solution**: Pin versions and define minimum stability (see above).

## Code & Static Analysis Errors

### Forbidden Statements

Blocked:

* `die`
* `exit`
* `var_dump`

### Invalid method usage

You might see `Call to static method *jsonEncode() on an unknown class*`. Shopware always uses `json_encode()` exclusively; there is no fallback.

### Remove dead code

Remove out-commented code from your source code. Ensure there are no unused classes or files.

## Cross-Domain Messaging

Ensure that cross-document messages are sent to the intended domain. Unrestricted messaging will be rejected.

Link: [OWASP Web Security Testing Guide](https://github.com/OWASP/wstg/blob/master/document/4-Web_Application_Security_Testing/11-Client-side_Testing/11-Testing_Web_Messaging.md)

## Cookie and security issues

Cookies must be set securely. All non-essential cookies must be registered in the Cookie Consent Manager.

## Packaging errors and unauthorized files and folders

Extensions submitted to the Shopware Store must not contain development files, temporary artifacts, or unused resources.

* ./tests
* .DS\_Store
* .editorconfig
* .eslintrc.js
* .git
* .github
* .gitignore
* .gitkeep
* .gitlab-ci.yml
* .gitpod.Dockerfile
* .gitpod.yml
* .phar
* .php-cs-fixer.cache
* .php-cs-fixer.dist.php
* .php\_cs.cache
* .php\_cs.dist
* .prettierrc
* .stylelintrc
* .stylelintrc.js
* .sw-zip-blacklist
* .tar
* .tar.gz
* .travis.yml
* .zip
* .zipignore
* ISSUE\_TEMPLATE.md
* Makefile
* Thumbs.db
* \_\_MACOSX
* auth.json
* bitbucket-pipelines.yml
* build.sh
* composer.lock
* eslint.config.js
* grumphp.yml
* package-lock.json
* package.json
* phpdoc.dist.xml
* phpstan-baseline.neon
* phpstan.neon
* phpstan.neon.dist
* phpunit.sh
* phpunit.xml.dist
* phpunitx.xml
* psalm.xml
* rector.php
* shell.nix
* stylelint.config.js
* webpack.config.js

---

---
url: /docs/v6.5/products/community-edition.md
---

# Community Edition

## Overview

The Community Edition is an open-source, basic variant of Shopware, free for everyone to use. All other Shopware offerings, such as  [PaaS](paas/) and [SaaS](saas) are based upon the Community Edition.

## Running Shopware

In general, there are several options to run Shopware, as explained in the [Installation](../guides/installation/) section. Also, find the [system requirements](../guides/installation/requirements) needed for running Shopware as a PHP application built upon Symfony.

## Platform components

The Shopware Platform itself is a Symfony application which consists of several components developed as Symfony bundles. Each of these components is mirrored to a dedicated repository and also included in the Shopware Platform mono repository. For the time being, there is the Core component, which includes the framework and business logic, as well as the APIs. The [Storefront](../guides/plugins/plugins/storefront/) component is a default frontend for your Storefront built upon the Bootstrap toolkit and Twig templates. A Vue.js SPA [Administration](../concepts/framework/architecture/administration-concept) component wrapped inside a Symfony bundle is a default Administration panel for all back-office tasks and communicates via the [Admin API](../concepts/api/admin-api) with the Core component. Last but not least, the Elasticsearch component gives you the opportunity to improve the indexing of entities and also contains an adapter for the entity search.

With these components stored inside many repositories, one can also enable Shopware to be used for headless scenarios. With the help of the [Production repository](https://github.com/shopware/production), you do have the opportunity to only require the repositories you really want to have in your project through the `composer.json` file (e.g. only require `shopware/core`).

## Features

Rather than listing all features from a user perspective below, we would like to mention a few key features that are also worth looking at in a more technical way. As Shopware 6 is built with the API first approach, your first technical feature touch points might be our different APIs built in our Core component.

The **Admin API** is used to work on all Administration tasks and is connected to our Administration component (Vue.js SPA). This Admin API gives you the opportunity to interact with every single entity resource of Shopware and it also ships with another endpoint, the **Sync API**. Its main purpose is to perform bulk write and delete operations within one single request via `UPSERT/DELETE`. Further conceptual information to our Admin API can be found [here](../concepts/api/admin-api). Now that you already know our Admin API, it is also interesting to learn about our [Store API](../concepts/api/store-api), which was built for a different use case. The **Store API** should be used when developing customer-facing clients. Within these endpoints, you do have the opportunity to cover the complete customer journey - starting from a product listing, showing product information and, of course, placing an order through the checkout. Not only do our [Storefront](../guides/plugins/plugins/storefront/) components make use of these routes, but also the [Shopware PWA](pwa), which is a Vue.js client developed with our partner Vue Storefront.

Another feature worth mentioning is our CMS integration called *Shopping experiences*, which lets you build custom pages for different page types like listing, shop pages, landing pages and product detail pages. As this *Shopping Experiences* feature is also a built-in feature available through the Administration panel, you can easily drag and drop predefined (and even custom) blocks to your page layout. From a technical perspective, it is also important to know that this translatable content is stored in a generic way and is also available throughout the Store API. There is also a [conceptual article](../concepts/commerce/content/shopping-experiences-cms.md) covering this topic more specifically.

Shopware also has a custom built-in **ORM**, called [Data Abstraction Layer](../concepts/framework/data-abstraction-layer), which offers several features, like e.g., API endpoint generation for your entities. Our rule engine, called [Rule builder](../concepts/framework/rules), is a big feature that lets you create global rules with several conditions, which can be used and applied in several modules to e.g. configure the availability of promotion codes, shipping methods, payment methods or even product prices.

Last but not least, there is a most important technical feature, which gives you the power to create your custom ideas without touching the Shopware core. Every single feature above can be extended and customized with the help of **Extensions**. Throughout this [Extension system](../concepts/extensions/) one is able to create own [Plugins](../concepts/extensions/plugins-concept), [Themes](../guides/plugins/themes/), or even [Apps](../concepts/extensions/apps-concept), for your Shopware project.

## Repository structure

Shopware 6 consists of multiple repositories bundled inside a [Mono repository](https://www.atlassian.com/git/tutorials/monorepos) called [shopware/shopware](https://github.com/shopware/shopware). This is where the Shopware core is developed. You need it as a dependency in your projects and this is where you can participate in the development of Shopware through pull requests. It is split into multiple repositories for production setups. All of them are read-only and include Core, Storefront, Administration, and Elasticsearch. Besides that, there is also a `Recovery` directory, which provides the opportunity to interactively update, install and maintain Shopware throughout the browser. To start developing with Shopware 6, refer to the [Installation](../guides/installation/) section for an overview of the supported development environments.

::: info
This video is part of our online training, the [Backend Development](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma) available on Shopware Academy for **free**.
:::

## Contribution

Shopware 6 is a community-driven platform with a lot of contributions, and we really appreciate your support. To ensure the quality of our code, our products and our documentation, we have created a small guideline for contributing [Code](../resources/guidelines/code/contribution) and contributing to the [Docs](../resources/guidelines/documentation-guidelines/) we all should endorse to. It helps you and us to collaborate with our software. Following these guidelines will help us to integrate your changes in our daily workflow.

---

---
url: /docs/v6.6/products/community-edition.md
---

# Community Edition

## Overview

The Community Edition is an open-source, basic variant of Shopware, free for everyone to use. All other Shopware offerings, such as  [PaaS](paas/) and [SaaS](saas) are based upon the Community Edition.

## Running Shopware

In general, there are several options to run Shopware, as explained in the [Installation](../guides/installation/) section. Also, find the [system requirements](../guides/installation/requirements) needed for running Shopware as a PHP application built upon Symfony.

## Platform components

The Shopware Platform itself is a Symfony application which consists of several components developed as Symfony bundles. Each of these components is mirrored to a dedicated repository and also included in the Shopware Platform mono repository. For the time being, there is the Core component, which includes the framework and business logic, as well as the APIs. The [Storefront](../guides/plugins/plugins/storefront/) component is a default frontend for your Storefront built upon the Bootstrap toolkit and Twig templates. A Vue.js SPA [Administration](../concepts/framework/architecture/administration-concept) component wrapped inside a Symfony bundle is a default Administration panel for all back-office tasks and communicates via the [Admin API](../concepts/api/admin-api) with the Core component. Last but not least, the Elasticsearch component gives you the opportunity to improve the indexing of entities and also contains an adapter for the entity search.

With these components stored inside many repositories, one can also enable Shopware to be used for headless scenarios. With the help of the [Production repository](https://github.com/shopware/production), you do have the opportunity to only require the repositories you really want to have in your project through the `composer.json` file (e.g. only require `shopware/core`).

## Features

Rather than listing all features from a user perspective below, we would like to mention a few key features that are also worth looking at in a more technical way. As Shopware 6 is built with the API first approach, your first technical feature touch points might be our different APIs built in our Core component.

The **Admin API** is used to work on all Administration tasks and is connected to our Administration component (Vue.js SPA). This Admin API gives you the opportunity to interact with every single entity resource of Shopware and it also ships with another endpoint, the **Sync API**. Its main purpose is to perform bulk write and delete operations within one single request via `UPSERT/DELETE`. Further conceptual information to our Admin API can be found [here](../concepts/api/admin-api). Now that you already know our Admin API, it is also interesting to learn about our [Store API](../concepts/api/store-api), which was built for a different use case. The **Store API** should be used when developing customer-facing clients. Within these endpoints, you do have the opportunity to cover the complete customer journey - starting from a product listing, showing product information and, of course, placing an order through the checkout. Not only our [Storefront](../guides/plugins/plugins/storefront/) components use these routes, but also [Composable Frontends](/../../frontends), which offer platform-independent packages to build your own custom frontend with Vue, React or something else.

Another feature worth mentioning is our CMS integration called *Shopping experiences*, which lets you build custom pages for different page types like listing, shop pages, landing pages and product detail pages. As this *Shopping Experiences* feature is also a built-in feature available through the Administration panel, you can easily drag and drop predefined (and even custom) blocks to your page layout. From a technical perspective, it is also important to know that this translatable content is stored in a generic way and is also available throughout the Store API. There is also a [conceptual article](../concepts/commerce/content/shopping-experiences-cms.md) covering this topic more specifically.

Shopware also has a custom built-in **ORM**, called [Data Abstraction Layer](../concepts/framework/data-abstraction-layer), which offers several features, like e.g., API endpoint generation for your entities. Our rule engine, called [Rule builder](../concepts/framework/rules), is a big feature that lets you create global rules with several conditions, which can be used and applied in several modules to e.g. configure the availability of promotion codes, shipping methods, payment methods or even product prices.

Last but not least, there is a most important technical feature, which gives you the power to create your custom ideas without touching the Shopware core. Every single feature above can be extended and customized with the help of **Extensions**. Throughout this [Extension system](../concepts/extensions/) one is able to create own [Plugins](../concepts/extensions/plugins-concept), [Themes](../guides/plugins/themes/), or even [Apps](../concepts/extensions/apps-concept), for your Shopware project.

## Repository structure

Shopware 6 consists of multiple repositories bundled inside a [Mono repository](https://www.atlassian.com/git/tutorials/monorepos) called [shopware/shopware](https://github.com/shopware/shopware). This is where the Shopware core is developed. You need it as a dependency in your projects and this is where you can participate in the development of Shopware through pull requests. It is split into multiple repositories for production setups. All of them are read-only and include Core, Storefront, Administration, and Elasticsearch. Besides that, there is also a `Recovery` directory, which provides the opportunity to interactively update, install and maintain Shopware throughout the browser. To start developing with Shopware 6, refer to the [Installation](../guides/installation/) section for an overview of the supported development environments.

::: info
This video is part of our online training, the [Backend Development](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma) available on Shopware Academy for **free**.
:::

## Contribution

Shopware 6 is a community-driven platform with a lot of contributions, and we really appreciate your support. To ensure the quality of our code, our products and our documentation, we have created a small guideline for contributing [Code](../resources/guidelines/code/contribution) and contributing to the [Docs](../resources/guidelines/documentation-guidelines/) we all should endorse to. It helps you and us to collaborate with our software. Following these guidelines will help us to integrate your changes in our daily workflow.

---

---
url: /docs/v6.5/guides/installation/community.md
---

# Community Setup

The community setup is the recommended installation procedure for the latest versions of Shopware. It is a streamlined installation process, providing an intuitive interface for users to set up their Shopware store via Dockware.

---

---
url: /docs/products/extensions/b2b-suite/guides/storefront/company.md
---

# Company

The company component acts as a container for role related entities by providing a minimalistic interface to the different components. This ensures shared functionality. The following graph shows components that are managed in this component:

![image](../../../../../assets/b2bSuite-storefront-companyComponents.svg)

| Icon                                      |Description|
|---------------------------------------------|------------|
|  | Represents component |
|  | Represent context objects that contain the component specific information |
|  | Represents child components |

## Context

A shared context for entity creation and update is provided via the `AclGrantContext` concept. Therefore the components do not have to depend on roles directly but rather on the company context.

## Create entity

To create a new entity (managed in the company component), you have to pass the parameter `grantContext` with an identifier of an `AclGrantContext`. The newly created entity is automatically assigned to the passed role.

## Company filter

The `CompanyFilterStruct` is used by the company module to filter and search for entities. It extends the `SearchStruct` by the `companyFilterType` and `aclGrantContext`. The correct filter type can be applied by the `CompanyFilterHelper`. Possible filter types are in the list below:

| Filter name   |                        What it applies                         |
|:---------------:|:--------------------------------------------------------------:|
| acl           |  Shows only entities which are visible to this `grantContext`  |
| assignment    |      Shows only entities assigned to this `grantContext`       |
| inheritance   | Shows only entities which are visible to this or inherited `grantContext`s                          |

---

---
url: /docs/v6.5/products/extensions/b2b-suite/guides/storefront/company.md
---

# Company

The company component acts as a container for role related entities by providing a minimalistic interface to the different components. This ensures shared functionality. The following graph shows components that are managed in this component:

![image](../../../../../assets/b2bSuite-storefront-companyComponents.svg)

| Icon                                      |Description|
|---------------------------------------------|------------|
|  | Represents component |
|  | Represent context objects that contain the component specific information |
|  | Represents child components |

## Context

A shared context for entity creation and update is provided via the `AclGrantContext` concept. Therefore the components do not have to depend on roles directly but rather on the company context.

## Create entity

To create a new entity (managed in the company component), you have to pass the parameter `grantContext` with an identifier of an `AclGrantContext`. The newly created entity is automatically assigned to the passed role.

## Company filter

The `CompanyFilterStruct` is used by the company module to filter and search for entities. It extends the `SearchStruct` by the `companyFilterType` and `aclGrantContext`. The correct filter type can be applied by the `CompanyFilterHelper`. Possible filter types are in the list below:

| Filter name   |                        What it applies                         |
|:---------------:|:--------------------------------------------------------------:|
| acl           |  Shows only entities which are visible to this `grantContext`  |
| assignment    |      Shows only entities assigned to this `grantContext`       |
| inheritance   | Shows only entities which are visible to this or inherited `grantContext`s                          |

---

---
url: /docs/v6.6/products/extensions/b2b-suite/guides/storefront/company.md
---

# Company

The company component acts as a container for role related entities by providing a minimalistic interface to the different components. This ensures shared functionality. The following graph shows components that are managed in this component:

![image](../../../../../assets/b2bSuite-storefront-companyComponents.svg)

| Icon                                      |Description|
|---------------------------------------------|------------|
|  | Represents component |
|  | Represent context objects that contain the component specific information |
|  | Represents child components |

## Context

A shared context for entity creation and update is provided via the `AclGrantContext` concept. Therefore the components do not have to depend on roles directly but rather on the company context.

## Create entity

To create a new entity (managed in the company component), you have to pass the parameter `grantContext` with an identifier of an `AclGrantContext`. The newly created entity is automatically assigned to the passed role.

## Company filter

The `CompanyFilterStruct` is used by the company module to filter and search for entities. It extends the `SearchStruct` by the `companyFilterType` and `aclGrantContext`. The correct filter type can be applied by the `CompanyFilterHelper`. Possible filter types are in the list below:

| Filter name   |                        What it applies                         |
|:---------------:|:--------------------------------------------------------------:|
| acl           |  Shows only entities which are visible to this `grantContext`  |
| assignment    |      Shows only entities assigned to this `grantContext`       |
| inheritance   | Shows only entities which are visible to this or inherited `grantContext`s                          |

---

---
url: /docs/products/extensions/b2b-suite/guides/storefront/complex-views.md
---

# Complex Views

The B2B Suite comes with a whole UI providing Administration like features in the frontend. The structure is reflected in the naming of the several controller classes. Each controller then uses a canonical naming scheme. The example below shows the *ContactController* with all its assignment controllers.

![image](../../../../../assets/b2bSuite-storefront-controller-structure.svg)

As you can see, every controller is associated with one specific component.

## Controller structure

The controller naming is very straightforward. It always looks like this:

```
B2bContact - contact listing
├── B2bContactRole - role <-> contact assignment
├── B2bContactAddress - address <-> contact assignment
├── B2bContactContingent - contingent <-> contact assignment
├── B2bContactRoute - route <-> contact assignment
```

We distinguish here between *root controller* and *sub-controller*. A root controller does not require parameters to be passed. It provides a basic page layout and CRUD actions on a single entity. Contrary, a sub-controller depends on a context (usually a selected id) from requests and provides auxiliary actions, like assignments, in this context.

## Root controller

The root controller usually looks like this:

```php
<?php declare(strict_types=1);

namespace My\Namespace;

class RootController
{
    /**
    * Provides the page layout and displays a listing containing the entities
    */
    public function indexAction() { [...] }
    
    /**
    * Display an empty form or optionally errors and the invalid entries
    */
    public function newAction() { [...] }

    /**
    * Post only!
    *
    * Store new entity. If invalid input, forward to `newAction`. If successful, forward to `detailAction`.
    */
    public function createAction() { [...] }

    /**
    * Provides a detailed layout. Usually a modal box containing a navigation and initially selecting the `editAction`.
    *
    */
    public function detailAction() { [...] }

    /**
    * Display the Form containing all stored data.
    */
    public function editAction() { [...] }

    /**
     * Post only!
     *
     * Store updates to the entity, forwards to `editAction`.
     */
    public function updateAction() { [...] }

    /**
     * Post only!
     *
     * Removes a record, forwards to `indexAction`.
     */
     public function removeAction() { [...] }
}
```

As you can see, there are a few `POST` only actions. These are solely for data processing and do not have a view of their own. This decision was made to provide small and simple to understand methods, easing the handling for extension developers. So actually, there are fewer views than actions:

```
├── index.html.twig - the listing grid
├── detail.html.twig - the modal dialog layout with navigation and extends modal.html.twig
├── edit.html.twig - edit an existing entity and extends modal.html.twig
├── _edit.html.twig - extends modal-content.html.twig
├── new.html.twig - extends modal.html.twig
├── _new.html.twig - extends modal-content.html.twig
├── _form.html.twig - the internal usage only form for edit and new
```

## Sub-controller

The sub-controller depends on parameters to get the context it should act on. A typical assignment controller looks like this:

```php
<?php declare(strict_types=1);

namespace My\Namespace;

class SubController
{
    /**
     * Provides the layout for the controller and contains the listing
     */
    public function indexAction() { [...] }

    /**
     * Post only!
     *
     * Assign two id's to each other
     */
    public function assignAction() { [...] }
}
```

Since `POST` only actions never have views, these controllers only have one view:

```
├── index.html.twig - contains entity listing
```

## Modal component

You can find more information about the modal component in this article: [B2B Suite Modal Component](modal-component)

---

---
url: /docs/v6.5/products/extensions/b2b-suite/guides/storefront/complex-views.md
---

# Complex Views

The B2B Suite comes with a whole UI providing Administration like features in the frontend. The structure is reflected in the naming of the several controller classes. Each controller then uses a canonical naming scheme. The example below shows the *ContactController* with all its assignment controllers.

![image](../../../../../assets/b2bSuite-storefront-controller-structure.svg)

As you can see, every controller is associated with one specific component.

## Controller structure

The controller naming is very straightforward. It always looks like this:

```
B2bContact - contact listing
├── B2bContactRole - role <-> contact assignment
├── B2bContactAddress - address <-> contact assignment
├── B2bContactContingent - contingent <-> contact assignment
├── B2bContactRoute - route <-> contact assignment
```

We distinguish here between *root controller* and *sub-controller*. A root controller does not require parameters to be passed. It provides a basic page layout and CRUD actions on a single entity. Contrary, a sub-controller depends on a context (usually a selected id) from requests and provides auxiliary actions, like assignments, in this context.

## Root controller

The root controller usually looks like this:

```php
<?php declare(strict_types=1);

namespace My\Namespace;

class RootController
{
    /**
    * Provides the page layout and displays a listing containing the entities
    */
    public function indexAction() { [...] }
    
    /**
    * Display an empty form or optionally errors and the invalid entries
    */
    public function newAction() { [...] }

    /**
    * Post only!
    *
    * Store new entity. If invalid input, forward to `newAction`. If successful, forward to `detailAction`.
    */
    public function createAction() { [...] }

    /**
    * Provides a detailed layout. Usually a modal box containing a navigation and initially selecting the `editAction`.
    *
    */
    public function detailAction() { [...] }

    /**
    * Display the Form containing all stored data.
    */
    public function editAction() { [...] }

    /**
     * Post only!
     *
     * Store updates to the entity, forwards to `editAction`.
     */
    public function updateAction() { [...] }

    /**
     * Post only!
     *
     * Removes a record, forwards to `indexAction`.
     */
     public function removeAction() { [...] }
}
```

As you can see, there are a few `POST` only actions. These are solely for data processing and do not have a view of their own. This decision was made to provide small and simple to understand methods, easing the handling for extension developers. So actually, there are fewer views than actions:

```
├── index.html.twig - the listing grid
├── detail.html.twig - the modal dialog layout with navigation and extends modal.html.twig
├── edit.html.twig - edit an existing entity and extends modal.html.twig
├── _edit.html.twig - extends modal-content.html.twig
├── new.html.twig - extends modal.html.twig
├── _new.html.twig - extends modal-content.html.twig
├── _form.html.twig - the internal usage only form for edit and new
```

## Sub-controller

The sub-controller depends on parameters to get the context it should act on. A typical assignment controller looks like this:

```php
<?php declare(strict_types=1);

namespace My\Namespace;

class SubController
{
    /**
     * Provides the layout for the controller and contains the listing
     */
    public function indexAction() { [...] }

    /**
     * Post only!
     *
     * Assign two id's to each other
     */
    public function assignAction() { [...] }
}
```

Since `POST` only actions never have views, these controllers only have one view:

```
├── index.html.twig - contains entity listing
```

## Modal component

You can find more information about the modal component in this article: [B2B Suite Modal Component](modal-component)

---

---
url: /docs/v6.6/products/extensions/b2b-suite/guides/storefront/complex-views.md
---

# Complex Views

The B2B Suite comes with a whole UI providing Administration like features in the frontend. The structure is reflected in the naming of the several controller classes. Each controller then uses a canonical naming scheme. The example below shows the *ContactController* with all its assignment controllers.

![image](../../../../../assets/b2bSuite-storefront-controller-structure.svg)

As you can see, every controller is associated with one specific component.

## Controller structure

The controller naming is very straightforward. It always looks like this:

```
B2bContact - contact listing
├── B2bContactRole - role <-> contact assignment
├── B2bContactAddress - address <-> contact assignment
├── B2bContactContingent - contingent <-> contact assignment
├── B2bContactRoute - route <-> contact assignment
```

We distinguish here between *root controller* and *sub-controller*. A root controller does not require parameters to be passed. It provides a basic page layout and CRUD actions on a single entity. Contrary, a sub-controller depends on a context (usually a selected id) from requests and provides auxiliary actions, like assignments, in this context.

## Root controller

The root controller usually looks like this:

```php
<?php declare(strict_types=1);

namespace My\Namespace;

class RootController
{
    /**
    * Provides the page layout and displays a listing containing the entities
    */
    public function indexAction() { [...] }
    
    /**
    * Display an empty form or optionally errors and the invalid entries
    */
    public function newAction() { [...] }

    /**
    * Post only!
    *
    * Store new entity. If invalid input, forward to `newAction`. If successful, forward to `detailAction`.
    */
    public function createAction() { [...] }

    /**
    * Provides a detailed layout. Usually a modal box containing a navigation and initially selecting the `editAction`.
    *
    */
    public function detailAction() { [...] }

    /**
    * Display the Form containing all stored data.
    */
    public function editAction() { [...] }

    /**
     * Post only!
     *
     * Store updates to the entity, forwards to `editAction`.
     */
    public function updateAction() { [...] }

    /**
     * Post only!
     *
     * Removes a record, forwards to `indexAction`.
     */
     public function removeAction() { [...] }
}
```

As you can see, there are a few `POST` only actions. These are solely for data processing and do not have a view of their own. This decision was made to provide small and simple to understand methods, easing the handling for extension developers. So actually, there are fewer views than actions:

```
├── index.html.twig - the listing grid
├── detail.html.twig - the modal dialog layout with navigation and extends modal.html.twig
├── edit.html.twig - edit an existing entity and extends modal.html.twig
├── _edit.html.twig - extends modal-content.html.twig
├── new.html.twig - extends modal.html.twig
├── _new.html.twig - extends modal-content.html.twig
├── _form.html.twig - the internal usage only form for edit and new
```

## Sub-controller

The sub-controller depends on parameters to get the context it should act on. A typical assignment controller looks like this:

```php
<?php declare(strict_types=1);

namespace My\Namespace;

class SubController
{
    /**
     * Provides the layout for the controller and contains the listing
     */
    public function indexAction() { [...] }

    /**
     * Post only!
     *
     * Assign two id's to each other
     */
    public function assignAction() { [...] }
}
```

Since `POST` only actions never have views, these controllers only have one view:

```
├── index.html.twig - contains entity listing
```

## Modal component

You can find more information about the modal component in this article: [B2B Suite Modal Component](modal-component)

---

---
url: /docs/products/digital-sales-rooms/customization/component.md
---

::: warning
All customization instructions will refer to changes made within your customization layer folder.
:::

# Component Customization

In this document, we will demonstrate how to customize a component (specifically, the "Wishlist" button) in the DSR frontend template using the Nuxt layer concept. This guide will help you understand the process of extending or modifying the default components in your frontend without altering the core files.

## Understand the component structure of the default layer

Before customizing any components, it's essential to understand the structure of the default layer. Navigate to the `dsr/components` directory to view all available components.

In this case, look for the `SwWishlistButton.vue` component inside `dsr/components/shared/molecules/`.

## Create the component in the custom layer

Now, inside your custom layer, paste the copied `SwWishlistButton.vue` file. You should now have the same default component in your custom-layer directory, ready for modification.
Once you have copied the component to your custom layer, modify the part of the component that you want to change. For instance, you may want to change the style, add new functionality, or update the template.
At this point, the frontend app will ignore the `SwWishlistButton` from the default layer and only use the `SwWishlistButton` from the custom layer.

---

---
url: /docs/products/sales-agent/customization/component.md
---

::: warning
All customization instructions will refer to changes made within your customization layer folder.
:::

# Component Customization

In this document, we will demonstrate how to customize a component (e.g, the login page) in the Sales Agent frontend using the Nuxt layer concept. This guide will help you understand the process of extending or modifying the default components in your frontend without altering the core files.

## Understand the component structure of the default layer

Before customizing any components, it's essential to understand the structure of the default layer. Navigate to the `~/layers/sales-agent` directory to view all available components.

In this case, look for the `login.vue` component inside `sales-agent/pages/auth`.

## Create the component in the custom layer

Now, inside your custom layer, paste the copied `login.vue` file. You should now have the same default component in your custom-layer directory, ready for modification.
Once you have copied the component to your custom layer, modify the part of the component that you want to change. For instance, you may want to change the style, add new functionality, or update the template.
At this point, the frontend app will ignore the `login.vue` from the default layer and only use the `login.vue` from the custom layer.

See example in the layer `example` of source code.

---

---
url: /docs/v6.6/products/digital-sales-rooms/customization/component.md
---

::: warning
All customization instructions will refer to changes made within your customization layer folder.
:::

# Component Customization

In this document, we will demonstrate how to customize a component (specifically, the "Wishlist" button) in the DSR frontend template using the Nuxt layer concept. This guide will help you understand the process of extending or modifying the default components in your frontend without altering the core files.

## Understand the component structure of the default layer

Before customizing any components, it's essential to understand the structure of the default layer. Navigate to the `dsr/components` directory to view all available components.

In this case, look for the `SwWishlistButton.vue` component inside `dsr/components/shared/molecules/`.

## Create the component in the custom layer

Now, inside your custom layer, paste the copied `SwWishlistButton.vue` file. You should now have the same default component in your custom-layer directory, ready for modification.
Once you have copied the component to your custom layer, modify the part of the component that you want to change. For instance, you may want to change the style, add new functionality, or update the template.
At this point, the frontend app will ignore the `SwWishlistButton` from the default layer and only use the `SwWishlistButton` from the custom layer.

---

---
url: /resources/admin-extension-sdk/api-reference/ui/component-sections.md
---

# Component Sections

Component sections allow extensions to render UI components inside existing Administration views. They are typically used together with tabs or other extension points that expose a `positionId`.

See the [Component Sections concept](../../concepts/component-sections.md) for an overview.

## componentSection.add()

Add a new component to a component section.

#### Usage

```ts
import { ui } from '@shopware-ag/meteor-admin-sdk';

ui.componentSection.add({
    component: 'the-component', // Choose the component which you want to render at the component section
    positionId: 'the-position-id-of-the-component-section', // Select the positionId where you want to render the component
    props: {
        ... // The properties are depending on the component
    }
})
```

#### Parameters

| Name        | Required | Default | Description                                    |
| :---------- | :------- | :------ | :--------------------------------------------- |
| `component` | true     |         | Choose the component which you want to render. |

#### Return value

Returns a promise without data.

## Available components

### Card

##### Properties

| Name         | Required | Default | Description                        |
| :----------- | :------- | :------ | :--------------------------------- |
| `title`      | false    |         | The main title of the card         |
| `subtitle`   | false    |         | The subtitle of the card           |
| `locationId` | true     |         | The locationId for the custom view |
| `tabs`       | false    |         | Render different content with tabs |

#### Example: Add a component to the product page

```js
import { ui } from "@shopware-ag/meteor-admin-sdk";

ui.componentSection.add({
  component: "card",
  positionId: "sw-product-properties__before",
  props: {
    title: "Hello from plugin",
    subtitle: "I am before the properties card",
    locationId: "my-awesome-app-card-before",
  },
});
```

![Card component example](./assets/example-card.png)

#### Example: Add tabs to the card

```js
import { ui } from "@shopware-ag/meteor-admin-sdk";

ui.componentSection.add({
  component: "card",
  positionId: "sw-product-properties__before",
  props: {
    title: "Hello from plugin",
    subtitle: "I am before the properties card",
    locationId: "my-awesome-app-card-before",
    // Render tabs and custom tab content with the provided location id
    tabs: [
      {
        name: "example-tab-1",
        label: "First tab",
        locationId: "example-tab-1",
      },
      {
        name: "example-tab-2",
        label: "Second tab",
        locationId: "example-tab-2",
      },
    ],
  },
});
```

To render the tabs introduced in this example, add matching entry points in your extension code using the `locationId` values that you freely chose when registering the component section. Read more about this pattern in [Locations](../../concepts/locations.md).

```js
import { location } from "@shopware-ag/meteor-admin-sdk";

if (location.is("example-tab-1")) {
  document.body.innerHTML = "<h1>First tab content</h1>";
}

if (location.is("example-tab-2")) {
  document.body.innerHTML = "<h1>Second tab content</h1>";
}
```

![Card component with tabs example](./assets/example-card-with-tabs.png)

---

---
url: /resources/admin-extension-sdk/concepts/component-sections.md
---

# Component Sections

Component sections allow extensions to render custom UI components inside predefined extension points in the Shopware Administration.

Unlike other extension APIs that modify existing UI elements (such as tabs or buttons), component sections allow extensions to inject full components into specific UI positions.

Component sections are prebuilt (like cards) and usually work together with:

* [Positions](./positions.md): identify where UI can be injected
* [Locations](./locations.md): determine where extension content should render

## Example

This example adds a card with custom content before the properties card on the manufacturer detail page:

```js
import { ui, location } from '@shopware-ag/meteor-admin-sdk';

if (location.is(location.MAIN_HIDDEN)) {
    ui.componentSection.add({
        positionId: 'sw-manufacturer-card-custom-fields__before',
        component: 'card', 
        props: {
            title: 'Hello from plugin',
            subtitle: 'I am before the properties card',
            locationId: 'my-app-card-before-properties'
        }
  })
}

if (location.is('my-app-card-before-properties')) {
    document.body.innerHTML = '<h1>Hello World before</h1>';
}
```

![Component Sections screenshot example](./assets/component-sections-example.png)

For the full API reference including available components, card properties, and tab support, see the [Component Sections API reference](../api-reference/ui/component-sections.md).

---

---
url: /docs/products/paas/shopware/composable-frontends.md
---

# Composable Frontends

Composable frontends can be deployed on Shopware PaaS Native in a similar way to Shopware applications.
They use the same project and application lifecycle, the same deployment commands, and the same environment variable and Vault secret handling.

Use this page for the configuration that is specific to composable frontends.
For the general platform workflow, see [Applications](../fundamentals/applications.md), [Application YAML Configuration](../fundamentals/application-yaml.md), and the [Quickstart](../get-started/quickstart.md).

## Prerequisites

Before deploying a composable frontend, make sure you have:

* A Git repository that contains your composable frontend source code
* Access to Shopware PaaS Native and the [`sw-paas` CLI](../get-started/cli.md)
* A project that is connected to your Git repository
* An `application.yaml` file in the root of your repository

If you have not connected a repository yet, follow the repository setup steps in the [Quickstart](../get-started/quickstart.md).

## Application YAML

Composable frontends require an `application.yaml` file in the root of the repository.
The main difference compared to a Shopware application is the application kind and the Node.js runtime configuration.

A minimal configuration looks like this:

```yaml
kind: cfe

app:
  node:
    version: "24"
```

The supported Node.js versions are:

* `22`
* `24`
* `26`

Choose the version that matches the runtime requirements of your frontend project and commit the `application.yaml` to your repository.

## Runtime requirements

Composable frontend applications must listen on port `3000`.

They must also expose a health endpoint at `/api/healthz`.
Shopware PaaS Native uses this endpoint for liveness and readiness checks.
The endpoint should return a successful response when the application is ready to receive traffic.

The container filesystem is read-only for security reasons.
If your application needs to write temporary files at runtime, write them to `/app/tmp`.

## Custom Dockerfile

If the default Shopware PaaS Native build does not fit your composable frontend, you can provide your own Dockerfile.

Configure the custom Dockerfile in `application.yaml`:

```yaml
apiVersion: v1
kind: cfe

app:
  build:
    dockerfile_path: Dockerfile
  node:
    version: "24"
```

When you use a custom Dockerfile, follow these additional requirements:

* Run the container as a non-root user with `UID` and `GID` set to `1000`
* Keep packages up to date
* Use an entrypoint that starts the server directly
* Follow general security and performance best practices

Shopware PaaS Native still handles the build and deployment workflow for the application.

## Environment variables

Composable frontends use the same environment variable configuration as Shopware applications.
You can define non-sensitive values in `application.yaml`:

```yaml
kind: cfe

app:
  node:
    version: "24"
  environment_variables:
    - name: FOO
      value: BAR
      scope: RUN
```

Use `RUN` for variables that must be available when the frontend runs.
Use `BUILD` for variables that are only needed during the build step.

For sensitive values such as API tokens, use [Vault secrets](../fundamentals/secrets.md) instead of committing them to `application.yaml`.
Secrets are handled in the same way as for Shopware applications:

* `env` secrets are available at runtime
* `buildenv` secrets are available during builds

For the full precedence rules and configuration details, see [Environment variables](../fundamentals/environment-variables.md).

## Deployment

Composable frontends use the same deployment workflow as Shopware applications.
By default, Shopware builds the container image for you with the managed PaaS build system.
If you configure a custom Dockerfile in `application.yaml`, the PaaS build system uses that Dockerfile to build the deployed image.

After changing the frontend source code or the `application.yaml`, update the application with:

```sh
sw-paas application update
```

To create and deploy a specific build, use:

```sh
sw-paas application deploy create
```

You can monitor the deployment with:

```sh
sw-paas watch
```

Build logs and runtime logs are available through the same commands documented for Shopware applications:

```sh
sw-paas application build logs
sw-paas application logs
```

For more details about builds, deployments and logs, see [Applications](../fundamentals/applications.md) and [Logs](../monitoring/logs.md).

## Fastly

Fastly is configured automatically for composable frontends.
This includes common edge behavior such as redirecting HTTP traffic to HTTPS.
After each deployment, Shopware PaaS Native performs a full cache purge.

If you only want to purge the Fastly cache, create a new deployment without updating the application commit SHA:

```sh
sw-paas application deploy create
```

This redeploys the application using the same application build and runs the CDN purge action.

## Caching and ISR

Shopware PaaS Native supports and encourages Incremental Static Regeneration (ISR) for composable frontends.
To cache a page at the CDN level, configure your frontend to send the following response header:

```http
Surrogate-Control: max-age=86400, stale-while-revalidate=86400
```

For routes that must not be cached, configure your frontend to send:

```http
Cache-Control: no-cache, no-store, must-revalidate
Surrogate-Control: no-store
```

For Nuxt projects, configure these headers with `routeRules` in `nuxt.config.ts`:

```ts
export default defineNuxtConfig({
  routeRules: {
    "/": {
      isr: 60 * 60 * 24,
      headers: {
        "Surrogate-Control": "max-age=86400, stale-while-revalidate=86400",
      },
    },
    "/account/**": {
      headers: {
        "Cache-Control": "no-cache, no-store, must-revalidate",
        "Surrogate-Control": "no-store",
      },
    },
  },
});
```

For more details about the CDN setup, see [CDN](../cdn/index.md).

---

---
url: /docs/products/paas/shopware-paas/composable-frontends/performance.md
---

# Composable-Frontends Performance

## Shopware Backend caching

The current versions of Shopware rely heavily on `POST` requests for `/store-api/`.\
`POST` requests are by design not cacheable, so Fastly simply passes them to the backend cluster without even trying to cache them.

A temporary [plugin](https://github.com/shopwareLabs/SwagStoreApiCache) has been developed.  With this workaround, Fastly can cache some of the `/store-api/` `POST` requests.

This plugin includes new Fastly snippets that must be used instead of the usual ones.

The plugin includes [a few routes](https://github.com/shopwareLabs/SwagStoreApiCache/blob/trunk/src/Listener/StoreAPIResponseListener.php#L57) which will become automatically cacheable.

If you need to cache additional routes, it can be done via the admin config: `SwagStoreAPICache.config.additionalCacheableRoutes`.

As usual, ensure [soft-purges](https://developer.shopware.com/docs/guides/hosting/infrastructure/reverse-http-cache.html#fastly-soft-purge) are enabled.

Please note that we're actively working on moving the `store-api` requests from `POST` to `GET` to make them cacheable, so the use of this plugin would no longer be required.\
More details in the [Epic](https://github.com/shopware/shopware/issues/7783).

## Composable Frontend caching

To get the best performance, Frontend caching must be enabled.

There are a few steps to get there:

1. Configure a Fastly service on top of each Frontend. It can be one Fastly service per Frontend, or it can be a single Fastly service with multiple domains and hosts configured.

2. Update `nuxt.config.ts` so `routesRules`, using Incremental Static Regeneration (`ISR`), have the required cache headers.
   Example:

```ts
'/': {
      		isr: 60 * 60 * 24,
      		headers: {
        		'cache-control': 'public, s-maxage=3600, stale-while-revalidate=1800'
      		}
    	},
'/**': {
      		isr: 60 * 60 * 24,
      		headers: {
        		'cache-control': 'public, s-maxage=3600, stale-while-revalidate=1800'
      		}
    	},
```

`s-maxage` and `stale-while-revalidate` can be adjusted.\
`s-maxage` represents how long in seconds the content will be cached on Fastly.\
`stale-while-revalidate` represents how long a stale page (aka an expired page) can be kept and served, so when a client requests this page, the stale object is served while a request to update it is done in the background, so the next client will have an updated version of the page.

::: Note

The cache invalidation process is only on the Fastly Backend service.
The Shopware instance is not "aware" of the Frontend instance. It cannot trigger cache invalidation. Items will remain in cache for the `s-maxage` duration.

:::

## Get rid of the OPTIONS requests (CORS)

When using a different domain for backend requests, browsers are forced to send `OPTIONS` requests. Those requests, also named `preflight` requests, are due to `CORS` checks. Every time the browser needs to send a request to the backend, it must first confirm it's authorized to do so.

`OPTIONS` requests are by default not cacheable as the responses may vary depending on the request's headers.
There is a possibility to include an `Access-Control-Max-Age` header in the `OPTIONS` responses, so it forces the browser to cache the answer for a longer period than the default 5 seconds.

But the recommended action is to remove those `CORS` checks completely.
To do so, all the requests to the Shopware backend must be sent on the same domain as the Frontend, so the browser only sees one single domain.

For this, the Frontend Fastly service can be configured to serve both the Frontend and the Backend requests.

The config is pretty simple. With the additional host, the logic is only four lines of code:

```vcl
if (req.url.path ~ "^/store-api/") { 
  set req.http.host = "backend.mydomain.com"; 
  set req.backend = F_Backend__Shopware_instance_; 
  return (pass);
}
```

The `return (pass)` is very important. We must not add a cache layer on the Frontend Fastly service to avoid invalidation issues. The Backend Fastly service remains the one responsible for caching.

## Optimize the Fastly Backend hit-ratio

Once an item has been set into the cart, a new cookie named `sw-cache-hash` is sent.
The default VCL hash snippet includes the content of this cookie in the hash (aka the cache key).
It means that the first backend request that was cached will no longer be cached when requested once an item has been added to the cart.

If rules based pricing is not used in the Shopware instance, the following section can be commented out in the VCL hash snippet:

```vcl
# Consider Shopware http cache cookies
#if (req.http.cookie:sw-cache-hash) {
#	set req.hash += req.http.cookie:sw-cache-hash;
#} elseif (req.http.cookie:sw-currency) {
#	set req.hash += req.http.cookie:sw-currency;
#}
```

## Check the results using the Developer Tools

Once everything is configured, check for the `Age` header to confirm the responses are cached.

---

---
url: /frontends/concepts/composables.md
---

# Composables

The section on composables describes context composables, shared composables and how to overwrite composables.

---

---
url: /docs/resources/references/core-reference/composer-commands-reference.md
---

# Composer Commands Reference

::: info
These commands are only available inside `shopware/shopware` GitHub repository, so when you contribute to Shopware. For regular projects, use `./bin/*.sh` scripts.
:::

These composer commands can be executed using composer with your Shopware project.

```bash
$ composer [command] [parameters]
```

## Commands

### Setup & build

| Command                      | Description                                                                                                                   |
|------------------------------|-------------------------------------------------------------------------------------------------------------------------------|
| `setup`                      | Resets and re-installs this Shopware instance - Database will be purged!                                                      |
| `build:js`                   | Builds Administration & Storefront - Combination of `build:js:admin` & `build:js:storefront`                                  |
| `build:js:admin`             | Builds the Administration - Includes `bundle:dump`, `feature:dump`, `admin:generate-entity-schema-types` and `assets:install` |
| `build:js:component-library` | Builds the component library                                                                                                  |
| `watch:admin`                | Build administration with hot module reloading                                                                                |
| `build:js:storefront`        | Builds the Storefront's JavaScript - Includes `bundle:dump`, `feature:dump` and `theme:compile`                               |
| `check:license`              | Check third-party dependency licenses for composer dependencies                                                               |
| `reset`                      | Resets this Shopware instance, without composer and npm install. (Faster reset if no dependencies changed)                    |

### Administration

| Command                              | Description                                                                   |
|:-------------------------------------|:------------------------------------------------------------------------------|
| `admin:create:test`                  | Generate a test boilerplate                                                   |
| `admin:generate-entity-schema-types` | Convert entity schemas to data types                                          |
| `admin:unit`                         | Launches the jest unit test-suite for the Admin                               |
| `admin:unit:watch`                   | Launches the interactive jest unit test-suite watcher for the Admin           |
| `admin:unit:prepare-vue3`            | Prepares the jest unit test-suite for the Admin with Vue3                     |
| `admin:unit:vue3`                    | Launches the jest unit test-suite for the Admin with Vue3                     |
| `admin:unit:watch:vue3`              | Launches the interactive jest unit test-suite watcher for the Admin with Vue3 |
| `npm:admin:check-license`            | Check third-party dependency licenses for administration                      |
| `watch:admin`                        | Build administration with hot module reloading                                |

### Storefront

| Command                        | Description                                                                                     |
|:-------------------------------|:------------------------------------------------------------------------------------------------|
| `build:js:storefront`          | Builds the Storefront's JavaScript - Includes `bundle:dump`, `feature:dump` and `theme:compile` |
| `npm:storefront:check-license` | Check third-party dependency licenses for storefront                                            |
| `watch:storefront`             | Build storefront with hot module reloading                                                      |

### Testsuite & Development

| Command                 | Description                                                                                           |
|:------------------------|:------------------------------------------------------------------------------------------------------|
| `bc-check`              | Checks for backwards compatibility breaks in the current branch                                       |
| `e2e:setup`             | Installs a clean shopware instance for E2E environment and launches `e2e:prepare`                     |
| `e2e:open`              | Launches the Cypress E2E test-suite UI                                                                |
| `e2e:prepare`           | Installs the Admin Extension SDK test plugin with fixtures and dumps the database                     |
| `ecs`                   | Checks all files regarding the Easy Coding Standard                                                   |
| `ecs-fix`               | Checks all files regarding the Easy Coding Standard and fixes them if possible                        |
| `eslint`                | Codestyle checks all (Administration/Storefront/E2E) JS/TS files                                      |
| `eslint:admin`          | Codestyle checks Administration JS/TS files                                                           |
| `eslint:admin:fix`      | Codestyle checks Administration JS/TS files and fixes them if possible                                |
| `eslint:e2e`            | Codestyle checks all E2E JS/TS files                                                                  |
| `eslint:e2e:fix`        | Codestyle checks all E2E JS/TS files and fixes them if possible                                       |
| `eslint:storefront`     | Codestyle checks all Storefront JS/TS files                                                           |
| `init:testdb`           | Initializes the test database                                                                         |
| `lint`                  | Shorthand for the composer commands `stylelint`, `eslint`, `ecs`, `lint:changlog` and `lint:snippets` |
| `lint:changelog`        | Validates changelogs                                                                                  |
| `lint:snippets`         | Validates existence of snippets in all core-supported languages                                       |
| `phpstan`               | runs the PHP static analysis tool                                                                     |
| `phpunit`               | Launches the PHP unit test-suit                                                                       |
| `phpunit:quarantined`   | Launches the PHP unit test-suite for quarantined tests                                                |
| `storefront:unit`       | Launches the jest unit test-suite for the Storefront                                                  |
| `storefront:unit:watch` | Launches the interactive jest unit test-suite watcher for the Storefront                              |

---

---
url: /docs/v6.6/resources/references/core-reference/composer-commands-reference.md
---

# Composer Commands Reference

::: info
These commands are only available inside `shopware/shopware` GitHub repository, so when you contribute to Shopware. For regular projects, use `./bin/*.sh` scripts.
:::

These composer commands can be executed using composer with your Shopware project.

```bash
$ composer [command] [parameters]
```

## Commands

### Setup & build

| Command                      | Description                                                                                                                   |
|------------------------------|-------------------------------------------------------------------------------------------------------------------------------|
| `setup`                      | Resets and re-installs this Shopware instance - Database will be purged!                                                      |
| `build:js`                   | Builds Administration & Storefront - Combination of `build:js:admin` & `build:js:storefront`                                  |
| `build:js:admin`             | Builds the Administration - Includes `bundle:dump`, `feature:dump`, `admin:generate-entity-schema-types` and `assets:install` |
| `build:js:component-library` | Builds the component library                                                                                                  |
| `watch:admin`                | Build administration with hot module reloading                                                                                |
| `build:js:storefront`        | Builds the Storefront's JavaScript - Includes `bundle:dump`, `feature:dump` and `theme:compile`                               |
| `check:license`              | Check third-party dependency licenses for composer dependencies                                                               |
| `reset`                      | Resets this Shopware instance, without composer and npm install. (Faster reset if no dependencies changed)                    |

### Administration

| Command                              | Description                                                                   |
|:-------------------------------------|:------------------------------------------------------------------------------|
| `admin:create:test`                  | Generate a test boilerplate                                                   |
| `admin:generate-entity-schema-types` | Convert entity schemas to data types                                          |
| `admin:unit`                         | Launches the jest unit test-suite for the Admin                               |
| `admin:unit:watch`                   | Launches the interactive jest unit test-suite watcher for the Admin           |
| `admin:unit:prepare-vue3`            | Prepares the jest unit test-suite for the Admin with Vue3                     |
| `admin:unit:vue3`                    | Launches the jest unit test-suite for the Admin with Vue3                     |
| `admin:unit:watch:vue3`              | Launches the interactive jest unit test-suite watcher for the Admin with Vue3 |
| `npm:admin:check-license`            | Check third-party dependency licenses for administration                      |
| `watch:admin`                        | Build administration with hot module reloading                                |

### Storefront

| Command                        | Description                                                                                     |
|:-------------------------------|:------------------------------------------------------------------------------------------------|
| `build:js:storefront`          | Builds the Storefront's JavaScript - Includes `bundle:dump`, `feature:dump` and `theme:compile` |
| `npm:storefront:check-license` | Check third-party dependency licenses for storefront                                            |
| `watch:storefront`             | Build storefront with hot module reloading                                                      |

### Testsuite & Development

| Command                 | Description                                                                                           |
|:------------------------|:------------------------------------------------------------------------------------------------------|
| `bc-check`              | Checks for backwards compatibility breaks in the current branch                                       |
| `e2e:setup`             | Installs a clean shopware instance for E2E environment and launches `e2e:prepare`                     |
| `e2e:open`              | Launches the Cypress E2E test-suite UI                                                                |
| `e2e:prepare`           | Installs the Admin Extension SDK test plugin with fixtures and dumps the database                     |
| `ecs`                   | Checks all files regarding the Easy Coding Standard                                                   |
| `ecs-fix`               | Checks all files regarding the Easy Coding Standard and fixes them if possible                        |
| `eslint`                | Codestyle checks all (Administration/Storefront/E2E) JS/TS files                                      |
| `eslint:admin`          | Codestyle checks Administration JS/TS files                                                           |
| `eslint:admin:fix`      | Codestyle checks Administration JS/TS files and fixes them if possible                                |
| `eslint:e2e`            | Codestyle checks all E2E JS/TS files                                                                  |
| `eslint:e2e:fix`        | Codestyle checks all E2E JS/TS files and fixes them if possible                                       |
| `eslint:storefront`     | Codestyle checks all Storefront JS/TS files                                                           |
| `init:testdb`           | Initializes the test database                                                                         |
| `lint`                  | Shorthand for the composer commands `stylelint`, `eslint`, `ecs`, `lint:changlog` and `lint:snippets` |
| `lint:changelog`        | Validates changelogs                                                                                  |
| `lint:snippets`         | Validates existence of snippets in all core-supported languages                                       |
| `phpstan`               | runs the PHP static analysis tool                                                                     |
| `phpunit`               | Launches the PHP unit test-suit                                                                       |
| `phpunit:quarantined`   | Launches the PHP unit test-suite for quarantined tests                                                |
| `storefront:unit`       | Launches the jest unit test-suite for the Storefront                                                  |
| `storefront:unit:watch` | Launches the interactive jest unit test-suite watcher for the Storefront                              |

---

---
url: /docs/resources/references/adr/2022-11-09-composer-based-web-updater.md
---

# Composer-based web updater

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-11-09-composer-based-web-updater.md)
:::

## Context

Currently, we are using a Slim Framework 2 based web updater which downloads the zip file from our server and unpacks it.
This is a very old approach and blocks us implementing new features like using Composer to install additional composer packages.

So our main problems are:

### Outdated stack of the updater itself

The Slim Framework 2 is outdated and is not supported anymore. We also don't have any good knowledge about the framework itself.

### Dangerous update process

* We assume that the shop files are in the same state as after the installation or the latest update. So we only apply the changeset to the latest update
* If the user runs Composer commands, the generated and dumped autoloader can differ and break the entire shop

### No Composer support

* Due to the simple unpacking of a changeset of the Shopware update, the user cannot use Composer to install additional packages
* Extensions have to package their own dependencies inside their extension zip and overwrite dependencies of Shopware or other extensions which can cause problems

## Decision

We will build a new Symfony based web updater which is packaged as an single phar file.
The Phar file will be downloaded from our server for each update and runs the newest web updater for the process of the update.
This allows us to react faster on bugs and implement new features, without having to wait for a new Shopware release.

The new web updater will use the same update process as the CLI update using composer.

So the process will be:

* The Shopware Admin will do a basic update check that all extensions are compatible with the next Shopware version
* If the user clicks on the update button the web updater will be downloaded and executed
* If the project is still based on the old structure, it will migrate it to Symfony Flex.
* Enable the maintenance mode using `bin/console`
* Run `composer update` to update Shopware
* Run `bin/console` to update the database
* Disable the maintenance mode
* Delete the Phar and Redirect the user to the Shopware Admin

The new way of managing a Shopware project will also allow us to setup a new project with the new tool.
So in the same way, we can provide an installer for new projects by utilising the `create-project` command of Composer.

## Consequences

The System requirements will change. We need access to functions like `proc_open` and `proc_close` in PHP and a PHP-CLI binary.

For updating config files Symfony Flex requires the `git` binary to be installed on the server and a git repository to be initialised.
This is a requirement for reviewing all the changes that have been made to the config files.
To avoid this we will backup the `.env` and the `.htaccess` file and overwrite all config files from a fresh installation and restore the backup.

To merge the upcoming changes of the `.htaccess` file we will use our already existing [UpdateHtaccess](https://github.com/shopware/shopware/blob/6.4.17.0/src/Core/Framework/Update/Services/UpdateHtaccess.php) which is using the Markers to update only our own changes.
For the `.env` files we will make use of `.env.local` to be able to update the normal `.env` file.

The normal CLI update way will require a git repository to be initialised and uses the normal Symfony update flow.

---

---
url: /docs/v6.5/resources/references/adr/2022-11-09-composer-based-web-updater.md
---

# Composer-based web updater

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-11-09-composer-based-web-updater.md)
:::

## Context

Currently, we are using a Slim Framework 2 based web updater which downloads the zip file from our server and unpacks it.
This is a very old approach and blocks us implementing new features like using Composer to install additional composer packages.

So our main problems are:

### Outdated stack of the updater itself

The Slim Framework 2 is outdated and is not supported anymore. We also don't have any good knowledge about the framework itself.

### Dangerous update process

* We assume that the shop files are in the same state as after the installation or the latest update. So we only apply the changeset to the latest update
* If the user runs Composer commands, the generated and dumped autoloader can differ and break the entire shop

### No Composer support

* Due to the simple unpacking of a changeset of the Shopware update, the user cannot use Composer to install additional packages
* Extensions have to package their own dependencies inside their extension zip and overwrite dependencies of Shopware or other extensions which can cause problems

## Decision

We will build a new Symfony based web updater which is packaged as an single phar file.
The Phar file will be downloaded from our server for each update and runs the newest web updater for the process of the update.
This allows us to react faster on bugs and implement new features, without having to wait for a new Shopware release.

The new web updater will use the same update process as the CLI update using composer.

So the process will be:

* The Shopware Admin will do a basic update check that all extensions are compatible with the next Shopware version
* If the user clicks on the update button the web updater will be downloaded and executed
* If the project is still based on the old structure, it will migrate it to Symfony Flex.
* Enable the maintenance mode using `bin/console`
* Run `composer update` to update Shopware
* Run `bin/console` to update the database
* Disable the maintenance mode
* Delete the Phar and Redirect the user to the Shopware Admin

The new way of managing a Shopware project will also allow us to setup a new project with the new tool.
So in the same way, we can provide an installer for new projects by utilising the `create-project` command of Composer.

## Consequences

The System requirements will change. We need access to functions like `proc_open` and `proc_close` in PHP and a PHP-CLI binary.

For updating config files Symfony Flex requires the `git` binary to be installed on the server and a git repository to be initialised.
This is a requirement for reviewing all the changes that have been made to the config files.
To avoid this we will backup the `.env` and the `.htaccess` file and overwrite all config files from a fresh installation and restore the backup.

To merge the upcoming changes of the `.htaccess` file we will use our already existing [UpdateHtaccess](https://github.com/shopware/shopware/blob/6.4.17.0/src/Core/Framework/Update/Services/UpdateHtaccess.php) which is using the Markers to update only our own changes.
For the `.env` files we will make use of `.env.local` to be able to update the normal `.env` file.

The normal CLI update way will require a git repository to be initialised and uses the normal Symfony update flow.

---

---
url: /docs/v6.6/resources/references/adr/2022-11-09-composer-based-web-updater.md
---

# Composer-based web updater

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-11-09-composer-based-web-updater.md)
:::

## Context

Currently, we are using a Slim Framework 2 based web updater which downloads the zip file from our server and unpacks it.
This is a very old approach and blocks us implementing new features like using Composer to install additional composer packages.

So our main problems are:

### Outdated stack of the updater itself

The Slim Framework 2 is outdated and is not supported anymore. We also don't have any good knowledge about the framework itself.

### Dangerous update process

* We assume that the shop files are in the same state as after the installation or the latest update. So we only apply the changeset to the latest update
* If the user runs Composer commands, the generated and dumped autoloader can differ and break the entire shop

### No Composer support

* Due to the simple unpacking of a changeset of the Shopware update, the user cannot use Composer to install additional packages
* Extensions have to package their own dependencies inside their extension zip and overwrite dependencies of Shopware or other extensions which can cause problems

## Decision

We will build a new Symfony based web updater which is packaged as an single phar file.
The Phar file will be downloaded from our server for each update and runs the newest web updater for the process of the update.
This allows us to react faster on bugs and implement new features, without having to wait for a new Shopware release.

The new web updater will use the same update process as the CLI update using composer.

So the process will be:

* The Shopware Admin will do a basic update check that all extensions are compatible with the next Shopware version
* If the user clicks on the update button the web updater will be downloaded and executed
* If the project is still based on the old structure, it will migrate it to Symfony Flex.
* Enable the maintenance mode using `bin/console`
* Run `composer update` to update Shopware
* Run `bin/console` to update the database
* Disable the maintenance mode
* Delete the Phar and Redirect the user to the Shopware Admin

The new way of managing a Shopware project will also allow us to setup a new project with the new tool.
So in the same way, we can provide an installer for new projects by utilising the `create-project` command of Composer.

## Consequences

The System requirements will change. We need access to functions like `proc_open` and `proc_close` in PHP and a PHP-CLI binary.

For updating config files Symfony Flex requires the `git` binary to be installed on the server and a git repository to be initialised.
This is a requirement for reviewing all the changes that have been made to the config files.
To avoid this we will backup the `.env` and the `.htaccess` file and overwrite all config files from a fresh installation and restore the backup.

To merge the upcoming changes of the `.htaccess` file we will use our already existing [UpdateHtaccess](https://github.com/shopware/shopware/blob/6.4.17.0/src/Core/Framework/Update/Services/UpdateHtaccess.php) which is using the Markers to update only our own changes.
For the `.env` files we will make use of `.env.local` to be able to update the normal `.env` file.

The normal CLI update way will require a git repository to be initialised and uses the normal Symfony update flow.

---

---
url: /docs/products/extensions/b2b-suite-migration/concept.md
---

# Concept

The migration process is designed to handle large datasets while maintaining data integrity. It uses three dedicated tables to track status, map records, and log errors. A message queue ensures scalability, and sequential migration respects entity relationships (e.g., migrating employees before quotes). Understanding these concepts is crucial before proceeding to execution.

## Migration Approach

The whole migration is executed in a message queue, allowing for scalable processing of large volumes of data. The migration is structured to ensure that all components and entities are migrated in the correct order, respecting their relationships and dependencies. All mappings fields and tables are defined via XML configuration files, which are processed by configurator. This modular approach allows for easy customization and extension of the migration process.

## Key Features

* **Message Queue**: Utilizes a message queue to process large volumes of data, ensuring scalability.
* **Sequential Migration**: Components (e.g., Employee, Budget, Quote, Shopping List) are migrated sequentially to respect entity relationships (e.g., employee records before budget).
* **Entity-Level Sequencing**: Within each component, entities (e.g., business partners, employees, roles) are migrated in the correct order.

::: info
Proper sequencing is critical to avoid dependency issues. Verify the migration order for your dataset.
:::

---

---
url: /docs/products/extensions/migration-assistant/concept.md
---

# Concept

## Overview

[Shopware Migration Assistant](https://github.com/shopware/SwagMigrationAssistant) was built with simple but powerful concepts in mind. These enable you to extend the plugin in various ways and migrate data into the Shopware 6 environment. You should have a basic understanding of how to use the migration plugin and its core features before extending it yourself, as this documentation will not explain the usage of the plugin.

We will provide you with a basic introduction to the concepts and structure right here in this chapter. Take a look at the last headline (Extension points) to find out more about the various ways to extend this plugin.

## Migration process

The migration procedure, states, and full step-by-step workflow are documented on a dedicated page.

For details, see [Migration Process](migration-process).

## Profile and connections

Users of the plugin can create connections to different source systems. A connection is used to allow multiple migrations from the same source and update the right data (mapping). Connections require a specific profile indicating the type of source system. Users can, for example, create a connection to a Shopware shop using the Shopware 5.5 profile. Developers can create their own profiles from scratch, connect to different source systems, or just extend existing ones.

For more details, look at [Profile and Connection](profile-and-connection).

## DataSelection and DataSet

These are the fundamental data structures for defining what to migrate. Each `DataSet` represents an entity, for example, a database table. Each `DataSelection` represents an orderly group of `DataSets`. For more information, refer to the articles on [DataSelection and DataSet](dataselection-and-dataset).

## Migration context

This data structure provides all the necessary data for the migration. For more details, refer to the [Migration Context](migration-context).

## Premapping

Because the structure of the source system does not always match the structure of the target system, the user may need to map the old structure to the new one. For example, in Shopware 5, we have default salutations like `Mr.`, but the user can also create custom ones. In Shopware 6, there are default salutations like `Mr.` and the user can also create custom ones. So the salutation `Mr.` from Shopware 5 must be mapped to Shopware 6 `Mr.`. In this default case, the mapping can be achieved automatically, but customized salutations will most likely have to be mapped manually. The premapping will be written into the mapping table to associate the old identifier with the new one.

You can look at [Premapping](premapping) section for more details.

## Gateway and reader

Users will have to specify a gateway for the connection. The gateway defines the way of communicating with the source system. Behind the user interface, we use `Reader` objects to read the data from the source system. For the `shopware55` profile, we have the `api` gateway, which communicates via HTTP/S with the source system, and the `local` gateway, which communicates directly with the source system's database. Thus both systems must be on the same server to successfully use the `local` gateway.

To use the `ShopwareApiGateway`, you must download the [Shopware Connector](https://github.com/shopware/SwagMigrationConnector) plugin for your Shopware 5.

For more details, look at the [Gateway and Reader](gateway-and-reader) article.

## Converter, mapping, and deltas

Data gathered by `Reader` objects is transferred to `Converter` objects that put the data in a format Shopware 6 is able to work with. Simultaneously entries in the underlying mapping table are inserted to map the old identifiers to the new ones for future migrations (Have a look at the `MappingService` for that). The mapping is saved for the current connection. Converted data will be removed after the migration, and the mapping will stay persistent. Also, a checksum is saved to the mapping to identify and skip the same source data (data has not been changed since the last migration).

You can find out more about them in the [Convert and Mapping](convert-and-mapping) section of this guide.

## Logging

During any migration, especially during the data conversion, there will possibly be errors that should be logged. The users can see these errors and these should be as helpful as possible.

For more information, have a look at the [Logging](logging) section.

## Error Resolution

The Migration Assistant provides users with the possibility to resolve errors that occurred during migration. The user can see details of an error and decide how to proceed. For example, if a product could not be migrated because of a missing tax, the user can create a new tax and assign it to the product. After that, the user can mark the error as resolved, and the Migration Assistant will try to migrate the product.

For more details, see the [Error Resolution](error-resolution) article.

## Writer

The `Writer` objects will receive the converted data and write it to Shopware 6. There is no special magic here; you do not need to worry about error handling because the Migration Assistant takes care of it.

To learn more about them, take a look at the [Writer](writer) section.

## Media processing

During a typical migration, media is handled in a dedicated processing step after writing. Gateway-specific processors import files either via HTTP (`api` gateway) or local filesystem (`local` gateway).

You can look at the [Media Processing](media-processing) article for more details.

## Extension points

The recommended way to migrate plugin data from a source system is to extend that profile by a new `DataSelection`. It is also possible to create a new profile in case a migration from a different shop/source system is sought.

Take a look at the following guides for your scenario:

* [Extending a Shopware Migration Profile](../guides/extending-a-shopware-migration-profile): Migrating your first basic plugin data (via local gateway).
* [Extending the Migration Connector](../guides/extending-the-migration-connector): Add API support for your migration.
* [Decorating a Shopware Migration Assistant Converter](../guides/decorating-a-shopware-migration-assistant-converter): Implement a premapping and change the behavior of an existing converter.
* [Creating a New Migration Profile](../guides/creating-a-new-migration-profile): Create a new profile from scratch to support a third-party source system (other than Shopware).

---

---
url: /docs/v6.5/products/extensions/migration-assistant/concept.md
---
# Concept

[Shopware Migration Assistant](https://github.com/shopware/SwagMigrationAssistant) was built with simple but powerful concepts in mind. These enable you to extend the plugin in various ways and migrate data into the Shopware 6 environment. You should have a basic understanding of how to use the migration plugin and its core features, before extending it yourself. (this documentation will not explain the usage of the plugin).

We will provide you with a basic introduction into the concepts and structure right here in this chapter. Take a look at the last headline (Extension points) to find out more about the various ways to extend this plugin.

## Profile and connections

Users of the plugin can create connections to different source systems. A connection is used to allow multiple migrations from the same source and update the right data (mapping). Connections require a specific profile, indicating the type of source system. Users can, for example, create a connection to a Shopware shop using the Shopware 5.5 profile. Developers are able to create their own profiles from scratch and connect to different source systems or just build up on and extend existing ones.

For more details have a look at [Profile and Connection](./concept/profile-and-connection).

## DataSelection and dataSet

These are the fundamental data structures for define what to migrate. Each `DataSet` represents an entity, for example a database table. Each `DataSelection` represents an orderly group of `DataSets`. For more Information take a look at [DataSelection and DataSet](./concept/dataselection-and-dataset).

## Migration context

This data structure provides all necessary data of the migration. For more details have a look at [Migration Context](./concept/migration-context).

## Premapping

Because the structure of the source system does not always match the structure of the target system, the user may need to map the old structure to the new one. For example, in Shopware 5 we have default salutations like 'mr', but the user can also create custom ones. In Shopware 6 there are also default salutations like 'mr' and the user can also create custom ones. So the salutation 'mr' from Shopware 5 must be mapped to Shopware 6 'mr'. In this default case the mapping can be achieved automatically, but customized salutations will most likely have to be mapped manually. The premapping will be written into the mapping table to associate the old identifier with the new one. For more details on this, head to [Premapping](./concept/premapping) concepts.

## Gateway and reader

Users will have to specify a gateway for the connection. The gateway defines the way of communicating with the source system. Behind the user interface we use `Reader` objects to read the data from the source system. For the `shopware55` profile we have the `api` gateway, which communicates via http/s with the source system, and the `local` gateway, which communicates directly with the source system's database. Thus both systems must be on the same server for successfully using the `local` gateway.

If you want to use the `ShopwareApiGateway` you have to download the [Shopware Migration Connector](https://github.com/shopware/SwagMigrationConnector) plugin for your Shopware 5. For more details have a look at the [Gateway and Reader](./concept/gateway-and-reader).

## Converter, mapping and deltas

Data gathered by `Reader` objects is transferred to `Converter` objects that put the data in a format Shopware 6 is able to work with. Simultaneously entries in the underlying mapping table are inserted to map the old identifiers to the new ones for future migrations (Have a look at the `MappingService` for that). The mapping is saved for the current connection. Converted data will be removed after the migration, the mapping will stay persistent. Also a checksum is saved to the mapping to identify and skip the same source data (data has not been changed since last migration). You can find out more about them in [Converter and Mapping](./concept/convert-and-mapping) section of this guide.

## Logging

During any migration, especially during the data conversion, there will possibly be errors that should be logged. The users can see these errors and these should be as helpful as possible. For more information, have a look at [Logging](./concept/logging).

## Writer

The `Writer` objects will receive the converted data and write it to Shopware 6. There is no special magic here and you don't need to worry about error handling because the migration assistant takes care of it. To learn more about them, take a look at [Writer](./concept/writer) concept.

## Media processing

During a typical migration we download the media files from the source system to Shopware 6. This is the last processing step in the migration and may be done differently for other gateways. For example the `local` gateway will copy and rename the files directly in the local filesystem. For more Details you can look at [Media Processing](./concept/media-processing).

## After migration

All fetched data will be deleted after finishing or aborting a migration run, but the mapping of the identifiers will stay.

## The migration procedure

The following bullet points will give you a general overview of what happens during a common migration.

1. The user selects / creates a connection (with a profile and gateway specified)
2. The user selects some of the available data (`DataSelections`)
3. Premapping check / execution: The user maps data from the source system to the current system (These decisions are stored with the connection.)
4. Fetch data for every `DataSet` in every selected `DataSelection` (mapping is used to store / use the identifiers from the source system.) 4.1 The corresponding `Reader` reads the data 4.2 The corresponding `Converter` converts the data
5. Write data for every `DataSet` in every selected `DataSelection` 5.1 The corresponding `Writer` writes the data
6. Process media, if necessary for example to download / copy images 6.1 Data in `swag_migration_media_file` table will be downloaded / copied 6.2 Files are assigned to media objects in Shopware 6
7. Finish migration to cleanup

These steps can be done multiple times. Each migration is called a `Run` / `MigrationRun` and will be saved to let the users know about any errors that occurred (in form of a detailed history).

## Extension points

The recommended way to migrate plugin data from a source system is to extend that profile by a new `DataSelection`. It is also possible to create a new profile, in case a migration from a different shop / source system is sought.

Take a look at the following HowTos for your scenario to get a step by step tutorial:

* [Extending a Shopware Migration Profile](./guides/extending-a-shopware-migration-profile) <- migrating your first basic plugin data (via local gateway)
* [Extending the Migration Connector](./guides/extending-the-migration-connector) <- add API support for your migration
* [Decorating a Shopware Migration Assistant Converter](./guides/decorating-a-shopware-migration-assistant-converter) <- implement a premapping and change the behavior of an existing converter
* [Creating a New Migration Profile](./guides/creating-a-new-migration-profile) <- create a new profile from scratch to support a third party source system (other than Shopware)

---

---
url: /docs/v6.5/products/extensions/migration-assistant/concept.md
---

# Concept

## Overview

[Shopware Migration Assistant](https://github.com/shopware/SwagMigrationAssistant) was built with simple but powerful concepts in mind. These enable you to extend the plugin in various ways and migrate data into the Shopware 6 environment. You should have a basic understanding of how to use the migration plugin and its core features before extending it yourself, as this documentation will not explain the usage of the plugin.

We will provide you with a basic introduction to the concepts and structure right here in this chapter. Take a look at the last headline (Extension points) to find out more about the various ways to extend this plugin.

## Profile and connections

Users of the plugin can create connections to different source systems. A connection is used to allow multiple migrations from the same source and update the right data (mapping). Connections require a specific profile indicating the type of source system. Users can, for example, create a connection to a Shopware shop using the Shopware 5.5 profile. Developers can create their own profiles from scratch, connect to different source systems, or just build and extend existing ones.

For more details, look at [Profile and Connection](profile-and-connection).

## DataSelection and dataSet

These are the fundamental data structures for defining what to migrate. Each `DataSet` represents an entity, for example, a database table. Each `DataSelection` represents an orderly group of `DataSets`. For more information, refer to the articles on [DataSelection and DataSet](dataselection-and-dataset).

## Migration context

This data structure provides all the necessary data for the migration. For more details, refer to the [Migration Context](migration-context).

## Premapping

Because the structure of the source system does not always match the structure of the target system, the user may need to map the old structure to the new one. For example, in Shopware 5, we have default salutations like `Mr.`, but the user can also create custom ones. In Shopware 6, there are default salutations like `Mr.` and the user can also create custom ones. So the salutation `Mr.` from Shopware 5 must be mapped to Shopware 6 `Mr.`. In this default case, the mapping can be achieved automatically, but customized salutations will most likely have to be mapped manually. The premapping will be written into the mapping table to associate the old identifier with the new one.

You can look at [Premapping](premapping) section for more details.

## Gateway and reader

Users will have to specify a gateway for the connection. The gateway defines the way of communicating with the source system. Behind the user interface, we use `Reader` objects to read the data from the source system. For the `shopware55` profile, we have the `api` gateway, which communicates via http/s with the source system, and the `local` gateway, which communicates directly with the source system's database. Thus both systems must be on the same server to successfully use the `local` gateway.

To use the `ShopwareApiGateway`, you must download the [Shopware Connector](https://github.com/shopware/SwagMigrationConnector) plugin for your Shopware 5.

For more details, look at the [Gateway and Reader](gateway-and-reader) article.

## Converter, mapping, and deltas

Data gathered by `Reader` objects is transferred to `Converter` objects that put the data in a format Shopware 6 is able to work with. Simultaneously entries in the underlying mapping table are inserted to map the old identifiers to the new ones for future migrations (Have a look at the `MappingService` for that). The mapping is saved for the current connection. Converted data will be removed after the migration, and the mapping will stay persistent. Also, a checksum is saved to the mapping to identify and skip the same source data (data has not been changed since the last migration).

You can find out more about them in the [Convert and Mapping](convert-and-mapping) section of this guide.

## Logging

During any migration, especially during the data conversion, there will possibly be errors that should be logged. The users can see these errors and these should be as helpful as possible.

For more information, have a look at the [Logging](logging) section.

## Writer

The `Writer` objects will receive the converted data and write it to Shopware 6. There is no special magic here; you don't need to worry about error handling because the migration assistant takes care of it.

To learn more about them, take a look at [Writer](writer) section.

## Media processing

During a typical migration, we download the media files from the source system to Shopware 6. This is the last processing step in the migration and may be done differently for other gateways. For example, the `local` gateway will copy and rename the files directly in the local filesystem.

You can look at [Media Processing](media-processing) article for more details.

## After migration

All fetched data will be deleted after finishing or aborting a migration run, but the mapping of the identifiers will stay.

## The migration procedure

The following bullet points will give you a general overview of what happens during a common migration.

1. The user selects/creates a connection (with a profile and gateway specified).
2. The user selects some of the available data (`DataSelections`).
3. Premapping check/execution: The user maps data from the source system to the current system (these decisions are stored with the connection).
4. Fetch data for every `DataSet` in every selected `DataSelection` (mapping is used to store/use the identifiers from the source system).
   4.1 The corresponding `Reader` reads the data.
   4.2 The corresponding `Converter` converts the data.
5. Write data for every `DataSet` in every selected `DataSelection` .
   5.1 The corresponding `Writer` writes the data.
6. Process media, if necessary, for example, to download/copy images .
   6.1 Data in the `swag_migration_media_file` table will be downloaded/copied.
   6.2 Files are assigned to media objects in Shopware 6.
7. Finish migration to clean up.

These steps can be done multiple times. Each migration is called a `Run`/`MigrationRun` and will be saved to inform the users about any errors that occurred (in the form of a detailed history).

## Extension points

The recommended way to migrate plugin data from a source system is to extend that profile by a new `DataSelection`. It is also possible to create a new profile in case a migration from a different shop/source system is sought.

Take a look at the following HowTos for your scenario to get a step-by-step tutorial:

* [Extending a Shopware Migration Profile](../guides/extending-a-shopware-migration-profile): Migrating your first basic plugin data (via local gateway).
* [Extending the Migration Connector](../guides/extending-the-migration-connector): Add API support for your migration.
* [Decorating a Shopware Migration Assistant Converter](../guides/decorating-a-shopware-migration-assistant-converter): Implement a premapping and change the behavior of an existing converter.
* [Creating a New Migration Profile](../guides/creating-a-new-migration-profile): Create a new profile from scratch to support a third-party source system (other than Shopware).

---

---
url: /docs/v6.6/products/extensions/migration-assistant/concept.md
---
# Concept

[Shopware Migration Assistant](https://github.com/shopware/SwagMigrationAssistant) was built with simple but powerful concepts in mind. These enable you to extend the plugin in various ways and migrate data into the Shopware 6 environment. You should have a basic understanding of how to use the migration plugin and its core features, before extending it yourself. (this documentation will not explain the usage of the plugin).

We will provide you with a basic introduction into the concepts and structure right here in this chapter. Take a look at the last headline (Extension points) to find out more about the various ways to extend this plugin.

## Profile and connections

Users of the plugin can create connections to different source systems. A connection is used to allow multiple migrations from the same source and update the right data (mapping). Connections require a specific profile, indicating the type of source system. Users can, for example, create a connection to a Shopware shop using the Shopware 5.5 profile. Developers are able to create their own profiles from scratch and connect to different source systems or just build up on and extend existing ones.

For more details have a look at [Profile and Connection](./concept/profile-and-connection).

## DataSelection and dataSet

These are the fundamental data structures for define what to migrate. Each `DataSet` represents an entity, for example a database table. Each `DataSelection` represents an orderly group of `DataSets`. For more Information take a look at [DataSelection and DataSet](./concept/dataselection-and-dataset).

## Migration context

This data structure provides all necessary data of the migration. For more details have a look at [Migration Context](./concept/migration-context).

## Premapping

Because the structure of the source system does not always match the structure of the target system, the user may need to map the old structure to the new one. For example, in Shopware 5 we have default salutations like 'mr', but the user can also create custom ones. In Shopware 6 there are also default salutations like 'mr' and the user can also create custom ones. So the salutation 'mr' from Shopware 5 must be mapped to Shopware 6 'mr'. In this default case the mapping can be achieved automatically, but customized salutations will most likely have to be mapped manually. The premapping will be written into the mapping table to associate the old identifier with the new one. For more details on this, head to [Premapping](./concept/premapping) concepts.

## Gateway and reader

Users will have to specify a gateway for the connection. The gateway defines the way of communicating with the source system. Behind the user interface we use `Reader` objects to read the data from the source system. For the `shopware55` profile we have the `api` gateway, which communicates via http/s with the source system, and the `local` gateway, which communicates directly with the source system's database. Thus both systems must be on the same server for successfully using the `local` gateway.

If you want to use the `ShopwareApiGateway` you have to download the [Shopware Migration Connector](https://github.com/shopware/SwagMigrationConnector) plugin for your Shopware 5. For more details have a look at the [Gateway and Reader](./concept/gateway-and-reader).

## Converter, mapping and deltas

Data gathered by `Reader` objects is transferred to `Converter` objects that put the data in a format Shopware 6 is able to work with. Simultaneously entries in the underlying mapping table are inserted to map the old identifiers to the new ones for future migrations (Have a look at the `MappingService` for that). The mapping is saved for the current connection. Converted data will be removed after the migration, the mapping will stay persistent. Also a checksum is saved to the mapping to identify and skip the same source data (data has not been changed since last migration). You can find out more about them in [Converter and Mapping](./concept/convert-and-mapping) section of this guide.

## Logging

During any migration, especially during the data conversion, there will possibly be errors that should be logged. The users can see these errors and these should be as helpful as possible. For more information, have a look at [Logging](./concept/logging).

## Writer

The `Writer` objects will receive the converted data and write it to Shopware 6. There is no special magic here and you don't need to worry about error handling because the migration assistant takes care of it. To learn more about them, take a look at [Writer](./concept/writer) concept.

## Media processing

During a typical migration we download the media files from the source system to Shopware 6. This is the last processing step in the migration and may be done differently for other gateways. For example the `local` gateway will copy and rename the files directly in the local filesystem. For more Details you can look at [Media Processing](./concept/media-processing).

## After migration

All fetched data will be deleted after finishing or aborting a migration run, but the mapping of the identifiers will stay.

## The migration procedure

The following bullet points will give you a general overview of what happens during a common migration.

1. The user selects / creates a connection (with a profile and gateway specified)
2. The user selects some of the available data (`DataSelections`)
3. Premapping check / execution: The user maps data from the source system to the current system (These decisions are stored with the connection.)
4. Fetch data for every `DataSet` in every selected `DataSelection` (mapping is used to store / use the identifiers from the source system.) 4.1 The corresponding `Reader` reads the data 4.2 The corresponding `Converter` converts the data
5. Write data for every `DataSet` in every selected `DataSelection` 5.1 The corresponding `Writer` writes the data
6. Process media, if necessary for example to download / copy images 6.1 Data in `swag_migration_media_file` table will be downloaded / copied 6.2 Files are assigned to media objects in Shopware 6
7. Finish migration to cleanup

These steps can be done multiple times. Each migration is called a `Run` / `MigrationRun` and will be saved to let the users know about any errors that occurred (in form of a detailed history).

## Extension points

The recommended way to migrate plugin data from a source system is to extend that profile by a new `DataSelection`. It is also possible to create a new profile, in case a migration from a different shop / source system is sought.

Take a look at the following HowTos for your scenario to get a step by step tutorial:

* [Extending a Shopware Migration Profile](./guides/extending-a-shopware-migration-profile) <- migrating your first basic plugin data (via local gateway)
* [Extending the Migration Connector](./guides/extending-the-migration-connector) <- add API support for your migration
* [Decorating a Shopware Migration Assistant Converter](./guides/decorating-a-shopware-migration-assistant-converter) <- implement a premapping and change the behavior of an existing converter
* [Creating a New Migration Profile](./guides/creating-a-new-migration-profile) <- create a new profile from scratch to support a third party source system (other than Shopware)

---

---
url: /docs/v6.6/products/extensions/migration-assistant/concept.md
---

# Concept

## Overview

[Shopware Migration Assistant](https://github.com/shopware/SwagMigrationAssistant) was built with simple but powerful concepts in mind. These enable you to extend the plugin in various ways and migrate data into the Shopware 6 environment. You should have a basic understanding of how to use the migration plugin and its core features before extending it yourself, as this documentation will not explain the usage of the plugin.

We will provide you with a basic introduction to the concepts and structure right here in this chapter. Take a look at the last headline (Extension points) to find out more about the various ways to extend this plugin.

## Profile and connections

Users of the plugin can create connections to different source systems. A connection is used to allow multiple migrations from the same source and update the right data (mapping). Connections require a specific profile indicating the type of source system. Users can, for example, create a connection to a Shopware shop using the Shopware 5.5 profile. Developers can create their own profiles from scratch, connect to different source systems, or just build and extend existing ones.

For more details, look at [Profile and Connection](profile-and-connection).

## DataSelection and dataSet

These are the fundamental data structures for defining what to migrate. Each `DataSet` represents an entity, for example, a database table. Each `DataSelection` represents an orderly group of `DataSets`. For more information, refer to the articles on [DataSelection and DataSet](dataselection-and-dataset).

## Migration context

This data structure provides all the necessary data for the migration. For more details, refer to the [Migration Context](migration-context).

## Premapping

Because the structure of the source system does not always match the structure of the target system, the user may need to map the old structure to the new one. For example, in Shopware 5, we have default salutations like `Mr.`, but the user can also create custom ones. In Shopware 6, there are default salutations like `Mr.` and the user can also create custom ones. So the salutation `Mr.` from Shopware 5 must be mapped to Shopware 6 `Mr.`. In this default case, the mapping can be achieved automatically, but customized salutations will most likely have to be mapped manually. The premapping will be written into the mapping table to associate the old identifier with the new one.

You can look at [Premapping](premapping) section for more details.

## Gateway and reader

Users will have to specify a gateway for the connection. The gateway defines the way of communicating with the source system. Behind the user interface, we use `Reader` objects to read the data from the source system. For the `shopware55` profile, we have the `api` gateway, which communicates via http/s with the source system, and the `local` gateway, which communicates directly with the source system's database. Thus both systems must be on the same server to successfully use the `local` gateway.

To use the `ShopwareApiGateway`, you must download the [Shopware Connector](https://github.com/shopware/SwagMigrationConnector) plugin for your Shopware 5.

For more details, look at the [Gateway and Reader](gateway-and-reader) article.

## Converter, mapping, and deltas

Data gathered by `Reader` objects is transferred to `Converter` objects that put the data in a format Shopware 6 is able to work with. Simultaneously entries in the underlying mapping table are inserted to map the old identifiers to the new ones for future migrations (Have a look at the `MappingService` for that). The mapping is saved for the current connection. Converted data will be removed after the migration, and the mapping will stay persistent. Also, a checksum is saved to the mapping to identify and skip the same source data (data has not been changed since the last migration).

You can find out more about them in the [Convert and Mapping](convert-and-mapping) section of this guide.

## Logging

During any migration, especially during the data conversion, there will possibly be errors that should be logged. The users can see these errors and these should be as helpful as possible.

For more information, have a look at the [Logging](logging) section.

## Writer

The `Writer` objects will receive the converted data and write it to Shopware 6. There is no special magic here; you don't need to worry about error handling because the migration assistant takes care of it.

To learn more about them, take a look at [Writer](writer) section.

## Media processing

During a typical migration, we download the media files from the source system to Shopware 6. This is the last processing step in the migration and may be done differently for other gateways. For example, the `local` gateway will copy and rename the files directly in the local filesystem.

You can look at [Media Processing](media-processing) article for more details.

## After migration

All fetched data will be deleted after finishing or aborting a migration run, but the mapping of the identifiers will stay.

## The migration procedure

The following bullet points will give you a general overview of what happens during a common migration.

1. The user selects/creates a connection (with a profile and gateway specified).
2. The user selects some of the available data (`DataSelections`).
3. Premapping check/execution: The user maps data from the source system to the current system (these decisions are stored with the connection).
4. Fetch data for every `DataSet` in every selected `DataSelection` (mapping is used to store/use the identifiers from the source system).
   4.1 The corresponding `Reader` reads the data.
   4.2 The corresponding `Converter` converts the data.
5. Write data for every `DataSet` in every selected `DataSelection` .
   5.1 The corresponding `Writer` writes the data.
6. Process media, if necessary, for example, to download/copy images .
   6.1 Data in the `swag_migration_media_file` table will be downloaded/copied.
   6.2 Files are assigned to media objects in Shopware 6.
7. Finish migration to clean up.

These steps can be done multiple times. Each migration is called a `Run`/`MigrationRun` and will be saved to inform the users about any errors that occurred (in the form of a detailed history).

## Extension points

The recommended way to migrate plugin data from a source system is to extend that profile by a new `DataSelection`. It is also possible to create a new profile in case a migration from a different shop/source system is sought.

Take a look at the following HowTos for your scenario to get a step-by-step tutorial:

* [Extending a Shopware Migration Profile](../guides/extending-a-shopware-migration-profile): Migrating your first basic plugin data (via local gateway).
* [Extending the Migration Connector](../guides/extending-the-migration-connector): Add API support for your migration.
* [Decorating a Shopware Migration Assistant Converter](../guides/decorating-a-shopware-migration-assistant-converter): Implement a premapping and change the behavior of an existing converter.
* [Creating a New Migration Profile](../guides/creating-a-new-migration-profile): Create a new profile from scratch to support a third-party source system (other than Shopware).

---

---
url: /docs/resources/references/adr/2022-07-19-blog-concept.md
---

# Concept for blogs using Shopping Experiences

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-07-19-blog-concept.md)
:::

## Context

A highly requested feature & expected for the CMS of Shopware 6 is the blog. In addition, this is an ideal use case and example for the use of [Custom Entities](../adr/2021-09-14-technical-concept-custom-entities).

## Decision

We want to implement blogs as part of the CMS. Since Custom Entities offers a good chance to implement such a feature, the blog is supposed to show the community how to handle Custom Entities in the Shopping Experiences.
Therefore, we decided on the following:

### Blog posts & Content types

Multiple types of content should be available in the future for our CMS and be directly accessible in the Content section of the administration. Using `admin-ui` as a flag in its specific xml file, Shopware will create a listing and a detail page into the Content section automatically for types of content (Custom Entities).
In addition, the `cms-aware` flag also will bring some pre-defined fields, used as defaults in the CMS elements, to our entity. Those are always prefixed with `sw_` to avoid duplicates by the user:

* `sw_title`
* `sw_content`
* `sw_media_id`
* `sw_cms_page_id`
* `sw_cms_page_version_id`
* `sw_seo_meta_title`
* `sw_seo_meta_description`
* `sw_seo_keywords`

To keep everything tidy, we decided to implement using two different files `admin-ui.xml` and `cms-aware.xml` and keep a distinct separation of schema and UI.
This flag will also result in new component types, so that for example the `cms-aware` property's `sw_cms_page_id` can be rendered as a CMS page selection, like known from the categories.

![Category menu with Content types](../../../assets/adr/content-management/example-cms-aware-admin-menu.png)

#### Example `admin-ui.xml`

```xml
<admin-ui>
    <entity name="custom_entity_example"
            navigation-parent="sw-content"
            position="50"
            icon="regular-tools-alt"
            color="#f00">
        <listing>
            <columns>
                <column ref="name"/>
                <column ref="my_description"/>
                <column ref="position" hidden="true" />
                <column ref="rating"/>
            </columns>
        </listing>
        <detail>
            <tabs>
                <tab name="main">
                    <card name="general">
                        <field ref="name"/>
                        <field ref="position"/>
                        <field ref="rating"/>
                    </card>
                    <card name="cardClone">
                        <field ref="name"/>
                        <field ref="my_description"/>
                    </card>
                </tab>
                <tab name="tabClone">
                    <card name="generalSecond">
                        <field ref="name"/>
                        <field ref="position"/>
                        <field ref="rating"/>
                    </card>
                    <card name="cardClone">
                        <field ref="name"/>
                        <field ref="my_description"/>
                    </card>
                </tab>
                <!-- cms-aware tabs will always be rendered last, if defined -->
            </tabs>
        </detail>
    </entity>
    <entity name="custom_entity_example_second"
            navigation-parent="sw-content"
            position="50"
            icon="regular-tools-alt"
            color="#f00">
        <!-- Like above -->
    </entity>
</admin-ui>
```

#### Example `cms-aware.xml`

```xml
<?xml version="1.0" encoding="utf-8" ?>
<cms-aware xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:noNamespaceSchemaLocation="../../../../../../../../src/Core/System/CustomEntity/Xml/Config/CmsAware/cms-aware-1.0.xsd">
    <entity name="custom_entity_example"/>
    <entity name="custom_entity_example_second"/>
</cms-aware>
```

### Category type as blogs

A blog is defined as a collection of blog posts, some additional metadata, SEO data and an associated CMS page. With this
in mind, we decided upon using categories and create a new type `blog` for those, since the category itself has everything
we need for a blog feature, even in terms of UI. The only change would be to replace assigned products with assigned posts, or custom entity entries when speaking generally.
The CMS page template assigned to the category will contain a post listing.

With content types in mind, this will be an additional step to be auto generated via the `cms-aware` flag of Custom Entities.

### Basic blog structure

```mermaid
erDiagram
    blog_post {
        uuid id PK
        uuid sw_cms_page_id
        uuid sw_media_id
        string sw_title
        string sw_content
        string sw_seo_meta_title
        string sw_seo_meta_description
        string sw_seo_keywords
        json custom_fields
        datetime publish_at
    }
    category {
        uuid id PK
        string type
    }
    blog_post_category {
        uuid blog_post_id PK
        uuid category_id PK
    }
    blog_post_tag {
        uuid blog_post_id PK
        uuid tag_id PK
    }
    blog_post ||--o{ blog_post_category : "collected in"
    blog_post_category }o--|| category : "collected in"
    blog_post }o--|| cms_page : "has blog post template"
    cms_slot_config |o--o| category : "listing block"
    blog_post ||--o{ blog_post_tag : ""
    blog_post_tag }o--|| tag : ""
```

### Snippet structure

Modules generated via `admin-ui.xml` are automatically referring to the following snippet structure:

```json
{
   "custom_entity_bundle": {
       "moduleTitle": "Blog posts",
       "moduleDescription": "Blog is colorful and has pics",
       "tabs": {
           "main": "Main settings",
           "tabClone": "Optional stuff"
       },
       "cards": {
           "general": "General stuff",
           "cardClone": "Just a clone",
           "generalSecond": "More general stuff"
       },
       "fields": {
           "swTitle": "Title",
           "swContent": "Product description",
           "swContentHelpText": "Help text!",
           "swContentPlaceholder": "Enter description...",
           "position": "Positioning"
       }
   }
}
```

---

---
url: /docs/v6.5/resources/references/adr/2022-07-19-blog-concept.md
---

# Concept for blogs using Shopping Experiences

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-07-19-blog-concept.md)
:::

## Context

A highly requested feature & expected for the CMS of Shopware 6 is the blog. In addition, this is an ideal use case and example for the use of [Custom Entities](../adr/2021-09-14-technical-concept-custom-entities).

## Decision

We want to implement blogs as part of the CMS. Since Custom Entities offers a good chance to implement such a feature, the blog is supposed to show the community how to handle Custom Entities in the Shopping Experiences.
Therefore, we decided on the following:

### Blog posts & Content types

Multiple types of content should be available in the future for our CMS and be directly accessible in the Content section of the administration. Using `admin-ui` as a flag in its specific xml file, Shopware will create a listing and a detail page into the Content section automatically for types of content (Custom Entities).
In addition, the `cms-aware` flag also will bring some pre-defined fields, used as defaults in the CMS elements, to our entity. Those are always prefixed with `sw_` to avoid duplicates by the user:

* `sw_title`
* `sw_content`
* `sw_media_id`
* `sw_cms_page_id`
* `sw_cms_page_version_id`
* `sw_seo_meta_title`
* `sw_seo_meta_description`
* `sw_seo_keywords`

To keep everything tidy, we decided to implement using two different files `admin-ui.xml` and `cms-aware.xml` and keep a distinct separation of schema and UI.
This flag will also result in new component types, so that for example the `cms-aware` property's `sw_cms_page_id` can be rendered as a CMS page selection, like known from the categories.

![Category menu with Content types](../../../assets/adr/content-management/example-cms-aware-admin-menu.png)

#### Example `admin-ui.xml`

```xml
<admin-ui>
    <entity name="custom_entity_example"
            navigation-parent="sw-content"
            position="50"
            icon="regular-tools-alt"
            color="#f00">
        <listing>
            <columns>
                <column ref="name"/>
                <column ref="my_description"/>
                <column ref="position" hidden="true" />
                <column ref="rating"/>
            </columns>
        </listing>
        <detail>
            <tabs>
                <tab name="main">
                    <card name="general">
                        <field ref="name"/>
                        <field ref="position"/>
                        <field ref="rating"/>
                    </card>
                    <card name="cardClone">
                        <field ref="name"/>
                        <field ref="my_description"/>
                    </card>
                </tab>
                <tab name="tabClone">
                    <card name="generalSecond">
                        <field ref="name"/>
                        <field ref="position"/>
                        <field ref="rating"/>
                    </card>
                    <card name="cardClone">
                        <field ref="name"/>
                        <field ref="my_description"/>
                    </card>
                </tab>
                <!-- cms-aware tabs will always be rendered last, if defined -->
            </tabs>
        </detail>
    </entity>
    <entity name="custom_entity_example_second"
            navigation-parent="sw-content"
            position="50"
            icon="regular-tools-alt"
            color="#f00">
        <!-- Like above -->
    </entity>
</admin-ui>
```

#### Example `cms-aware.xml`

```xml
<?xml version="1.0" encoding="utf-8" ?>
<cms-aware xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:noNamespaceSchemaLocation="../../../../../../../../src/Core/System/CustomEntity/Xml/Config/CmsAware/cms-aware-1.0.xsd">
    <entity name="custom_entity_example"/>
    <entity name="custom_entity_example_second"/>
</cms-aware>
```

### Category type as blogs

A blog is defined as a collection of blog posts, some additional metadata, SEO data and an associated CMS page. With this
in mind, we decided upon using categories and create a new type `blog` for those, since the category itself has everything
we need for a blog feature, even in terms of UI. The only change would be to replace assigned products with assigned posts, or custom entity entries when speaking generally.
The CMS page template assigned to the category will contain a post listing.

With content types in mind, this will be an additional step to be auto generated via the `cms-aware` flag of Custom Entities.

### Basic blog structure

```mermaid
erDiagram
    blog_post {
        uuid id PK
        uuid sw_cms_page_id
        uuid sw_media_id
        string sw_title
        string sw_content
        string sw_seo_meta_title
        string sw_seo_meta_description
        string sw_seo_keywords
        json custom_fields
        datetime publish_at
    }
    category {
        uuid id PK
        string type
    }
    blog_post_category {
        uuid blog_post_id PK
        uuid category_id PK
    }
    blog_post_tag {
        uuid blog_post_id PK
        uuid tag_id PK
    }
    blog_post ||--o{ blog_post_category : "collected in"
    blog_post_category }o--|| category : "collected in"
    blog_post }o--|| cms_page : "has blog post template"
    cms_slot_config |o--o| category : "listing block"
    blog_post ||--o{ blog_post_tag : ""
    blog_post_tag }o--|| tag : ""
```

### Snippet structure

Modules generated via `admin-ui.xml` are automatically referring to the following snippet structure:

```json
{
   "custom_entity_bundle": {
       "moduleTitle": "Blog posts",
       "moduleDescription": "Blog is colorful and has pics",
       "tabs": {
           "main": "Main settings",
           "tabClone": "Optional stuff"
       },
       "cards": {
           "general": "General stuff",
           "cardClone": "Just a clone",
           "generalSecond": "More general stuff"
       },
       "fields": {
           "swTitle": "Title",
           "swContent": "Product description",
           "swContentHelpText": "Help text!",
           "swContentPlaceholder": "Enter description...",
           "position": "Positioning"
       }
   }
}
```

---

---
url: /docs/v6.6/resources/references/adr/2022-07-19-blog-concept.md
---

# Concept for blogs using Shopping Experiences

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-07-19-blog-concept.md)
:::

## Context

A highly requested feature & expected for the CMS of Shopware 6 is the blog. In addition, this is an ideal use case and example for the use of [Custom Entities](../adr/2021-09-14-technical-concept-custom-entities).

## Decision

We want to implement blogs as part of the CMS. Since Custom Entities offers a good chance to implement such a feature, the blog is supposed to show the community how to handle Custom Entities in the Shopping Experiences.
Therefore, we decided on the following:

### Blog posts & Content types

Multiple types of content should be available in the future for our CMS and be directly accessible in the Content section of the administration. Using `admin-ui` as a flag in its specific xml file, Shopware will create a listing and a detail page into the Content section automatically for types of content (Custom Entities).
In addition, the `cms-aware` flag also will bring some pre-defined fields, used as defaults in the CMS elements, to our entity. Those are always prefixed with `sw_` to avoid duplicates by the user:

* `sw_title`
* `sw_content`
* `sw_media_id`
* `sw_cms_page_id`
* `sw_cms_page_version_id`
* `sw_seo_meta_title`
* `sw_seo_meta_description`
* `sw_seo_keywords`

To keep everything tidy, we decided to implement using two different files `admin-ui.xml` and `cms-aware.xml` and keep a distinct separation of schema and UI.
This flag will also result in new component types, so that for example the `cms-aware` property's `sw_cms_page_id` can be rendered as a CMS page selection, like known from the categories.

![Category menu with Content types](../../../assets/adr/content-management/example-cms-aware-admin-menu.png)

#### Example `admin-ui.xml`

```xml
<admin-ui>
    <entity name="custom_entity_example"
            navigation-parent="sw-content"
            position="50"
            icon="regular-tools-alt"
            color="#f00">
        <listing>
            <columns>
                <column ref="name"/>
                <column ref="my_description"/>
                <column ref="position" hidden="true" />
                <column ref="rating"/>
            </columns>
        </listing>
        <detail>
            <tabs>
                <tab name="main">
                    <card name="general">
                        <field ref="name"/>
                        <field ref="position"/>
                        <field ref="rating"/>
                    </card>
                    <card name="cardClone">
                        <field ref="name"/>
                        <field ref="my_description"/>
                    </card>
                </tab>
                <tab name="tabClone">
                    <card name="generalSecond">
                        <field ref="name"/>
                        <field ref="position"/>
                        <field ref="rating"/>
                    </card>
                    <card name="cardClone">
                        <field ref="name"/>
                        <field ref="my_description"/>
                    </card>
                </tab>
                <!-- cms-aware tabs will always be rendered last, if defined -->
            </tabs>
        </detail>
    </entity>
    <entity name="custom_entity_example_second"
            navigation-parent="sw-content"
            position="50"
            icon="regular-tools-alt"
            color="#f00">
        <!-- Like above -->
    </entity>
</admin-ui>
```

#### Example `cms-aware.xml`

```xml
<?xml version="1.0" encoding="utf-8" ?>
<cms-aware xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:noNamespaceSchemaLocation="../../../../../../../../src/Core/System/CustomEntity/Xml/Config/CmsAware/cms-aware-1.0.xsd">
    <entity name="custom_entity_example"/>
    <entity name="custom_entity_example_second"/>
</cms-aware>
```

### Category type as blogs

A blog is defined as a collection of blog posts, some additional metadata, SEO data and an associated CMS page. With this
in mind, we decided upon using categories and create a new type `blog` for those, since the category itself has everything
we need for a blog feature, even in terms of UI. The only change would be to replace assigned products with assigned posts, or custom entity entries when speaking generally.
The CMS page template assigned to the category will contain a post listing.

With content types in mind, this will be an additional step to be auto generated via the `cms-aware` flag of Custom Entities.

### Basic blog structure

```mermaid
erDiagram
    blog_post {
        uuid id PK
        uuid sw_cms_page_id
        uuid sw_media_id
        string sw_title
        string sw_content
        string sw_seo_meta_title
        string sw_seo_meta_description
        string sw_seo_keywords
        json custom_fields
        datetime publish_at
    }
    category {
        uuid id PK
        string type
    }
    blog_post_category {
        uuid blog_post_id PK
        uuid category_id PK
    }
    blog_post_tag {
        uuid blog_post_id PK
        uuid tag_id PK
    }
    blog_post ||--o{ blog_post_category : "collected in"
    blog_post_category }o--|| category : "collected in"
    blog_post }o--|| cms_page : "has blog post template"
    cms_slot_config |o--o| category : "listing block"
    blog_post ||--o{ blog_post_tag : ""
    blog_post_tag }o--|| tag : ""
```

### Snippet structure

Modules generated via `admin-ui.xml` are automatically referring to the following snippet structure:

```json
{
   "custom_entity_bundle": {
       "moduleTitle": "Blog posts",
       "moduleDescription": "Blog is colorful and has pics",
       "tabs": {
           "main": "Main settings",
           "tabClone": "Optional stuff"
       },
       "cards": {
           "general": "General stuff",
           "cardClone": "Just a clone",
           "generalSecond": "More general stuff"
       },
       "fields": {
           "swTitle": "Title",
           "swContent": "Product description",
           "swContentHelpText": "Help text!",
           "swContentPlaceholder": "Enter description...",
           "position": "Positioning"
       }
   }
}
```

---

---
url: /docs/products/extensions/b2b-components/employee-management/concepts.md
---

# Concepts

This section includes the concepts related to Employee Management.

## Additional info

It's important to keep in mind that employees are uniquely identified via their email address.
When a new employee gets invited, a check will be performed to ensure that the email address is in use only once.

---

---
url: /docs/products/extensions/b2b-suite/concept.md
---

# Concepts

B2B Suite is a comprehensive software solution that facilitates efficient and seamless business-to-business transactions. It provides organizations with a complete set of tools and functionalities to enhance communication, collaboration, and transaction management with their trading partners. In this section, you will explore the key components of the B2B Suite, including its system architecture, the basic conventions of B2B, the method structure, and the line item list.

---

---
url: /docs/v6.5/products/extensions/b2b-components/employee-management/concept.md
---

# Concepts

This section includes the concepts related to Employee Management.

## Additional info

It's important to keep in mind that employees are uniquely identified via their email address.
When a new employee gets invited, a check will be performed to ensure that the email address is in use only once.

---

---
url: /docs/v6.5/products/extensions/b2b-suite/concept.md
---

# Concepts

B2B Suite is a comprehensive software solution that facilitates efficient and seamless business-to-business transactions. It provides organizations with a complete set of tools and functionalities to enhance communication, collaboration, and transaction management with their trading partners. In this section, you will explore the key components of the B2B Suite, including its system architecture, the basic conventions of B2B, the method structure, and the line item list.

---

---
url: /docs/v6.6/products/extensions/b2b-components/employee-management/concepts.md
---

# Concepts

This section includes the concepts related to Employee Management.

## Additional info

It's important to keep in mind that employees are uniquely identified via their email address.
When a new employee gets invited, a check will be performed to ensure that the email address is in use only once.

---

---
url: /docs/v6.6/products/extensions/b2b-suite/concept.md
---

# Concepts

B2B Suite is a comprehensive software solution that facilitates efficient and seamless business-to-business transactions. It provides organizations with a complete set of tools and functionalities to enhance communication, collaboration, and transaction management with their trading partners. In this section, you will explore the key components of the B2B Suite, including its system architecture, the basic conventions of B2B, the method structure, and the line item list.

---

---
url: /docs/v6.6/products/extensions/subscriptions/concept.md
---
# Concepts

To use subscriptions, you will need to be familiar with two core concepts in subscription models.

## Plans

A plan is a set of rules that define the subscription. This includes the billing interval and the product that the customer will receive. Multiple intervals can be assigned to a single plan. Plans can be created and managed in the Shopware administration.

## Intervals

An interval is the time between each delivery cycle. For example, a delivery can be monthly, quarterly, or annually. Billing is triggered each time a delivery cycle repeats. The interval is defined in the plan and can be set to any time frame. This is also created and managed in the Shopware administration.

Intervals can be of three different types:

### Relative

A relative interval is an interval that is determined by a previous interval. For example, if a customer subscribes to a monthly plan, the next interval will be one month after the first delivery. These intervals are determined by using PHP's `DateInterval` class.

### Absolute

An absolute interval is an interval that is determined by a fixed date. For example, if a customer subscribes to a monthly plan, the next interval will be on a fixed day like the 1st or 15th of each month. These work with cron expressions.

### Mixed

A mix of the two types above. For instance, a customer subscribes to a plan that delivers every 12 weeks, but only on a Friday. These intervals are determined by using PHP's `DateInterval` class in combination with cron expressions.

## Further reading

You can read more about the setup of plans and intervals in the [Shopware documentation](https://docs.shopware.com/en/shopware-6-en/settings/shop/subscriptions).

---

---
url: /resources/admin-extension-sdk/concepts.md
---

# Concepts

Before building Administration extensions, it helps to understand a few core concepts used by the Meteor Admin SDK.

These concepts explain how extensions are rendered, where UI can be injected, and how data is accessed.

## Concepts overview

* [Architecture](./architecture.md): explains how the SDK communicates with the Shopware Administration and how requests are handled internally.
* [Locations](./locations.md): determine where extension code runs.
* [Positions](./positions.md): identify extendable areas of the Administration UI.
* [Component Sections](./component-sections.md): render custom components inside extension points.
* [Selectors](./selectors.md): retrieve specific fields from Administration data.
* [Data Handling](./datahandling.md): represent the data published by the Administration that extensions can read, subscribe to, or update.

---

---
url: /frontends/concepts.md
---

# CONCEPTS

Understand how Shopware Frontends is put together before you start building. For task-based instructions, see the [Guides](../guides/) section instead.

---

---
url: /docs/resources/guidelines/documentation-guidelines/02-conceptual-structure.md
---

# Conceptual Outline

Our documentation is categorized into the following sections - Concepts, Products, Guides, and Resources. This structure provides different levels of detail, abstraction, and focus.

To give our readers a good experience, we have established writing guidelines for these sections.

## Concepts

This section articulates the core concepts of Shopware. It is an entry point to learn about how the platform is organized. This section rather **explains** than **shows** how things work

## Products

This section deals with topics specific to a single product of Shopware. Every product shares at least some aspect and serves as an entry point to other sections. For example, the *catalog* used within our Community Edition and in all commercial plans is technically the same.

## Guides

This section of the document is home to all the *how-to's*, *examples, cookbooks*, and *tutorials*. In contrast to articles within the *Concepts section*, *Guides* show code, give concrete examples, and provide step-by-step instructions.

It is essential to refer back to the concepts section for related topics from the Guides. For example, *"How to create a custom cart processor"* might contain terms and concepts explained within the "Concepts > Commerce > Checkout > Cart" section and also relate to topics dealt within the "Concepts > Framework > Rules" section. A clear structure allows you to create these cross-references and make the documentation more readable.

## Resources

Resources contain structured documentation for API references, code references, testing references, tooling, links, SDKs, libraries, etc. It also includes guidelines for contribution and publishing.

Now that you have understood the documentation structure, the following section describes the command over language one needs to use for documentation.

---

---
url: >-
  /docs/v6.5/resources/guidelines/documentation-guidelines/02-conceptual-structure.md
---

# Conceptual Outline

Our documentation is categorized into the following sections - Concepts, Products, Guides, and Resources. This structure provides different levels of detail, abstraction, and focus.

To give our readers a good experience, we have established writing guidelines for these sections.

## Concepts

This section articulates the core concepts of Shopware. It is an entry point to learn about how the platform is organized. This section rather **explains** than **shows** how things work

## Products

This section deals with topics specific to a single product of Shopware. Every product shares at least some aspect and serves as an entry point to other sections. For example, the *catalog* used within our Community Edition and in all commercial plans is technically the same.

## Guides

This section of the document is home to all the *how-to's*, *examples, cookbooks*, and *tutorials*. In contrast to articles within the *Concepts section*, *Guides* show code, give concrete examples, and provide step-by-step instructions.

It is essential to refer back to the concepts section for related topics from the Guides. For example, *"How to create a custom cart processor"* might contain terms and concepts explained within the "Concepts > Commerce > Checkout > Cart" section and also relate to topics dealt within the "Concepts > Framework > Rules" section. A clear structure allows you to create these cross-references and make the documentation more readable.

## Resources

Resources contain structured documentation for API references, code references, testing references, tooling, links, SDKs, libraries, etc. It also includes guidelines for contribution and publishing.

Now that you have understood the documentation structure, the following section describes the command over language one needs to use for documentation.

---

---
url: >-
  /docs/v6.6/resources/guidelines/documentation-guidelines/02-conceptual-structure.md
---

# Conceptual Outline

Our documentation is categorized into the following sections - Concepts, Products, Guides, and Resources. This structure provides different levels of detail, abstraction, and focus.

To give our readers a good experience, we have established writing guidelines for these sections.

## Concepts

This section articulates the core concepts of Shopware. It is an entry point to learn about how the platform is organized. This section rather **explains** than **shows** how things work

## Products

This section deals with topics specific to a single product of Shopware. Every product shares at least some aspect and serves as an entry point to other sections. For example, the *catalog* used within our Community Edition and in all commercial plans is technically the same.

## Guides

This section of the document is home to all the *how-to's*, *examples, cookbooks*, and *tutorials*. In contrast to articles within the *Concepts section*, *Guides* show code, give concrete examples, and provide step-by-step instructions.

It is essential to refer back to the concepts section for related topics from the Guides. For example, *"How to create a custom cart processor"* might contain terms and concepts explained within the "Concepts > Commerce > Checkout > Cart" section and also relate to topics dealt within the "Concepts > Framework > Rules" section. A clear structure allows you to create these cross-references and make the documentation more readable.

## Resources

Resources contain structured documentation for API references, code references, testing references, tooling, links, SDKs, libraries, etc. It also includes guidelines for contribution and publishing.

Now that you have understood the documentation structure, the following section describes the command over language one needs to use for documentation.

---

---
url: /docs/resources/references/config-reference.md
---
# Config Reference

This section gives you a reference on server configuration.

---

---
url: /docs/v6.5/resources/references/config-reference.md
---
# Config Reference

This section gives you a reference on server configuration.

---

---
url: /docs/v6.6/resources/references/config-reference.md
---
# Config Reference

This section gives you a reference on server configuration.

---

---
url: /docs/guides/plugins/apps/lifecycle/configuration.md
---

# Configuration

::: info
Configurations for apps adhere to the same schema as [Plugin Configurations](../../plugins/plugin-fundamentals/add-plugin-configuration.md).
:::

## Overview

To offer configuration possibilities to your users you can provide a `config.xml` file that describes your configuration options. You can find detailed information about the possibilities and the structure of the `config.xml` in the according documentation page. To include a `config.xml` file in your app put it into the `Resources/config` folder:

```text
...
└── DemoApp
      └── Resources
            └── config  
                  └── config.xml
      └── manifest.xml
```

The configuration page will be displayed in the Administration under `Extensions > My extensions`.
For development purposes you can use the Administration component to configure plugins to provide configuration for your app, therefore use the URL `{APP_URL}/admin#/sw/extension/config/{appName}`.

If an app configuration value changes cached Storefront output, mark the corresponding `<input-field>` or `<component>` with `cache-relevant="true"` in the `config.xml`. See [Cache relevant fields](../../plugins/plugin-fundamentals/add-plugin-configuration.md#cache-relevant-fields) for details.

## Reading the configuration values

The configuration values are saved as part of the `SystemConfig` and you can use the key `{appName}.config.{fieldName}` to identify the values. There are two possibilities to access the configuration values from your app. If you need those values on your app-backend server, you can read them over the API. If you need the configuration values in your Storefront twig templates you can use the `systemConfig()`-twig function.

### Reading the config over the API

To access your apps configuration over the API make a GET request against the `/api/_action/system-config` route. You have to add the prefix for your configuration as the `domain` query parameter. Optionally you can provide a `SalesChannelId`, if you want to read the values for a specific SalesChannel, as the `salesChannelId` query param. The API call will return a JSON-Object containing all of your configuration values. A sample Request and Response may look like this.

```txt
GET /api/_action/system-config?domain=DemoApp.config&salesChannelId=98432def39fc4624b33213a56b8c944d

{
    "DemoApp.config.field1": true,
    "DemoApp.config.field2": "successfully configured"
}
```

::: warning
Keep in mind that your app needs the `system_config:read` permission to access this API.
:::

### Writing the config over the API

To write your app's configuration over the API, make a `POST`request against the `/api/_action/system-config` route.
You have to provide the configurations as JSON object and optionally provide a `salesChannelId` query param, if you want to write the values for a specific Sales Channel.

```txt
POST /api/_action/system-config?salesChannelId=98432def39fc4624b33213a56b8c944d
Content-Type: application/json

{
    "DemoApp.config.field1": true
}
```

::: warning
Keep in mind that your app needs the `system_config:update`, `system_config:create` and `system_config:delete` permission to access this API.
:::

### Reading the config in templates

Inside twig templates you can use the twig function `config` (see [Shopware Twig functions](../../plugins/storefront/templates/twig-function-reference.md). An example twig template could look like this:

```twig
{{ config('DemoApp.config.field1') }}
```

### Reading the config in app scripts

App scripts provide access to the [`config` service](../../../../resources/references/app-reference/script-reference/miscellaneous-script-services-reference.md#servicesconfig-shopwarecoresystemsystemconfigfacadesystemconfigfacade), which can be used to access config values.

::: info
Note that app scripts were introduced in Shopware 6.4.8.0, and are not supported in previous versions.
:::

The `config` service provides an `app()` method, that can be used to access your app's configuration. When using this method you don't need to provide the `{appName}.config` prefix and your app does not need any additional permissions.

```twig
{% set configValue = services.config.app('field1') %}
```

Additionally, you can use the `get()` method, to access any configuration value and not just the ones of your app.

::: warning
Your app needs the `system_config:read` permission to use the `config.get()` method.
:::

```twig
{% set configValue = services.config.get('core.listing.productsPerPage') %}
```

## Next steps

* Review the [App Scripts guide](../app-scripts/index.md)
* Find a full description of the `config` service at its [reference guide](../../../../resources/references/app-reference/script-reference/miscellaneous-script-services-reference.md#servicesconfig-shopwarecoresystemsystemconfigfacadesystemconfigfacade).

---

---
url: /docs/products/tools/cli/extension-commands/configuration.md
---

# Configuration

Many configurations can be changed using a `.shopware-extension.yml` file in the root of your extension.

Here is an example of a `.shopware-extension.yml` file:

```yaml
compatibility_date: '2026-02-11'

build:
  extraBundles:
    - path: src/Foo
    - name: OverrideName
      path: src/Override
  shopwareVersionConstraint: '~6.6.0'
  zip:
    assets:
      enabled: false
      before_hooks: []
      after_hooks: []
      disable_sass: false
      enable_es_build_for_admin: false
      enable_es_build_for_storefront: false
      npm_strict: false

changelog:
  enabled: true

store:
  automatic_bugfix_version_compatibility: true
  # ...

validation:
  ignore:
    - 'xx'
```

When you edit that file in an editor, you will get autocompletion and hints for the available options.

::: info
To programmatically access the configuration schema, use `shopware-cli extension config-schema`. This outputs the JSON schema and is particularly useful for AI agents and automation tools that need to understand the extension configuration structure.
:::

## Compatibility date

You can define a `compatibility_date` in `.shopware-extension.yml`:

```yaml
compatibility_date: '2026-02-11'
```

The `compatibility_date` lets Shopware CLI introduce behavior changes without breaking existing projects by default. New or potentially breaking changes are activated only for configurations that opt in with a date at or after the feature's rollout date.

* Format: `YYYY-MM-DD`
* If the field is missing, Shopware CLI uses `2026-02-11` as fallback
* When missing, Shopware CLI logs a warning during config loading

## Environment variables

Additionally, you can set environment variables to change the behavior of the CLI. The following environment variables are available:

| Environment Variable            | Description                                                                           |
|---------------------------------|---------------------------------------------------------------------------------------|
| CI                              | Detect CI environment                                                                 |
| SHOPWARE\_CLI\_PREVIOUS\_TAG       | Override previous Git tag detection with a previous tag used for Changelog generation |
| CI\_PROJECT\_URL                  | GitLab CI project URL used for Changelog generation                                   |
| SHOPWARE\_CLI\_NO\_SYMFONY\_CLI     | Disable Symfony CLI usage                                                             |
| APP\_ENV                         | Application environment                                                               |
| SHOPWARE\_PROJECT\_ROOT           | Use this Shopware project to build the extension instead of setting up a new project  |
| SHOPWARE\_CLI\_DISABLE\_WASM\_CACHE | Disable the WASM cache for PHP linting                                                |

---

---
url: /docs/products/tools/mcp-server/configuration.md
---

# Configuration

:::info Version requirements
This page describes Shopware 6.7.14.0 and later, where the MCP server is always enabled and progressive tool discovery is active.

On Shopware 6.7.11.0 to 6.7.13.x, the MCP server is gated behind the `MCP_SERVER` feature flag. Set `MCP_SERVER=1` in your `.env` file to enable the endpoint. Those versions advertise every allowed tool in `tools/list`; the discovery tools, tool groups, toolsets, cursor pagination, and `listChanged` notifications do not exist there.

Starting with 6.7.14.0, the flag is removed and has no effect. Remove `MCP_SERVER` from your `.env` file. The MCP classes stay marked as experimental until 6.8.0.
:::

## Shopware MCP configuration

Shopware-specific MCP settings live under the `shopware.mcp` key in `config/packages/shopware.yaml` or any config file loaded in your application:

```yaml
shopware:
    mcp:
        allowed_tools: []       # Empty = all tools allowed. List tool names to restrict globally.
        app_tool_timeout: 10    # Timeout in seconds for app webhook tool calls.
```

These two keys are the complete `shopware.mcp` configuration:

| Key                | Type            | Default | Description                                                             |
|--------------------|-----------------|---------|-------------------------------------------------------------------------|
| `allowed_tools`    | list of strings | `[]`    | Installation-wide tool allowlist applied at compile time. Empty = all.  |
| `app_tool_timeout` | integer         | `10`    | Timeout in seconds for app webhook tool calls. Minimum `1`.             |

Everything else — the endpoint path, server instructions, and list pagination — is configured on the `symfony/mcp-bundle` extension, not under `shopware.mcp`.

### Global tool allowlist

`allowed_tools` is an installation-wide safety switch. It restricts which tools are available across **all** integrations at compile time:

```yaml
shopware:
    mcp:
        allowed_tools:
            - shopware-tool-search
            - shopware-toolsets-list
            - shopware-toolset-enable
            - shopware-entity-schema
            - shopware-entity-search
            - shopware-system-config-read
```

An empty list (the default) means no compile-time restriction; all registered tools are available. When the list is not empty, add the three discovery tools and every domain tool that should remain available globally. The domain tools in the example are only an illustrative subset; you do not need to list every registered tool unless you want all of them available.

Removing the discovery tools at compile time prevents clients from finding and enabling the remaining tools. The per-integration and per-user allowlists in the Administration are the primary controls for day-to-day access management.

:::info Per-principal allowlist
Shopware applies a per-principal MCP allowlist depending on how the client authenticates:

| Auth mode                                | Allowlist source                                                                          |
|------------------------------------------|-------------------------------------------------------------------------------------------|
| Integration access key (`SWIA...`)       | Per-integration allowlist under **Settings → Integrations → Edit MCP Allowlist**          |
| User access key (`SWUA...`)              | Per-user allowlist under **Settings → Users & Permissions → \[user] → MCP tool allowlist** |
| Bearer JWT, password / refresh grant     | Per-user allowlist of the authenticated user                                              |
| Bearer JWT, client\_credentials           | Per-integration allowlist                                                                 |
| Integration + `sw-app-user-id` (Copilot) | Intersection of the integration allowlist and the user allowlist                          |

`null` per key means all capabilities of that type are allowed; a JSON array restricts access to the listed names; an empty array `[]` denies access to that capability type.

The three server-owned discovery tools are the exception for tool allowlists. They remain available so that clients can use the discovery flow, but their search results and toolsets contain only tools permitted by the effective allowlist.

Admin user accounts (`admin = true`) always bypass the allowlist regardless of auth mode. This applies to user accounts, not to integrations created with `--admin` (which bypasses ACL but still respects the per-integration allowlist).
:::

### Delegated user calls (`sw-app-user-id`)

Apps that act on behalf of a logged-in user (for example, a Copilot sidebar embedded in the Admin UI) can pass the `sw-app-user-id` header alongside integration credentials:

```text
sw-access-key: SWIA...
sw-secret-access-key: ...
sw-app-user-id: <user-uuid>
```

The value must be the Shopware user ID (a UUID in hex format, e.g., `01932f3a...`). Apps embedded in the Admin UI can read it from:

* The current session in JavaScript: `Shopware.Store.get('session').currentUser.id`
* The Admin API: `GET /api/_info/me` — the `data.id` field in the response

If the header is absent or invalid (i.e., not a valid UUID), Shopware ignores it and applies only the integration allowlist.

When this header is present, and a valid user UUID is provided, Shopware applies the **intersection** of the integration allowlist and the user allowlist. A tool is only available if both the integration and the user have it enabled:

| Integration allowlist | User allowlist        | Effective allowlist |
|-----------------------|-----------------------|---------------------|
| `null` (unrestricted) | `null` (unrestricted) | unrestricted        |
| `null`                | `[tool-b]`            | `[tool-b]`          |
| `[tool-a, tool-b]`    | `null`                | `[tool-a, tool-b]`  |
| `[tool-a, tool-b]`    | `[tool-b, tool-c]`    | `[tool-b]`          |
| `[tool-a]`            | `[]`                  | `[]` (nothing)      |

Admin users bypass the user side of the intersection — if the user is an admin, their allowlist is treated as `null` (unrestricted), so the integration allowlist alone applies.

This pattern lets the app owner control which tools the integration may ever call, while users control which of those tools they personally allow the app to use on their behalf. Neither side can grant more than what the other has permitted.

## MCP bundle configuration

The underlying `symfony/mcp-bundle` is configured in `config/packages/mcp.php`. Shopware ships this file, and Symfony loads it automatically. You do not need to create or modify it for standard setups.

This file also sets the server `instructions` that clients receive during `initialize`. They tell the agent that the advertised tool list is not the full catalogue and that it should call `shopware-tool-search` before concluding that an action is unsupported.

## Capability list pagination

The `tools/list`, `resources/list`, and `prompts/list` methods use MCP cursor pagination. When a response contains `nextCursor`, pass that value unchanged as `cursor` in the next request. Continue until `nextCursor` is absent.

The default page size is 50 entries. It is the MCP bundle's `pagination_limit` option, not a `shopware.mcp` key. Shopware does not set it, so to change it, configure the `mcp` extension in your own config file:

```yaml
# config/packages/mcp.yaml
mcp:
    pagination_limit: 100
```

Treat cursors as opaque values. Shopware applies the effective allowlist before pagination, so each page contains only capabilities the current principal may access, and a cursor is only meaningful for the principal that received it. An unknown, malformed, or out-of-range cursor is answered with the JSON-RPC error `-32602` and the message `Invalid value for pagination parameter "cursor"`.

In practice `tools/list` rarely paginates: it only contains the discovery tools plus the tools of the toolsets enabled for the current session. `resources/templates/list` is not allowlist-filtered.

## Session store

MCP sessions track an ongoing conversation across multiple requests. The client performs an `initialize` handshake first, then sends subsequent `tools/call` requests referencing that session ID. Session data and enabled toolsets must survive between requests.

Shopware defaults to a file-based session store that writes to `%kernel.cache_dir%/mcp-sessions/`.

Enabled toolsets are stored separately, in the `mcp_toolset_session` database table, keyed on the `Mcp-Session-Id` header only — not per user and not per integration. Rows are deleted when the client ends the session with `DELETE /api/_mcp`. Sessions that are abandoned without a `DELETE` are cleaned up by the daily `mcp_toolset_session.cleanup` scheduled task, so the scheduler must run in production.

| Store                                           | Multi-worker | Multi-server | Backend                                                                       |
|-------------------------------------------------|--------------|--------------|-------------------------------------------------------------------------------|
| `file` (default)                                | No           | No           | `%kernel.cache_dir%/mcp-sessions/`                                            |
| `memory`                                        | No           | No           | Per-process RAM                                                               |
| `cache` (avoid)                                 | No in dev    | No           | `cache.app` (ArrayAdapter in dev)                                             |
| `framework` (unusable in Shopware)              | Yes          | Yes          | Requires active PHP session, not available because the Admin API is stateless |
| Custom Redis store (recommended for production) | Yes          | Yes          | Redis / Valkey                                                                |

### Production: Redis session store

The file store works on a single machine. In a multi-server or Kubernetes environment, `initialize` and subsequent tool calls may land on different workers that do not share a local filesystem. Switch to Redis:

**`config/services.yaml`:**

```yaml
services:
    mcp.session.cache_psr16:
        class: Symfony\Component\Cache\Psr16Cache
        arguments: ['@cache.mcp_sessions']

    mcp.session.store:
        class: Mcp\Server\Session\Psr16SessionStore
        arguments:
            - '@mcp.session.cache_psr16'
            - 3600   # TTL in seconds
```

**`config/packages/framework.yaml`:**

```yaml
framework:
    cache:
        pools:
            cache.mcp_sessions:
                adapter: cache.adapter.redis_tag_aware
                provider: 'redis://your-redis-host:6379'
                default_lifetime: 3600
```

If you already have a Redis/Valkey connection configured for Shopware, set `provider` to the same DSN to avoid opening a second connection.

## ACL and permissions

All MCP tool operations respect the integration's Admin API ACL role. To restrict what an MCP client can do:

1. Create an ACL role in **Settings → Users & Permissions → Roles** with only the required permissions.
2. Assign that role to the integration (omit `--admin` when creating via CLI).
3. Under **Settings → Integrations → Edit MCP Allowlist**, enable only the tools needed for this integration.

The Admin UI surfaces two helpers for getting ACL right:

* The **Role detail** page shows a banner when the role is assigned to MCP-enabled integrations. Click **Show MCP tool requirements** to open the MCP Tool Requirements modal, which lists every privilege required by the allowed tools. Switch between **By Permission** (per-entity view with Grant buttons) and **By Tool** (per-tool view). Use **Grant all missing** to add the missing privileges in one click:

- The **Edit MCP Allowlist** modal groups tools by their tool group — the same taxonomy that becomes a toolset for progressive discovery. Each group has its own checkbox that also reflects partial selections, plus expand and collapse controls, so you can allow a whole toolset in one click. A tool that another selected tool declares as a dependency is included automatically and marked as such. The modal also shows a coverage warning when the assigned role is missing privileges required by an allowed tool:

## CLI: `debug:mcp`

List all registered capabilities:

```bash
bin/console debug:mcp
```

The tool output shows five columns: **Name**, **Group**, **Source**, **Dependencies**, and **Privileges**. It reads from the complete live server registry and covers core and extension tools in one view. The **Group** becomes the toolset name used for progressive discovery.

The command prints separate sections for **Tools**, **Prompts**, **Resources**, and **Resource Templates**. It covers the Admin API server only; Store API capabilities are not listed — see [Store API MCP](./store-api.md).

Filter by capability type:

```bash
bin/console debug:mcp --tools      # tools only
bin/console debug:mcp --prompts    # prompts only
bin/console debug:mcp --resources  # resources only
```

Drill into a single capability by name:

```bash
bin/console debug:mcp shopware-entity-search
```

See the registry from a specific integration's perspective (honors its per-integration allowlist):

```bash
bin/console debug:mcp --integration=SWIA...
```

If a tool is missing from this output, it is also missing from the live endpoint. Common causes:

* Plugin is not installed or activated
* Service tag is missing (`shopware.mcp.tool`)
* `#[McpTool]` attribute is on `__invoke()` instead of the class
* App tool's webhook URL is not reachable

## Rate limiting

Both MCP endpoints are rate limited with their own buckets, configured under `shopware.api.rate_limiter` in `config/packages/shopware.yaml`. Rate limiting protects the endpoints from brute-force attempts and runaway agent loops.

| Bucket           | Endpoint          | Keyed on                                    | Limits                                |
|------------------|-------------------|---------------------------------------------|---------------------------------------|
| `mcp_admin_api`  | `/api/_mcp`       | Access token, falling back to client IP     | 300 per minute, 1000 per 10 minutes   |
| `mcp_store_api`  | `/store-api/_mcp` | Sales channel and context token, plus client IP | 120 per minute, 600 per 10 minutes |

Both use the `time_backoff` policy and reset after one hour. Exceeding a limit returns HTTP 429 with the remaining wait time in the response body; no `Retry-After` header is sent.

---

---
url: /docs/v6.5/guides/plugins/apps/configuration.md
---

# Configuration

::: info
Configurations for apps adhere to the same schema as [Plugin Configurations](../plugins/plugin-fundamentals/add-plugin-configuration).
:::

To offer configuration possibilities to your users you can provide a `config.xml` file that describes your configuration options. You can find detailed information about the possibilities and the structure of the `config.xml` in the according documentation page. To include a `config.xml` file in your app put it into the `Resources/config` folder:

```text
...
└── DemoApp
      └── Resources
            └── config  
                  └── config.xml
      └── manifest.xml
```

The configuration page will be displayed in the Administration under `Extensions > My extensions`.
For development purposes you can use the Administration component to configure plugins to provide configuration for your app, therefore use the URL `{APP_URL}/admin#/sw/extension/config/{appName}`.

## Reading the configuration values

The configuration values are saved as part of the `SystemConfig` and you can use the key `{appName}.config.{fieldName}` to identify the values. There are two possibilities to access the configuration values from your app. If you need those values on your app-backend server, you can read them over the API. If you need the configuration values in your Storefront twig templates you can use the `systemConfig()`-twig function.

### Reading the config over the API

To access your apps configuration over the API make a GET request against the `/api/_action/system-config` route. You have to add the prefix for your configuration as the `domain` query parameter. Optionally you can provide a `SalesChannelId`, if you want to read the values for a specific SalesChannel, as the `salesChannelId` query param. The API call will return a JSON-Object containing all of your configuration values. A sample Request and Response may look like this.

```txt
GET /api/_action/system-config?domain=DemoApp.config&salesChannelId=98432def39fc4624b33213a56b8c944d

{
    "DemoApp.config.field1": true,
    "DemoApp.config.field2": "successfully configured"
}
```

::: warning
Keep in mind that your app needs the `system_config:read` permission to access this API.
:::

### Writing the config over the API

To write your app's configuration over the API, make a `POST`request against the `/api/_action/system-config` route.
You have to provide the configurations as JSON object and optionally provide a `salesChannelId` query param, if you want to write the values for a specific Sales Channel.

```txt
POST /api/_action/system-config?salesChannelId=98432def39fc4624b33213a56b8c944d
Content-Type: application/json

{
    "DemoApp.config.field1": true
}
```

::: warning
Keep in mind that your app needs the `system_config:update`, `system_config:create` and `system_config:delete` permission to access this API.
:::

### Reading the config in templates

Inside twig templates you can use the twig function `config` (see [Shopware Twig functions](../../../resources/references/storefront-reference/twig-function-reference)). An example twig template could look like this:

```twig
{{ config('DemoApp.config.field1') }}
```

### Reading the config in app scripts

In app scripts you have access to the [`config` service](../../../resources/references/app-reference/script-reference/miscellaneous-script-services-reference#SystemConfigFacade), that can be used to access config values.

::: info
Note that app scripts were introduced in Shopware 6.4.8.0, and are not supported in previous versions.
:::

The `config` service provides an `app()` method, that can be used to access your app's configuration. When using this method you don't need to provide the `{appName}.config` prefix and your app does not need any additional permissions.

```twig
{% set configValue = services.config.app('field1') %}
```

Additionally, you can use the `get()` method, to access any configuration value and not just the ones of your app.

::: warning
Keep in mind that your app needs the `system_config:read` permission to use the `config.get()` method.
:::

```twig
{% set configValue = services.config.get('core.listing.productsPerPage') %}
```

For a detailed description about app scripts refer to this [guide](./app-scripts/).

For a full description of the `config` service take a look at the [service's reference](../../../resources/references/app-reference/script-reference/miscellaneous-script-services-reference#servicesconfig-shopwarecoresystemsystemconfigfacadesystemconfigfacade).

---

---
url: /docs/v6.5/products/digital-sales-rooms/configuration.md
---

# Configuration

There are a lot of settings on the configuration page, but most of them are already filled by default. However, there are some settings that need to be setup.

## Navigate to the configuration page

Open Shopware CMS, select Marketing > Digital Sales Rooms > Configuration

![ ](../../assets/products-digitalSalesRooms-configuration.png)

## Fill the settings

### Appointments

* *Default appointment domain* - This select box shows the list of domains of all sale channels. You should choose the *Digital Sales Rooms* domain from [this section](./installation/app-installation.md#setup-sales-channel-for-dsr)

### Video and Audio

* *API base url* - use value `https://api.daily.co/v1/`
* *API key* - get the value from [this section](./installation/realtime-video-dailyco.md##get-the-api-key)

### Realtime service

* *Hub url* - get the value from [this section](./installation/realtime-service-mercure.md#setup-via-stackhero-recommended)
* *Hub public url* - get the value from [this section](./installation/realtime-service-mercure.md#setup-via-stackhero-recommended)
* *Hub subscriber secret* - get the value from [this section](./installation/realtime-service-mercure.md#setup-via-stackhero-recommended)
* *Hub publisher secret* - get the value from [this section](./installation/realtime-service-mercure.md#setup-via-stackhero-recommended)

---

---
url: /docs/v6.6/guides/plugins/apps/configuration.md
---

# Configuration

::: info
Configurations for apps adhere to the same schema as [Plugin Configurations](../plugins/plugin-fundamentals/add-plugin-configuration).
:::

To offer configuration possibilities to your users you can provide a `config.xml` file that describes your configuration options. You can find detailed information about the possibilities and the structure of the `config.xml` in the according documentation page. To include a `config.xml` file in your app put it into the `Resources/config` folder:

```text
...
└── DemoApp
      └── Resources
            └── config  
                  └── config.xml
      └── manifest.xml
```

The configuration page will be displayed in the Administration under `Extensions > My extensions`.
For development purposes you can use the Administration component to configure plugins to provide configuration for your app, therefore use the URL `{APP_URL}/admin#/sw/extension/config/{appName}`.

## Reading the configuration values

The configuration values are saved as part of the `SystemConfig` and you can use the key `{appName}.config.{fieldName}` to identify the values. There are two possibilities to access the configuration values from your app. If you need those values on your app-backend server, you can read them over the API. If you need the configuration values in your Storefront twig templates you can use the `systemConfig()`-twig function.

### Reading the config over the API

To access your apps configuration over the API make a GET request against the `/api/_action/system-config` route. You have to add the prefix for your configuration as the `domain` query parameter. Optionally you can provide a `SalesChannelId`, if you want to read the values for a specific SalesChannel, as the `salesChannelId` query param. The API call will return a JSON-Object containing all of your configuration values. A sample Request and Response may look like this.

```txt
GET /api/_action/system-config?domain=DemoApp.config&salesChannelId=98432def39fc4624b33213a56b8c944d

{
    "DemoApp.config.field1": true,
    "DemoApp.config.field2": "successfully configured"
}
```

::: warning
Keep in mind that your app needs the `system_config:read` permission to access this API.
:::

### Writing the config over the API

To write your app's configuration over the API, make a `POST`request against the `/api/_action/system-config` route.
You have to provide the configurations as JSON object and optionally provide a `salesChannelId` query param, if you want to write the values for a specific Sales Channel.

```txt
POST /api/_action/system-config?salesChannelId=98432def39fc4624b33213a56b8c944d
Content-Type: application/json

{
    "DemoApp.config.field1": true
}
```

::: warning
Keep in mind that your app needs the `system_config:update`, `system_config:create` and `system_config:delete` permission to access this API.
:::

### Reading the config in templates

Inside twig templates you can use the twig function `config` (see [Shopware Twig functions](../../../resources/references/storefront-reference/twig-function-reference)). An example twig template could look like this:

```twig
{{ config('DemoApp.config.field1') }}
```

### Reading the config in app scripts

In app scripts you have access to the [`config` service](../../../resources/references/app-reference/script-reference/miscellaneous-script-services-reference#SystemConfigFacade), that can be used to access config values.

::: info
Note that app scripts were introduced in Shopware 6.4.8.0, and are not supported in previous versions.
:::

The `config` service provides an `app()` method, that can be used to access your app's configuration. When using this method you don't need to provide the `{appName}.config` prefix and your app does not need any additional permissions.

```twig
{% set configValue = services.config.app('field1') %}
```

Additionally, you can use the `get()` method, to access any configuration value and not just the ones of your app.

::: warning
Keep in mind that your app needs the `system_config:read` permission to use the `config.get()` method.
:::

```twig
{% set configValue = services.config.get('core.listing.productsPerPage') %}
```

For a detailed description about app scripts refer to this [guide](./app-scripts/).

For a full description of the `config` service take a look at the [service's reference](../../../resources/references/app-reference/script-reference/miscellaneous-script-services-reference#servicesconfig-shopwarecoresystemsystemconfigfacadesystemconfigfacade).

---

---
url: /docs/v6.6/products/cli/extension-commands/configuration.md
---

# Configuration

Many configurations can be changed using a `.shopware-extension.yml` file in the root of your extension.

Here is an example of a `.shopware-extension.yml` file:

```yaml
build:
  extraBundles:
    - path: src/Foo
    - name: OverrideName
      path: src/Override
  shopwareVersionConstraint: '~6.6.0'
  zip:
    assets:
      enabled: false
      before_hooks: []
      after_hooks: []
      disable_sass: false
      enable_es_build_for_admin: false
      enable_es_build_for_storefront: false
      npm_strict: false

changelog:
  enabled: true

store:
  automatic_bugfix_version_compatibility: true
  # ...

validation:
  ignore:
    - 'xx'
```

When you edit that file in an editor, you will get autocompletion and hints for the available options.

## Environment variables

Additionally, you can set environment variables to change the behavior of the CLI. The following environment variables are available:

| Environment Variable            | Description                                                                           |
|---------------------------------|---------------------------------------------------------------------------------------|
| CI                              | Detect CI environment                                                                 |
| SHOPWARE\_CLI\_PREVIOUS\_TAG       | Override previous Git tag detection with a previous tag used for Changelog generation |
| CI\_PROJECT\_URL                  | GitLab CI project URL used for Changelog generation                                   |
| SHOPWARE\_CLI\_NO\_SYMFONY\_CLI     | Disable Symfony CLI usage                                                             |
| APP\_ENV                         | Application environment                                                               |
| SHOPWARE\_PROJECT\_ROOT           | Use this Shopware project to build the extension instead of setting up a new project  |
| SHOPWARE\_CLI\_DISABLE\_WASM\_CACHE | Disable the WASM cache for PHP linting                                                |

---

---
url: >-
  /docs/products/extensions/b2b-suite-migration/development/validation-and-run.md
---

# Configuration Validation and Migration Execution

After configuring your migration, follow these steps:

1. Validate the configuration:
   Validate your migration configuration to ensure correctness before running the migration.

   ```bash
   bin/console b2b:migrate:validate
   ```

   * Checks the configuration for errors. Ensure the XML is well-formed and adheres to a valid schema. It will also verify if the fields and tables exist in the database; otherwise, it will throw an exception.
   * Provides hints to resolve issues if validation fails.

   ::: info
   Validation helps catch configuration errors early, saving time during migration.
   :::

2. Monitor progress (should be run in a separate terminal):

   ```bash
   bin/console b2b:migrate:progress --watch
   ```

3. Start the migration (ensure the queue worker is running):

   ```bash
   bin/console b2b:migrate:commercial
   ```

4. Review logs and errors in `b2b_components_migration_errors` to ensure a successful migration.

5. In case you want to roll back the migration, use:

   ```bash
   bin/console b2b:migrate:rollback
   ```

---

---
url: /docs/guides/hosting/configurations.md
---

# Configurations

## Overview

When running Shopware 6 there are various configuration options you can use to customize your installation.

## Configuration

The configuration for Shopware 6 resides in the general bundle configuration:

```text
<project root>
└── config
   └── packages
      └── shopware.yaml
```

If you want to aim at a specific environment, you can create a configuration file for that as follows:

```text
<project root>
└── config
   └── packages
      └── dev
         └── mailer.yaml
```

```text
<project root>
└── config
   └── packages
      └── prod
         └── mailer.yaml
```

For more information on environment-specific configurations, check out the [Symfony Configuration Environments](https://symfony.com/doc/current/configuration.html#configuration-environments) section.

---

---
url: /docs/v6.5/guides/hosting/configurations.md
---

# Configurations

## Overview

When running Shopware 6 there are various configuration options you can use to customize your installation. This page will give you an overview of the different configuration options and how they effect Shopware.

## Configuration

The configuration for Shopware 6 resides in the general bundle configuration:

```text
<project root>
└── config
   └── packages
      └── shopware.yaml
```

---

---
url: /docs/v6.6/guides/hosting/configurations.md
---

# Configurations

## Overview

When running Shopware 6 there are various configuration options you can use to customize your installation.

## Configuration

The configuration for Shopware 6 resides in the general bundle configuration:

```text
<project root>
└── config
   └── packages
      └── shopware.yaml
```

If you want to aim at a specific environment, you can create a configuration file for that as follows:

```text
<project root>
└── config
   └── packages
      └── dev
         └── mailer.yaml
```

```text
<project root>
└── config
   └── packages
      └── prod
         └── mailer.yaml
```

For more information on environment-specific configurations, check out the [Symfony Configuration Environments](https://symfony.com/doc/current/configuration.html#configuration-environments) section.

---

---
url: >-
  /docs/v6.6/products/cli/shopware-account-commands/configure-composer-repository.md
---

# Configure composer repository

To install extensions from the Shopware Store, you need to configure the Composer repository in your `composer.json` file. Shopware CLI can configure this for you automatically.

First, make sure you have access to the given Shop in Shopware Account. You can check this with the following command:

```bash
shopware-cli account merchant shop list
```

If you don't see the shop you want to use, you need to switch to the correct company with the following command. Check the [Authentication](./authentication.md) guide for more information.

To create a `auth.json` file with the Composer repository configuration, you can use the following command:

::: info
You can also use the tab completion in the terminal to get the domains of the shops you have access to.
:::

```bash
shopware-cli account merchant shop configure-composer <domain>
```

This will create `auth.json` and append the Composer repository configuration to your `composer.json` file.

---

---
url: >-
  /docs/products/extensions/advanced-search/How-to-configure-searchable-fields.md
---

# Configure Searchable Fields

Search entities and their searchable fields are stored in `advanced_search_config` and `advanced_search_config_field` table respectively.

These configured fields help to build the search query when a search/suggest request is sent from the client.

This approach is very similar to how `product_search_config` and `product_search_config_field` work in the platform. The main difference is you can configure the configuration by sales channel instead of by language (each sales channel now has its own search config).

@Refer:

`\Shopware\Commercial\AdvancedSearch\Entity\AdvancedSearchConfig\AdvancedSearchConfigDefinition`
`\Shopware\Commercial\AdvancedSearch\Entity\AdvancedSearchConfig\Aggregate\AdvancedSearchConfigFieldDefinition`

To have the custom search configuration, you need to add a migration to insert the configuration into the database. In the below example, we add default search configuration for product, manufacturer, and category entities

@Refer: `\Shopware\Commercial\Migration\Migration1680751315SWAGAdvancedSearch_AddAdvancedSearchConfigurationDefaults`

And you might want to add the configuration for newly created saleschannel as well:
@Refer: `\Shopware\Commercial\AdvancedSearch\Subscriber\SalesChannelCreatedSubscriber`

---

---
url: >-
  /docs/v6.5/products/extensions/advanced-search/How-to-configure-searchable-fields.md
---

# Configure Searchable Fields

Search entities and their searchable fields are stored in `advanced_search_config` and `advanced_search_config_field` table respectively.

These configured fields help to build the search query when a search/suggest request is sent from the client.

This approach is very similar to how `product_search_config` and `product_search_config_field` work in the platform. The main difference is you can configure the configuration by sales channel instead of by language (each sales channel now has its own search config).

@Refer:

`\Shopware\Commercial\AdvancedSearch\Entity\AdvancedSearchConfig\AdvancedSearchConfigDefinition`
`\Shopware\Commercial\AdvancedSearch\Entity\AdvancedSearchConfig\Aggregate\AdvancedSearchConfigFieldDefinition`

To have the custom search configuration, you need to add a migration to insert the configuration into the database. In the below example, we add default search configuration for product, manufacturer, and category entities

@Refer: `\Shopware\Commercial\Migration\Migration1680751315SWAGAdvancedSearch_AddAdvancedSearchConfigurationDefaults`

And you might want to add the configuration for newly created saleschannel as well:
@Refer: `\Shopware\Commercial\AdvancedSearch\Subscriber\SalesChannelCreatedSubscriber`

---

---
url: >-
  /docs/v6.6/products/extensions/advanced-search/How-to-configure-searchable-fields.md
---

# Configure Searchable Fields

Search entities and their searchable fields are stored in `advanced_search_config` and `advanced_search_config_field` table respectively.

These configured fields help to build the search query when a search/suggest request is sent from the client.

This approach is very similar to how `product_search_config` and `product_search_config_field` work in the platform. The main difference is you can configure the configuration by sales channel instead of by language (each sales channel now has its own search config).

@Refer:

`\Shopware\Commercial\AdvancedSearch\Entity\AdvancedSearchConfig\AdvancedSearchConfigDefinition`
`\Shopware\Commercial\AdvancedSearch\Entity\AdvancedSearchConfig\Aggregate\AdvancedSearchConfigFieldDefinition`

To have the custom search configuration, you need to add a migration to insert the configuration into the database. In the below example, we add default search configuration for product, manufacturer, and category entities

@Refer: `\Shopware\Commercial\Migration\Migration1680751315SWAGAdvancedSearch_AddAdvancedSearchConfigurationDefaults`

And you might want to add the configuration for newly created saleschannel as well:
@Refer: `\Shopware\Commercial\AdvancedSearch\Subscriber\SalesChannelCreatedSubscriber`

---

---
url: /resources/admin-extension-sdk/api-reference/consent.md
---
# Consent

:::caution
The consent API is experimental. Behavior, payloads, and availability may still change in upcoming Shopware versions.
:::

> Available since Shopware v6.7.10.0

The `sw.consent` API can be used to inspect the current state of a consent and to trigger a consent request flow in the Administration.

`sw.consent.status()` returns a `Promise<Consent>`.
`sw.consent.request()` returns an object with:

* `requestPromise: Promise<Consent>`
* `abort: (reason: unknown) => void`

## `Consent`

`Consent` is the value object returned by the consent API. It represents the current state of a consent in Shopware.

### Properties

| Name | Type | Description |
| :------ | :------ | :------ |
| `name` | `string` | Technical name of the consent. |
| `status` | `'unset' \| 'declined' \| 'revoked' \| 'accepted'` | Current consent status. |
| `updatedAt` | `string \| null` | Timestamp of the last consent state update. |
| `acceptedRevision` | `string \| null` | Revision that was accepted by the user. |
| `lastRevision` | `string \| null` | Latest known revision of the consent. |

### Derived flags

| Name | Type | Description |
| :------ | :------ | :------ |
| `isAccepted` | `boolean` | `true` when the current status is `accepted`. |
| `isStale` | `boolean` | `true` when the consent is accepted, but the accepted revision differs from the latest revision. |

### Example

```ts
const consent = await sw.consent.status({
  consent: 'product_analytics',
});

if (consent.isAccepted && !consent.isStale) {
  console.log(`Consent "${consent.name}" is up to date.`);
}
```

## Get consent status

Read the current state of a consent without opening a consent prompt.

#### Usage

```ts
const consent = await sw.consent.status({
  consent: 'product_analytics',
});
```

#### Parameters

| Name | Required | Description |
| :------ | :------ | :------ |
| `consent` | true | Technical name of the consent to load. |

#### Return value

```ts
Promise<Consent>
```

#### Example value

```ts
{
  name: 'product_analytics',
  status: 'accepted',
  updatedAt: '2026-04-13T11:00:00.000Z',
  acceptedRevision: '2026-03-01',
  lastRevision: '2026-05-01',
  isAccepted: true,
  isStale: true,
}
```

## Request consent

Trigger the consent request flow in the Administration and resolve with the resulting consent state.

#### Usage

```ts
const { requestPromise } = sw.consent.request({
  consent: 'product_analytics',
  requestMessage: 'Please confirm that we may track Admin usage data.',
  privacyLink: 'https://www.shopware.com/en/privacy/dpa/',
});

const consent = await requestPromise;
```

#### Parameters

| Name | Required | Description |
| :------ | :------ | :------ |
| `consent` | true | Technical name of the consent to request. |
| `requestMessage` | false | Optional message shown together with the consent request. |
| `privacyLink` | false | Optional link to the privacy policy or related information. |

#### Return value

```ts
{
  requestPromise: Promise<Consent>,
  abort: (reason: unknown) => void,
}
```

`requestPromise` resolves when Shopware sends back the matching consent response.

#### Abort example

```ts
const { requestPromise, abort } = sw.consent.request({
  consent: 'product_analytics',
});

const timeout = setTimeout(() => {
  abort(new Error('Consent request timed out'));
}, 5000);

try {
  const consent = await requestPromise;
  console.log(consent.status);
} catch (error) {
  console.error(error);
} finally {
  clearTimeout(timeout);
}
```

---

---
url: >-
  /docs/resources/references/adr/2022-02-28-consistent-deprecation-notices-in-core.md
---

# Consistent deprecation notices in Core

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-02-28-consistent-deprecation-notices-in-core.md)
:::

## Context

Currently, we use `@deprecated` annotations to warn 3rd party developers that we will introduce some breaking change in the next major version.
This annotation instructs the IDE to warn the developer that the method/class is deprecated, but has no consequences at runtime.

PHP/Symfony has also a built-in runtime deprecation mechanism with `trigger_deprecation`. This is only used sparsely in the core in `Feature::triggerDeprecated()`.

## Decision

In the future we will use both `@deprecated` and runtime deprecation notices over `trigger_deprecation`.
This means wherever a `@deprecated` annotation is used we will also throw a deprecation notice.

The deprecation notices can be thrown conditionally, e.g., when a new parameter in a method will become required, we will only throw the deprecation if the method is called in the old/deprecated way.
If it is already used in the new way, there is no need to trigger the deprecation.

This has the benefit that 3rd party developers get deprecation notices during runtime with a concrete deprecation message and the stacktrace where the deprecation was triggered.
This is useful, e.g., to run the test suite of a plugin against a new shopware version to get a list of all deprecations.

Additionally, we can use this to provide better feedback to 3rd party developers, e.g., if App Scripts use a deprecated method/class or if some private apps in the cloud rely on deprecated functionality.

### Ensuring the correct usage during CI

To ensure that this guideline is followed, we add a step in the CI (e.g., a custom PHPStan rule or a special unit test) that checks that every method that has a `@deprecated` annotation triggers also a deprecation notice, and vice versa.

There are some special cases where we use a `@deprecated` annotation, but a according triggered deprecation notice makes no sense:

* Classes/methods marked as deprecated, because they will be considered `internal` starting with the next major version.
* Methods are deprecated because the return type will change.
  For both cases we will add special keywords to the `@deprecated` annotation and our CI-check will skip those annotations.

### Common Implementation

We will add a common implementation inside the core that should be used everywhere. This makes it easier to change the deprecation handling later on in a single place and makes it possible to provide custom deprecation warnings, e.g., for app scripts inside Symfony's debug toolbar.

The new method will accept the deprecation message as string and the feature flag of the major version, where the deprecation will be removed.
The method will then trigger a deprecation notice if the major feature flag is not active. If the flag is active, it will throw an exception instead.
This ensures that we inside the core don't rely on deprecated functionality as we have a test-pipeline where the major feature flag is set to true.

A POC implementation in the `Feature`-class can look something like this:

```php
    public static function triggerDeprecationOrThrow(string $message, string $majorFlag): void
    {
        if (self::isActive($majorFlag) || !self::has($majorFlag)) {
            throw new \RuntimeException('Deprecated Functionality: ' . $message);
        }

        trigger_deprecation('', '', $message);
    }
```

Additionally, we will deprecate the `triggerDeprecated()` method, because it will only trigger deprecation messages if the feature flag is active, but in that case the deprecated code will already be removed and the deprecation message never thrown.

### Consistent deprecation notice format

To be as useful as possible, we should use a consistent format for the deprecation messages.

Most importantly, we should ensure that the following information is present in the deprecation message:

* The name of the method/class that is deprecated
* The version in which the deprecation will be removed and the announced changes will be applied
* What to do instead to get rid of the deprecation, e.g., using another method/class or provide an additional param etc.

As an example:

* **Bad:** Will be removed, use NewFeature::method() instead
* **Good:** Method OldFeature::method() will be removed in v6.5.0.0, use NewFeature::method() instead

---

---
url: >-
  /docs/v6.5/resources/references/adr/2022-02-28-consistent-deprecation-notices-in-core.md
---

# Consistent deprecation notices in Core

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-02-28-consistent-deprecation-notices-in-core.md)
:::

## Context

Currently, we use `@deprecated` annotations to warn 3rd party developers that we will introduce some breaking change in the next major version.
This annotation instructs the IDE to warn the developer that the method/class is deprecated, but has no consequences at runtime.

PHP/Symfony has also a built-in runtime deprecation mechanism with `trigger_deprecation`. This is only used sparsely in the core in `Feature::triggerDeprecated()`.

## Decision

In the future we will use both `@deprecated` and runtime deprecation notices over `trigger_deprecation`.
This means wherever a `@deprecated` annotation is used we will also throw a deprecation notice.

The deprecation notices can be thrown conditionally, e.g., when a new parameter in a method will become required, we will only throw the deprecation if the method is called in the old/deprecated way.
If it is already used in the new way, there is no need to trigger the deprecation.

This has the benefit that 3rd party developers get deprecation notices during runtime with a concrete deprecation message and the stacktrace where the deprecation was triggered.
This is useful, e.g., to run the test suite of a plugin against a new shopware version to get a list of all deprecations.

Additionally, we can use this to provide better feedback to 3rd party developers, e.g., if App Scripts use a deprecated method/class or if some private apps in the cloud rely on deprecated functionality.

### Ensuring the correct usage during CI

To ensure that this guideline is followed, we add a step in the CI (e.g., a custom PHPStan rule or a special unit test) that checks that every method that has a `@deprecated` annotation triggers also a deprecation notice, and vice versa.

There are some special cases where we use a `@deprecated` annotation, but a according triggered deprecation notice makes no sense:

* Classes/methods marked as deprecated, because they will be considered `internal` starting with the next major version.
* Methods are deprecated because the return type will change.
  For both cases we will add special keywords to the `@deprecated` annotation and our CI-check will skip those annotations.

### Common Implementation

We will add a common implementation inside the core that should be used everywhere. This makes it easier to change the deprecation handling later on in a single place and makes it possible to provide custom deprecation warnings, e.g., for app scripts inside Symfony's debug toolbar.

The new method will accept the deprecation message as string and the feature flag of the major version, where the deprecation will be removed.
The method will then trigger a deprecation notice if the major feature flag is not active. If the flag is active, it will throw an exception instead.
This ensures that we inside the core don't rely on deprecated functionality as we have a test-pipeline where the major feature flag is set to true.

A POC implementation in the `Feature`-class can look something like this:

```php
    public static function triggerDeprecationOrThrow(string $message, string $majorFlag): void
    {
        if (self::isActive($majorFlag) || !self::has($majorFlag)) {
            throw new \RuntimeException('Deprecated Functionality: ' . $message);
        }

        trigger_deprecation('', '', $message);
    }
```

Additionally, we will deprecate the `triggerDeprecated()` method, because it will only trigger deprecation messages if the feature flag is active, but in that case the deprecated code will already be removed and the deprecation message never thrown.

### Consistent deprecation notice format

To be as useful as possible, we should use a consistent format for the deprecation messages.

Most importantly, we should ensure that the following information is present in the deprecation message:

* The name of the method/class that is deprecated
* The version in which the deprecation will be removed and the announced changes will be applied
* What to do instead to get rid of the deprecation, e.g., using another method/class or provide an additional param etc.

As an example:

* **Bad:** Will be removed, use NewFeature::method() instead
* **Good:** Method OldFeature::method() will be removed in v6.5.0.0, use NewFeature::method() instead

---

---
url: >-
  /docs/v6.6/resources/references/adr/2022-02-28-consistent-deprecation-notices-in-core.md
---

# Consistent deprecation notices in Core

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2022-02-28-consistent-deprecation-notices-in-core.md)
:::

## Context

Currently, we use `@deprecated` annotations to warn 3rd party developers that we will introduce some breaking change in the next major version.
This annotation instructs the IDE to warn the developer that the method/class is deprecated, but has no consequences at runtime.

PHP/Symfony has also a built-in runtime deprecation mechanism with `trigger_deprecation`. This is only used sparsely in the core in `Feature::triggerDeprecated()`.

## Decision

In the future we will use both `@deprecated` and runtime deprecation notices over `trigger_deprecation`.
This means wherever a `@deprecated` annotation is used we will also throw a deprecation notice.

The deprecation notices can be thrown conditionally, e.g., when a new parameter in a method will become required, we will only throw the deprecation if the method is called in the old/deprecated way.
If it is already used in the new way, there is no need to trigger the deprecation.

This has the benefit that 3rd party developers get deprecation notices during runtime with a concrete deprecation message and the stacktrace where the deprecation was triggered.
This is useful, e.g., to run the test suite of a plugin against a new shopware version to get a list of all deprecations.

Additionally, we can use this to provide better feedback to 3rd party developers, e.g., if App Scripts use a deprecated method/class or if some private apps in the cloud rely on deprecated functionality.

### Ensuring the correct usage during CI

To ensure that this guideline is followed, we add a step in the CI (e.g., a custom PHPStan rule or a special unit test) that checks that every method that has a `@deprecated` annotation triggers also a deprecation notice, and vice versa.

There are some special cases where we use a `@deprecated` annotation, but a according triggered deprecation notice makes no sense:

* Classes/methods marked as deprecated, because they will be considered `internal` starting with the next major version.
* Methods are deprecated because the return type will change.
  For both cases we will add special keywords to the `@deprecated` annotation and our CI-check will skip those annotations.

### Common Implementation

We will add a common implementation inside the core that should be used everywhere. This makes it easier to change the deprecation handling later on in a single place and makes it possible to provide custom deprecation warnings, e.g., for app scripts inside Symfony's debug toolbar.

The new method will accept the deprecation message as string and the feature flag of the major version, where the deprecation will be removed.
The method will then trigger a deprecation notice if the major feature flag is not active. If the flag is active, it will throw an exception instead.
This ensures that we inside the core don't rely on deprecated functionality as we have a test-pipeline where the major feature flag is set to true.

A POC implementation in the `Feature`-class can look something like this:

```php
    public static function triggerDeprecationOrThrow(string $message, string $majorFlag): void
    {
        if (self::isActive($majorFlag) || !self::has($majorFlag)) {
            throw new \RuntimeException('Deprecated Functionality: ' . $message);
        }

        trigger_deprecation('', '', $message);
    }
```

Additionally, we will deprecate the `triggerDeprecated()` method, because it will only trigger deprecation messages if the feature flag is active, but in that case the deprecated code will already be removed and the deprecation message never thrown.

### Consistent deprecation notice format

To be as useful as possible, we should use a consistent format for the deprecation messages.

Most importantly, we should ensure that the following information is present in the deprecation message:

* The name of the method/class that is deprecated
* The version in which the deprecation will be removed and the announced changes will be applied
* What to do instead to get rid of the deprecation, e.g., using another method/class or provide an additional param etc.

As an example:

* **Bad:** Will be removed, use NewFeature::method() instead
* **Good:** Method OldFeature::method() will be removed in v6.5.0.0, use NewFeature::method() instead

---

---
url: /docs/concepts/commerce/content.md
---

# Content

Shopware 6 has an integrated content management system based upon layouts which is called *Shopping Experiences*. The tool used to compose and manage layouts is part of the [Admin panel](../../framework/architecture/administration-concept) and referred to as *Page Builder*.

Beyond content management, Shopware also provides [Cookie Consent Management](cookie-consent-management) with features to help support GDPR compliance by handling customer privacy preferences and cookie handling transparently.

---

---
url: /docs/guides/plugins/apps/content.md
---

# Content

With apps, you can assign content to specific categories, create layouts, and control content visibility based on various conditions.
This provides a flexible, intuitive way to manage and present your store content, helping you deliver a seamless, engaging customer experience.

---

---
url: /docs/guides/plugins/plugins/content.md
---

# Content

Content feature in Shopware encompasses the essential capabilities related to managing and enhancing content within the e-commerce platform, including content management, email management, SEO optimization, sitemap generation, and media management. These functions enhance website content, facilitate effective communication, improve search engine visibility, and streamline media organization within the e-commerce platform. While these functions are typically available within the core Shopware system, plugins offer the flexibility to extend or customize them based on specific business needs and content strategies.

---

---
url: /docs/v6.5/concepts/commerce/content.md
---

# Content

Shopware 6 has an integrated content management system based upon layouts which is called *Shopping Experiences*. The tool used to compose and manage layouts is part of the [Admin panel](../../framework/architecture/administration-concept) and referred to as *Page Builder*.

---

---
url: /docs/v6.5/guides/plugins/apps/content.md
---

# Content

create layouts, and control the visibility of content based on various conditions. It provides a flexible and intuitive system for managing and presenting your store's content, helping you deliver a seamless and engaging customer experience.

The following section guides how to extend Shopware CMS via a custom app.

---

---
url: /docs/v6.5/guides/plugins/plugins/content.md
---

# Content

Content feature in Shopware encompasses the essential capabilities related to managing and enhancing content within the e-commerce platform, including content management, email management, SEO optimization, sitemap generation, and media management. These functions enhance website content, facilitate effective communication, improve search engine visibility, and streamline media organization within the e-commerce platform. While these functions are typically available within the core Shopware system, plugins offer the flexibility to extend or customize them based on specific business needs and content strategies.

---

---
url: /docs/v6.6/concepts/commerce/content.md
---

# Content

Shopware 6 has an integrated content management system based upon layouts which is called *Shopping Experiences*. The tool used to compose and manage layouts is part of the [Admin panel](../../framework/architecture/administration-concept) and referred to as *Page Builder*.

---

---
url: /docs/v6.6/guides/plugins/apps/content.md
---

# Content

create layouts, and control the visibility of content based on various conditions. It provides a flexible and intuitive system for managing and presenting your store's content, helping you deliver a seamless and engaging customer experience.

The following section guides how to extend Shopware CMS via a custom app.

---

---
url: /docs/v6.6/guides/plugins/plugins/content.md
---

# Content

Content feature in Shopware encompasses the essential capabilities related to managing and enhancing content within the e-commerce platform, including content management, email management, SEO optimization, sitemap generation, and media management. These functions enhance website content, facilitate effective communication, improve search engine visibility, and streamline media organization within the e-commerce platform. While these functions are typically available within the core Shopware system, plugins offer the flexibility to extend or customize them based on specific business needs and content strategies.

---

---
url: /docs/guides/development/testing/store/content-and-translations.md
---

# Content and translations

Listing text, translations, previews, and account profile content for the Shopware Store. For HTML and technical packaging issues, see [Common Store review errors](./store-review-errors.md).

## Store listing

All extensions must:

* Be published in the international store. Publication in the German Store is optional. If the extension should also be available in the German Store, there must be a 1:1 translation between English and German.
* **Short description** (150–185 characters): Teaser in overviews, “Customers also bought” / “Customers also viewed,” and published as the meta description.
* **Long description** (minimum 200 characters): Describe functionality in detail; must match 1:1 between English and German where both are used.
* Use meaningful short and long descriptions.
* Accurately and clearly describe the extension and its use cases.
* Avoid the words “plugin” and “shopware” in the display name.
* Avoid blank spaces as filler text.
* Include clear, complete setup and configuration instructions.
* Use clean HTML source code. Inline styles in the description will be stripped.

Allowed HTML tags:

```markdown
<a> <p> <br> <b> <strong> <i> <ul> <ol> <li> <h2> <h3> <h4> <h5>
```

There must be no advertising for your own services or contact information in the Administration, description, or images. Links that encourage contact are not permitted, including support email addresses and backlinks.

### Images and screenshots

* Use English-only screenshots for the English store listing and preview images.
* Do not mix languages within the same image.
* Only images that represent the extension’s function are allowed.
* Advertising for other extensions or services is not permitted.
* Show the extension in use in Storefront and Administration, including configuration and how-to detail.
* Prefer screenshots for mobile and desktop.
* Images must be high quality; at least one storefront and one admin screenshot should show main features.
* Store a valid favicon named `plugin.png` (112×112px) under `src/Resources/config/` so the extension is identifiable under **Administration > Extension Manager**.
* [Themes](../../../plugins/themes/index.md) require a preview image in the Theme Manager.
* [Shopping Experiences CMS elements](../../../../concepts/commerce/content/shopping-experiences-cms.md#elements) must include an element icon.
* [How to request a preview](https://docs.shopware.com/en/account-en/extension-partner/extensions?category=account-en/extension-partner#how-can-i-request-a-preview)

::: info
[How to add images and icons to extensions](https://docs.shopware.com/en/account-en/adding-pictures-and-icons/how-to)
:::

## Preview and Extension Manager presentation {#preview-and-extension-manager-presentation}

For detailed requirements, see the [FAQ — What must a preview include?](./faq.md#what-must-a-preview-include).

## Admin translations {#admin-translations}

Extensions must work independently of the system language. If a translation is missing (for example, Spanish), use a proper fallback (usually English).

If the extension is available in multiple languages, define them in your Shopware Account under “Translations into the following languages are available,” in the "Description & images" section.

English must be the fallback and always be available for settings and error messages.

### Extension master data and license

The license in your Shopware Account must match the license in `composer.json`. The selected license cannot be changed after the extension is created; a new extension with a new technical name and upload is required for changes.

## Manufacturer profile

Configure the profile under **Shopware Account > Extension Partner > [Extension Partner profile](https://account.shopware.com/producer/profile)**.

* A manufacturer logo is required.
* No iframes, tracking, or external scripts.
* External sources must use HTTPS.
* Accurate English and German descriptions.

::: info
Descriptions, profiles, and instructions must not use iframes, external scripts, or tracking pixels. Custom styles must not overwrite core Shopware styles. External resources must use HTTPS.
:::

::: info
You cannot advertise Shopware certificates in an extension description, images, or the manufacturer profile. Certificates are added automatically at the end of each extension description by Shopware.
:::

## Listing content rules (privacy and media)

If personal data is processed under Art. 28 DSGVO, declare subprocessors and further subprocessors as required in your account.

**Not allowed in listings and profiles:**

* Inline styles in descriptions.
* Certificates embedded in descriptions (see note above).
* Iframes, tracking pixels, and external scripts.

**Allowed:**

* Up to two YouTube videos embedded in the extension description.

::: info
Video content (explainers, demos, tutorials) improves trust and conversion.
:::

---

---
url: /docs/guides/plugins/apps/app-sdks/javascript/03-context.md
---

# Context

The `ContextResolver` validates incoming requests, resolves the corresponding shop, and returns a typed context for further processing.

* `fromBrowser()` resolves requests coming from browser-based app modules, such as iframes.
* `fromAPI()` resolves requests coming from Shopware server-to-server calls, such as webhooks or action buttons.

## Usage

```javascript
import { AppServer } from '@shopware-ag/app-server-sdk'

const app = new AppServer(/** ... */);

// Resolve the context from the request like iframe
app.contextResolver.fromBrowser(/** Request */);

// Resolve the context from the request like webhook, action button
app.contextResolver.fromAPI(/** Request */);
```

Both methods accept a generic type parameter to define the expected context payload.

```ts
import { BrowserAppModuleRequest } from '@shopware-ag/app-server-sdk/types'

const ctx = await app.contextResolver.fromBrowser<BrowserAppModuleRequest>(/** Request */);

// This is now typed
console.log(ctx.payload['sw-version']);
```

See the [types.ts](https://github.com/shopware/app-sdk-js/blob/main/src/types.ts) for the available built-in types.

If a type is missing, either file an issue on the SDK repository or define your own in your project.

```ts
type MyCustomWebHook = {
  foo: string;
}

const ctx = await app.contextResolver.fromBrowser<MyCustomWebHook>(/** Request */);

ctx.payload.foo; // This is now typed and the IDE will help you
```

Next, we will look into [Signing Responses](./04-signing).

---

---
url: /docs/guides/plugins/apps/app-sdks/php/03-context.md
---

# Context

The ContextResolver helps you map the Shopware requests to struct classes to work with them more easily.
It also does some validation and checks if the request is valid.

## Usage

```php
$app = new AppConfiguration('Foo', 'test', 'http://localhost:6001/register/callback');
// for a repository to save stores implementing \Shopware\App\SDK\Shop\ShopRepositoryInterface, see FileShopRepository as an example
$repository = ...;

// Create a psr 7 request or convert it (HttpFoundation Symfony)
$psrRequest = ...;

$registrationService = new \Shopware\App\SDK\Registration\RegistrationService($app, $repository);
$shopResolver = new \Shopware\App\SDK\Shop\ShopResolver($repository);

$contextResolver = new \Shopware\App\SDK\Context\ContextResolver();

// Find the actual shop by the request
$shop = $shopResolver->resolveShop($psrRequest);

// Parse the request as a webhook
$webhook = $contextResolver->assembleWebhook($psrRequest, $shop);

$webhook->eventName; // the event name
$webhook->payload; // the event data
```

## Supported requests

* [Webhook](https://github.com/shopware/app-php-sdk/blob/main/src/Context/Webhook/WebhookAction.php) - Webhooks or App lifecycle events
* [ActionButton](https://github.com/shopware/app-php-sdk/blob/main/src/Context/ActionButton/ActionButtonAction.php) - Administration buttons
* [Module](https://github.com/shopware/app-php-sdk/blob/main/src/Context/Module/ModuleAction.php) - Iframe
* [TaxProvider](https://github.com/shopware/app-php-sdk/blob/main/src/Context/TaxProvider/TaxProviderAction.php) - Tax calculation
* [Payment Pay](https://github.com/shopware/app-php-sdk/blob/main/src/Context/Payment/PaymentPayAction.php) - Payment pay action
* [Payment Capture](https://github.com/shopware/app-php-sdk/blob/main/src/Context/Payment/PaymentCaptureAction.php) - Payment capture action
* [Payment Validate](https://github.com/shopware/app-php-sdk/blob/main/src/Context/Payment/PaymentValidateAction.php) - Payment validate action
* [Payment Finalize](https://github.com/shopware/app-php-sdk/blob/main/src/Context/Payment/PaymentFinalizeAction.php) - Payment finalize action

Next, we will look into the [Signing of responses](./04-signing).

---

---
url: /docs/v6.5/guides/plugins/apps/app-sdks/php/03-context.md
---

# Context

The ContextResolver helps you map the Shopware requests to struct classes to work with them more easily.
It also does some validation and checks if the request is valid.

## Usage

```php
$app = new AppConfiguration('Foo', 'test', 'http://localhost:6001/register/callback');
// for a repository to save stores implementing \Shopware\App\SDK\Shop\ShopRepositoryInterface, see FileShopRepository as an example
$repository = ...;

// Create a psr 7 request or convert it (HttpFoundation Symfony)
$psrRequest = ...;

$registrationService = new \Shopware\App\SDK\Registration\RegistrationService($app, $repository);
$shopResolver = new \Shopware\App\SDK\Shop\ShopResolver($repository);

$contextResolver = new \Shopware\App\SDK\Context\ContextResolver();

// Find the actual shop by the request
$shop = $shopResolver->resolveShop($psrRequest);

// Parse the request as a webhook
$webhook = $contextResolver->assembleWebhook($psrRequest, $shop);

$webhook->eventName; // the event name
$webhook->payload; // the event data
```

## Supported requests

* [Webhook](https://github.com/shopware/app-php-sdk/blob/main/src/Context/Webhook/WebhookAction.php) - Webhooks or App lifecycle events
* [ActionButton](https://github.com/shopware/app-php-sdk/blob/main/src/Context/ActionButton/ActionButtonAction.php) - Administration buttons
* [Module](https://github.com/shopware/app-php-sdk/blob/main/src/Context/Module/ModuleAction.php) - Iframe
* [TaxProvider](https://github.com/shopware/app-php-sdk/blob/main/src/Context/TaxProvider/TaxProviderAction.php) - Tax calculation
* [Payment Pay](https://github.com/shopware/app-php-sdk/blob/main/src/Context/Payment/PaymentPayAction.php) - Payment pay action
* [Payment Capture](https://github.com/shopware/app-php-sdk/blob/main/src/Context/Payment/PaymentCaptureAction.php) - Payment capture action
* [Payment Validate](https://github.com/shopware/app-php-sdk/blob/main/src/Context/Payment/PaymentValidateAction.php) - Payment validate action
* [Payment Finalize](https://github.com/shopware/app-php-sdk/blob/main/src/Context/Payment/PaymentFinalizeAction.php) - Payment finalize action

Next, we will look into the [Signing of responses](./04-signing).

---

---
url: /docs/v6.6/guides/plugins/apps/app-sdks/javascript/03-context.md
---

# Context

The ContextResolver helps you to validate the Request, resolve the Shop and provide types for the Context.

## Usage

```javascript
import { AppServer } from '@shopware-ag/app-server-sdk'

const app = new AppServer(/** ... */);

// Resolve the context from the request like iframe
app.contextResolver.fromBrowser(/** Request */);

// Resolve the context from the request like webhook, action button
app.contextResolver.fromAPI(/** Request */);
```

Both methods accepts a Type to specify the context type.

```ts
import { BrowserAppModuleRequest } from '@shopware-ag/app-server-sdk/types'

const ctx = await app.contextResolver.fromBrowser<BrowserAppModuleRequest>(/** Request */);

// This is now typed
console.log(ctx.payload['sw-version']);
```

You can checkout the [types.ts](https://github.com/shopware/app-sdk-js/blob/main/src/types.ts) to see all available types.

If you miss a type, feel free to open a PR or an issue. Otherwise you can also specify the type also in your project.

```ts
type MyCustomWebHook = {
  foo: string;
}

const ctx = await app.contextResolver.fromBrowser<MyCustomWebHook>(/** Request */);

ctx.payload.foo; // This is now typed and the IDE will help you
```

Next, we will look into the [Signing of responses](./04-signing).

---

---
url: /docs/v6.6/guides/plugins/apps/app-sdks/php/03-context.md
---

# Context

The ContextResolver helps you map the Shopware requests to struct classes to work with them more easily.
It also does some validation and checks if the request is valid.

## Usage

```php
$app = new AppConfiguration('Foo', 'test', 'http://localhost:6001/register/callback');
// for a repository to save stores implementing \Shopware\App\SDK\Shop\ShopRepositoryInterface, see FileShopRepository as an example
$repository = ...;

// Create a psr 7 request or convert it (HttpFoundation Symfony)
$psrRequest = ...;

$registrationService = new \Shopware\App\SDK\Registration\RegistrationService($app, $repository);
$shopResolver = new \Shopware\App\SDK\Shop\ShopResolver($repository);

$contextResolver = new \Shopware\App\SDK\Context\ContextResolver();

// Find the actual shop by the request
$shop = $shopResolver->resolveShop($psrRequest);

// Parse the request as a webhook
$webhook = $contextResolver->assembleWebhook($psrRequest, $shop);

$webhook->eventName; // the event name
$webhook->payload; // the event data
```

## Supported requests

* [Webhook](https://github.com/shopware/app-php-sdk/blob/main/src/Context/Webhook/WebhookAction.php) - Webhooks or App lifecycle events
* [ActionButton](https://github.com/shopware/app-php-sdk/blob/main/src/Context/ActionButton/ActionButtonAction.php) - Administration buttons
* [Module](https://github.com/shopware/app-php-sdk/blob/main/src/Context/Module/ModuleAction.php) - Iframe
* [TaxProvider](https://github.com/shopware/app-php-sdk/blob/main/src/Context/TaxProvider/TaxProviderAction.php) - Tax calculation
* [Payment Pay](https://github.com/shopware/app-php-sdk/blob/main/src/Context/Payment/PaymentPayAction.php) - Payment pay action
* [Payment Capture](https://github.com/shopware/app-php-sdk/blob/main/src/Context/Payment/PaymentCaptureAction.php) - Payment capture action
* [Payment Validate](https://github.com/shopware/app-php-sdk/blob/main/src/Context/Payment/PaymentValidateAction.php) - Payment validate action
* [Payment Finalize](https://github.com/shopware/app-php-sdk/blob/main/src/Context/Payment/PaymentFinalizeAction.php) - Payment finalize action

Next, we will look into the [Signing of responses](./04-signing).

---

---
url: /resources/admin-extension-sdk/api-reference/context.md
---

# Context

The Context API provides read access to the current state of the Shopware Administration. Extensions can use these methods to retrieve information about the active language, locale, currency, environment, Shopware version, and more.

This is useful for adapting extension behavior based on the current Administration context — for example, loading translations for the active language, matching the active color theme, or checking the Shopware version before using a newer API.

```ts
import { context } from "@shopware-ag/meteor-admin-sdk";
```

## getLanguage()

Returns the current Administration language ID and the system default language ID. Use this to load the correct translations or filter data by language.

#### Usage

```ts
const language = await context.getLanguage();
```

#### Parameters

No parameters needed.

#### Return value

```ts
Promise<{
  languageId: string;
  systemLanguageId: string;
}>
```

#### Example value

```ts
{
  languageId: '2fbb5fe2e29a4d70aa5854ce7ce3e20b',
  systemLanguageId: '2fbb5fe2e29a4d70aa5854ce7ce3e20b'
}
```

## subscribeLanguage()

Subscribes to language changes in the Administration. The callback fires whenever the user switches languages, allowing extensions to react immediately (e.g. reloading translated content).

#### Usage

```ts
context.subscribeLanguage(({ languageId, systemLanguageId }) => {
  // do something with the callback data
});
```

#### Parameters

| Name             | Description                            |
| :--------------- | :------------------------------------- |
| `callbackMethod` | Called every-time the language changes |

#### Callback value

```ts
{
  languageId: string,
  systemLanguageId: string
}
```

#### Example callback value

```ts
{
  languageId: '2fbb5fe2e29a4d70aa5854ce7ce3e20b',
  systemLanguageId: '2fbb5fe2e29a4d70aa5854ce7ce3e20b'
}
```

## getEnvironment()

Returns the current Administration environment mode. Use this to enable debug features or disable analytics in non-production environments.

#### Usage

```ts
const environment = await context.getEnvironment();
```

#### Parameters

No parameters needed.

#### Return value

```ts
Promise<"development" | "production" | "testing">
```

#### Example value

```ts
"development";
```

## getLocale()

Returns the browser locale used by the Administration UI, including a fallback locale. Use this to format dates, numbers, or currencies according to the user's regional settings.

#### Usage

```ts
const locale = await context.getLocale();
```

#### Parameters

No parameters needed.

#### Return value

```ts
Promise<{
  locale: string;
  fallbackLocale: string;
}>
```

#### Example value

```ts
{
  locale: 'de-DE',
  fallbackLocale: 'en-GB'
}
```

## subscribeLocale()

Subscribes to locale changes in the Administration. The callback fires whenever the locale changes, allowing extensions to re-render locale-dependent content like formatted dates or currencies.

#### Usage

```ts
context.subscribeLocale(({ locale, fallbackLocale }) => {
  // do something with the callback data
});
```

#### Parameters

| Name             | Description                          |
| :--------------- | :----------------------------------- |
| `callbackMethod` | Called every-time the locale changes |

#### Callback value

```ts
{
  locale: string,
  fallbackLocale: string
}
```

#### Example callback value

```ts
{
  locale: 'de-DE',
  fallbackLocale: 'en-GB'
}
```

## Automatic theme synchronization

On startup, the SDK mirrors the resolved Administration theme onto the `data-theme` attribute and the `color-scheme` style of your document root (`<html data-theme="light|dark">`) and keeps both in sync. Because Meteor tokens are theme-aware through `data-theme`, updating the SDK dependency is all an app needs to follow the Administration theme. The matching `color-scheme` keeps the iframe transparent — on a mismatch the browser paints an opaque backdrop behind it.

If your document already declares `data-theme` itself, the SDK does not interfere. On Administrations without theme support, the attribute is never set.

## Embedded context

When your app runs inside an iframe, the SDK marks the document root with a `data-embedded` attribute (`<html data-embedded>`) on startup, so stylesheets can adapt to the embedded context. It also unsets the body background (`html[data-embedded] body { background: unset; }`) as a sensible default for iframes inside of the administration.

If your document already declares `data-embedded` itself, the SDK keeps your value.

## getTheme()

Returns the current resolved color theme of the Administration. A `system` preference is always resolved, so the result is either `"light"` or `"dark"`.

#### Usage

```ts
const theme = await context.getTheme();
```

#### Parameters

No parameters needed.

#### Return value

```ts
Promise<"light" | "dark">
```

#### Example value

```ts
"dark";
```

## subscribeTheme()

Subscribes to theme changes in the Administration. The callback fires whenever the resolved theme changes. Returns a function that stops the subscription.

#### Usage

```ts
context.subscribeTheme((theme) => {
  // do something with the callback data
});
```

#### Parameters

| Name             | Description                                  |
| :--------------- | :------------------------------------------- |
| `callbackMethod` | Called every time the resolved theme changes |

#### Callback value

```ts
"light" | "dark"
```

#### Example callback value

```ts
"dark";
```

## syncTheme()

Mirrors the Administration theme onto an element's `data-theme` attribute and keeps it in sync. The document root is already handled by the [automatic theme synchronization](#automatic-theme-synchronization); use this when you manage `data-theme` yourself or need the attribute on additional elements.

#### Usage

```ts
const stopSync = await context.syncTheme({ target: document.getElementById("app") });
```

#### Parameters

| Name             | Description                                                                             |
| :--------------- | :-------------------------------------------------------------------------------------- |
| `options.target` | Element whose `data-theme` attribute is updated. Defaults to `document.documentElement` |

#### Return value

```ts
Promise<() => void>
```

The returned function stops the synchronization.

## getCurrency()

Returns the system currency configured for the Shopware instance. Use this when displaying prices or working with monetary values.

#### Usage

```ts
const currency = await context.getCurrency();
```

#### Parameters

No parameters needed.

#### Return value

```ts
Promise<{
  systemCurrencyId: string;
  systemCurrencyISOCode: string;
}>
```

#### Example value

```ts
{
  systemCurrencyId: 'b7d2554b0ce847cd82f3ac9bd1c0dfca',
  systemCurrencyISOCode: 'EUR'
}
```

## getShopwareVersion()

Returns the Shopware version as a string. Use this to conditionally enable features or check compatibility before using newer APIs.

#### Usage

```ts
const shopwareVersion = await context.getShopwareVersion();
```

#### Parameters

No parameters needed.

#### Return value

```ts
string
```

#### Example value

```ts
"6.4.0.0";
```

## compareIsShopwareVersion()

Compares the current Shopware version against a target version. The current Shopware version is always the left-hand side of the comparison — so `context.compareIsShopwareVersion('>=', '7.0.0')` reads as "is the current Shopware version equal to or greater than 7.0.0?"

#### Usage

```ts
const isRightVersion = await context.compareIsShopwareVersion(">=", "7.0.0");
```

#### Parameters

| Name         | Description                                                                      |
| :----------- | :------------------------------------------------------------------------------- |
| `comparator` | The operator to compare. Possible values: `'='` `'!='` `'>'` `'<'` `'<='` `'>='` |
| `version`    | The string with the version to compare                                           |

The function supports both Shopware's four-digit version number and semver versions. The following calls are equivalent:

```ts
await context.compareIsShopwareVersion(">=", "6.6.4.0");

await context.compareIsShopwareVersion(">=", "6.4.0");
```

#### Return value

```ts
boolean
```

#### Example value

```ts
true;
```

## getAppInformation()

Returns metadata about the current app or plugin, including its name, version, type, and granted privileges. Use this to adapt behavior based on the extension type or check which permissions were granted.

> The `privileges` property is available since Shopware v6.7.1.0.

#### Usage

```ts
const { name, version, type, privileges } = await context.getAppInformation();
```

#### Parameters

No parameters needed.

#### Return value

```ts
Promise<{
  name: string;
  version: string;
  type: "app" | "plugin";
  privileges: privileges;
}>
```

#### Example value

```ts
{
  name: 'my-extension',
  version: '1.2.3',
  type: 'app',
  privileges: {
    read: [ 'product', 'customer' ],
    update: [ 'product' ],
    additional: [ 'system.cache_clear' ]
  }
}
```

## getUserInformation()

Returns details about the currently logged-in Administration user, including their roles, email, and admin status. Use this to personalize the extension UI or check user permissions.

> Available since Shopware v6.4.9.0

#### Usage

```ts
const userInformation = await context.getUserInformation();
```

#### Parameters

No parameters needed.

#### Return value

```ts
Promise<{
  aclRoles: Array<{
    name: string;
    type: string;
    id: string;
    privileges: Array<string>;
  }>;
  active: boolean;
  admin: boolean;
  avatarId: string;
  email: string;
  firstName: string;
  id: string;
  lastName: string;
  localeId: string;
  title: string;
  type: string;
  username: string;
}>
```

#### Example value

```ts
{
    "aclRoles": [],
    "active": true,
    "admin": true,
    "avatarId": "",
    "email": "info@shopware.com",
    "firstName": "",
    "id": "e2a77f4c718d407591b4826222aa3546",
    "lastName": "admin",
    "localeId": "35bbb8c4305c47ec88b13ab30c0c5c5a",
    "title": "",
    "type": "user",
    "username": "admin"
}
```

## getUserTimezone()

Returns the timezone setting of the currently logged-in user. Use this to display dates and times in the user's local timezone.

> Available since Shopware v6.6.2.0

#### Usage

```ts
const userTimezone = await context.getUserTimezone();
```

#### Parameters

No parameters needed.

#### Return value

```ts
Promise<string>
```

This function returns a Promise that resolves to a string representing the user's timezone.

## getModuleInformation()

Returns the list of all registered extension modules (created by adding menu items, settings items, etc.). Use the module ID to navigate between extensions.

#### Usage

```ts
import { window as swWindow } from "@shopware-ag/meteor-admin-sdk";

const { modules } = await context.getModuleInformation();

swWindow.routerPush({
  name: "sw.extension.sdk.index",
  params: {
    id: modules[0].id,
  },
});
```

#### Parameters

No parameters needed.

#### Return value

```ts
Promise<{
  modules: Array<{
    displaySearchBar: boolean;
    heading: string;
    id: string;
    locationId: string;
  }>;
}>
```

#### Example value

```ts
{
  modules: [
    {
      displaySearchBar: true,
      heading: "My module",
      id: "sd5aasfsdfas",
      locationId: "my-location-id",
    },
  ];
}
```

## getShopId()

Returns the unique shop ID used by Shopware's app system. Use this to identify the shop instance when communicating with external services.

> Available since Shopware v6.7.1.0

#### Usage

```ts
const shopId = await context.getShopId();
```

#### Parameters

No parameters needed.

#### Return value

```ts
Promise<string | null>
```

## can()

Checks whether a specific privilege is granted for the current app. Use this to conditionally show features that require specific permissions.

> Available since Shopware v6.7.1.0

#### Usage

```ts
const isAllowed: boolean = await context.can("product:read");
```

#### Parameters

| Name        | Description                                          |
| :---------- | :--------------------------------------------------- |
| `privilege` | The privilege string to check, e.g. `'product:read'` |

#### Return value

```ts
boolean
```

---

---
url: /frontends/concepts/composables/context-composables.md
---
# Context Composables

Composables are containers for reusable logic and state. While some composables are entirely stateless and just provide a set of functions, there are so-called context composables that can share state between parent and child components without the need for property drilling or usage of `provide` and `inject`.

Context boundaries follow the component tree hierarchy, so that a child component can access the state of its parent component without explicit references.

## Why to use context composables

Context composables allow for a more granular way of sharing state between components.

Instead of doing this:

```vue
<!-- Product.vue -->
<script setup lang="ts">
const product = searchProduct();
</script>
<template>
  <div>
    <ProductConfigurator :product="product" />
  </div>
</template>
```

```vue
<!-- ProductConfigurator.vue -->
<script setup lang="ts">
const props = defineProps<{
  product: Product;
}>();
</script>
<template>
  <div>
    <ProductPrice :product="product" />
  </div>
</template>
```

```vue
<!-- ProductPrice.vue -->
<script setup lang="ts">
const props = defineProps<{
  product: Product;
}>();
</script>
<template>
  <div>
    {{ getFormattedPrice(product.price) }}
  </div>
</template>
```

A parent component calls the composable and provides context - all child components can feed off that context. Have a look at the example below:

![wireframe of an application showing multiple context composables](../../.assets/wireframe-proposal-01.png)

In the example above, there are multiple usages of the `useProduct` composable and one usage of the `useNavigationContext` composable. All calls create a new context boundary (indicated by the coloured boxes). Within their context boundaries (meaning further down the component tree), the child components can access the state of the parent component.

For example, the call

```js
const { product } = useProduct(detailProduct);
```

creates a new context boundary for all underlying components. The `ProductConfigurator` component can access the `product` state without having to pass it down as a prop.

### Navigation Context (blue)

This context boundary is usually global to the whole application, unless you have explicit requirements for sub-routes within your pages.
Just call the following to access navigation context information from almost anywhere in your application:

```js
const { routeName, foreignKey } = useNavigationContext();
```

### Detail page (red)

The detail page component calls the composable with the `detailProduct` parameter and creates a new context boundary (red). Every child component of the detail page can now call

```js
const { product } = useProduct();
```

and access data from the correct product, such as title, description or price.

### Quickview (green)

In the quickview component, a new context boundary (green) is created by calling the composable with the `quickViewProduct` parameter.

Again, all children components of the quickview components have access without passing the product context explicitly. You can even use the same components as in the product detail page.

## Using context composables

Context composables are used just as normal composables. However, they have one additional catch. They can be instantiated with and without a `context` parameter. If the `context` parameter is set, a new context boundary is created, which means all child components are able to retrieve the same state. Correspondingly, if the `context` parameter is omitted, the context state is resolved from the closest parent context boundary.

:::info
Internally, context composables use the `provide` and `inject` mechanism from Vue 3.
:::

### Example

See a simple example with the context composable `useCategory` below.

First, fetch a category from the API and store it in the context state by passing it to the `useCategory` composable.

```vue
<!-- Category.vue -->

<script setup>
const { path } = useRoute();
const { search } = useCategorySearch();

const categoryResponse = await search(path);

// Setting the context and creating a context boundary
const { category } = useCategory(categoryResponse);
</script>

<template>
  <CategoryHeader />
</template>
```

Then, use the `useCategory` composable in the child component to retrieve the category from the context state.

```vue
<!-- CategoryHeader.vue -->

<script setup>
// Resolving the category from the closest parent context boundary
const { category } = useCategory();
</script>

<template>
  <h1>{{ category.name }}</h1>
  <p>{{ category.description }}</p>
</template>
```

---

---
url: /docs/guides/plugins/apps/gateways/context/context-gateway.md
---

# Context Gateway

:::danger
**Security and privacy**

With the Context Gateway, Shopware enables your app to manipulate the customer context, including sensitive information such as customer addresses, payment methods, and more.

It is your responsibility to ensure that the commands are valid and do not compromise customer security or privacy.

Due to the powerful nature of this feature, it should only be used if your app server is properly secured and the commands it sends are fully trusted and validated.
:::

## Context

Introduced in Shopware version 6.7.1.0, the Context Gateway is a powerful feature that enables apps to securely access and interact with the customer context — based on the current cart and sales channel — allowing for more informed decision-making on the app server. This enhancement empowers app developers to dynamically tailor the shopping experience by manipulating the customer context.

It serves as the bridge between your app’s JavaScript and your app server.

## Prerequisites

You should be familiar with the concept of Apps, their registration flow, and signing and verifying requests and responses between Shopware and the App backend server.

Your app server must also be accessible to the Shopware server. You can use a tunneling service like [ngrok](https://ngrok.com/) for development.

## Manifest configuration

To indicate to Shopware that your app uses the context gateway, you must provide a `context` property inside a `gateways` parent property of your app's `manifest.xml`.

Below is an example definition of a working checkout gateway configuration.

::: code-group

```xml [manifest.xml]
<?xml version="1.0" encoding="UTF-8"?>
<manifest>
    <!-- ... -->

    <gateways>
        <!-- ... -->
        <context>https://my-app.server.com/context/gateway</context>
    </gateways>
</manifest>
```

:::

After the successful installation of your app, the context gateway is ready to be called by Shopware.

## Context Gateway Endpoint

To trigger the context gateway, your integration can call the additional Store API route: `store-api.context.gateway`.
This endpoint will forward the request to your app server’s context gateway endpoint, which must be [configured in your app's manifest](#manifest-configuration).

To allow the shop to identify your app, the request must include the `appName` field, defined in your [app’s `manifest.xml`](../../app-base-guide.md#manifest-file).

Your app server will receive the following payload:

* The request source, including:
  * The URL of the Shopware shop
  * The Shop ID
  * The app version
  * Any active [in-app purchase](../../../../development/monetization/in-app-purchases.md).
* The current `SalesChannelContext`
* The current `Cart`
* Any custom data you include in the request body

::: info

Communication between Shopware and your app server is secured via the [app signature verification mechanism](../../lifecycle/app-signature-verification.md), ensuring that only your app server can respond to context gateway requests.

:::

### Storefront Integration

To trigger the context gateway from the Storefront, use the `frontend.gateway.context` endpoint. Shopware automatically registers this route.

You can include any custom data in the request body; Shopware will forward it to your app server.

To simplify this integration, Shopware provides the `ContextGatewayClient` service.
This JavaScript client is intended for use within your app and handles communication with the context gateway endpoint.
It returns a response containing:

* A (new) context token
* An optional redirect URL

Here is an example JavaScript plugin that triggers the context gateway when a button is clicked in the Storefront:

::: code-group

```javascript [context-gateway.js]
import Plugin from 'src/plugin-system/plugin.class';
import ContextGatewayClient from 'src/service/context-gateway-client.service';

export default class MyPlugin extends Plugin {
  init() {
    this._registerEvents();
 }

  _registerEvents() {
    this.el.addEventListener('click', this._onClick.bind(this));
 }

  async _onClick() {
    // create client with your app name
    const gatewayClient = new ContextGatewayClient('myAppName');

    // call the gateway with optional custom data
    const tokenResponse = await gatewayClient.call({ some: 'data', someMore: 'data' });

    // either: you can work with the new token or redirect URL
    // this means you have to handle the navigation yourself, e.g., reloading the page or redirecting to the URL
    const token = tokenResponse.token;
    const redirectUrl = tokenResponse.redirectUrl;

    // or: if you want shopware to handle the navigation automatically, even supplying an optional custom target path is possible,
    await gatewayClient.navigate(tokenResponse, '/custom/target/path');
 }
}
```

:::

::: info
**Navigation `customTarget` Behavior**

The `customTarget` parameter allows you to optionally control the redirect path used by the `navigate` method.

* If `customTarget` is an **absolute path** (starts with `/`), it completely replaces the path portion of the `redirectUrl`.
  This can be used to override sales channel sub-paths in the `redirectUrl`.
  *Example:* `https://example.com/en` → `https://example.com/custom/target/path`

* If `customTarget` is a **relative path**, it is appended to the existing path of the `redirectUrl`.

* If `customTarget` is `null`, the behavior depends on whether a `redirectUrl` is present:
  * If present: the `redirectUrl` is used as-is.
  * If not: the current page is reloaded to apply context changes.

Trailing slashes are automatically removed to ensure clean and consistent URLs.
:::

### App server response

::: warning
**Connection timeouts**

The Shopware shop will wait for a response for 5 seconds.
Be sure that your context gateway implementation on your app server responds in time, otherwise Shopware will time out and drop the connection.
:::

Your app server can respond with a list of commands to modify the current sales channel context.
These commands can be used to perform actions such as:

* Changing aspects of the customer context, like:
  * Changing the active currency
  * Changing the active language and more
* Registering a new customer
* Logging in an existing customer

You can find a complete reference of all available commands in the [command reference](./command-reference.md).

For example, you might want to update the context to a different currency and language if the current currency is not GBP.

Request content is JSON

```json5
{
  "source": {
    "url": "http:\/\/localhost:8000",
    "shopId": "hRCw2xo1EDZnLco4",
    "appVersion": "1.0.0"
 },
  "cart": {
    //...
 },
  "salesChannelContext": {
    //...
 },
  "data": {
    "your": "custom data",
    "appears": "here"
 }
}
```

And your response could look like this:

```json5
{
  "commands": [
 {
      "command": "context_change-currency",
      "payload": {
        "iso": "GBP"
 }
 },
 {
      "command": "context_change-language",
      "payload": {
        "iso": "en-GB",
 }
 }
 ]
}
```

With version `4.1.0`, support for the context gateway has been added to the `app-php-sdk`.
The SDK will handle the communication with the Shopware shop and provide you with a convenient way to handle the incoming payload and respond with the necessary commands.

```php
<?php declare(strict_types=1);

use Psr\Http\Message\RequestInterface;
use Psr\Http\Message\ResponseInterface;
use Shopware\App\SDK\Context\Cart\Error;
use Shopware\App\SDK\Context\ContextResolver;
use Shopware\App\SDK\Framework\Collection;
use Shopware\App\SDK\Gateway\Context\ContextGatewayCommand;
use Shopware\App\SDK\Gateway\Context\Command\ChangeCurrencyCommand;
use Shopware\App\SDK\Gateway\Context\Command\ChangeLanguageCommand;
use Shopware\App\SDK\Response\GatewayResponse;
use Shopware\App\SDK\Shop\ShopResolver;

function gatewayController(RequestInterface $request): ResponseInterface
{
    // injected or built by yourself
    $shopResolver = new ShopResolver($repository);
    $contextResolver = new ContextResolver();
    $signer = new ResponseSigner();

    $shop = $shopResolver->resolveShop($request);

    /** @var Shopware\App\SDK\Context\Gateway\Context\ContextGatewayAction $action */
    $action = $contextResolver->assembleContextGatewayRequest($request, $shop);

    /** @var Collection<Shopware\App\SDK\Gateway\Context\ContextGatewayCommand> $commands */
    $commands = new Collection();

    if ($action->getSalesChannelContext()->getCurrency()->getIsoCode() !== 'GBP') {
        $commands->add(new ChangeCurrencyCommand('GBP'));
        $commands->add(new ChangeLanguageCommand('en-GB'));
    }

    $response = GatewayResponse::createContextGatewayResponse($commands);

    return $signer->sign($response);
}
```

```php
<?php declare(strict_types=1);

namespace App\Controller;

use Shopware\App\SDK\Context\Cart\Error;
use Shopware\App\SDK\Context\Gateway\Context\ContextGatewayAction;
use Shopware\App\SDK\Framework\Collection;
use Shopware\App\SDK\Gateway\Context\Command\ChangeCurrencyCommand;
use Shopware\App\SDK\Gateway\Context\Command\ChangeLanguageCommand;
use Shopware\App\SDK\Response\GatewayResponse;
use Symfony\Bridge\PsrHttpMessage\HttpFoundationFactoryInterface;
use Symfony\Bundle\FrameworkBundle\Controller\AbstractController;
use Symfony\Component\HttpFoundation\Response;
use Symfony\Component\Routing\Attribute\Route;

#[Route('/api/gateway', name: 'api.gateway.')]
class GatewayController extends AbstractController
{
    public function __construct(
        private readonly HttpFoundationFactoryInterface $httpFoundationFactory
    ) {
    }

 #[Route('/context', name: 'context', methods: ['POST'])]
    public function context(ContextGatewayAction $action): Response
    {
        /** @var Collection<ContextGatewayCommand> $commands */
        $commands = new Collection();

        if ($action->getSalesChannelContext()->getCurrency()->getIsoCode() !== 'GBP') {
            $commands->add(new ChangeCurrencyCommand('GBP'));
            $commands->add(new ChangeLanguageCommand('en-GB'));
        }

        $response = GatewayResponse::createContextGatewayResponse($commands);

        return $this->httpFoundationFactory->createResponse($response);
    }
}
```

### Command Validation

Shopware performs basic validation on the commands returned by your app server to ensure they are reasonable to execute.

The following checks are enforced:

* The command must be recognized as valid, e.g. `context_change-currency`. See the full list of available [commands](./command-reference.md#available-commands).
* The payload must be valid for the respective command type.
* Only **one command per type** is allowed. For example, you cannot include two `context_change-currency` commands in a single response.
* A maximum of **one `context_register-customer` or `context_login-customer`** command is allowed per response.

## Event

Plugins can listen to the `Shopware\Core\Framework\Gateway\Context\Command\Event\ContextGatewayCommandsCollectedEvent`.
This event is dispatched after all commands have been collected from the app server and allows plugins to modify or add commands based on the same payload the app received.

## Special Considerations

* The `context_login-customer` command allows your app to log in a customer **without requiring their password**.
  Use this feature with caution to uphold the shop’s security and privacy standards.

* The `context_register-customer` command will create a new customer account and **automatically log them in**.
  Make sure to validate the provided data before issuing this command.
  See the [RegisterCustomerCommand reference](./command-reference.md#available-data-for-registercustomercommand) for the list of accepted fields.

In both cases, your app must ensure that the customer has **explicitly consented** to be registered or logged in.

---

---
url: /docs/resources/references/adr/2025-04-01-context-gateway.md
---

# Context Gateway

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2025-04-01-context-gateway.md)
:::

# ADR: Context Gateway Feature

## Context

Previously, we introduced the `CheckoutGateway` to allow app servers to influence the checkout process based on the current cart and sales channel context.\
This was a significant step toward enabling dynamic, app-driven decision-making during checkout.

However, this approach does not support modifying the storefront experience **outside** of the checkout flow.\
There is a growing need to allow app servers to influence the **sales channel context** —
e.g. customer data, language, and currency — based on external logic or user-specific criteria.

In particular, some use cases require **context manipulation before a cart or checkout process begins**.\
To address this, we propose the introduction of a dedicated `ContextGateway`,
which provides a secure and structured communication channel between the storefront and the app server.

The gateway is initiated from the storefront client and allows apps to request context changes based on external decision logic.

### Example Use Cases

* Registering customers with custom or prefilled data (including guest and full customer registration)
* Logging in existing customers
* Switching the current language or currency
* Updating the active customer address

## Decision

### AppContextGateway

To encapsulate the logic for context-driven decisions, a new `AppContextGateway` will be introduced.

It receives a `ContextGatewayPayloadStruct`, which includes:

* The current `SalesChannelContext`
* The current `Cart`
* A `RequestDataBag` containing all custom data provided by the client

The gateway will return a `ContextTokenResponse`, which includes the updated token of the `SalesChannelContext` after executing all applicable commands.

Example implementation:

```php
<?php declare(strict_types=1);

class AppCheckoutGateway
{
    public function process(ContextGatewayPayloadStruct $payload): ContextTokenResponse;
}
```

#### Store-API

A new store API route, `ContextGatewayRoute` '/store-api/context/gateway', will be introduced.
This route will call the `AppContextGateway` implementation and respond accordingly.

Example implementation:

```php
<?php declare(strict_types=1);

#[Route(defaults: [PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [StoreApiRouteScope::ID]])]
class ContextGatewayRoute extends AbstractContextGatewayRoute
{
    public function __construct(
        private readonly AppContextGateway $contextGateway,
    ) {
    }

    public function getDecorated(): AbstractContextGatewayRoute
    {
        throw new DecorationPatternException(self::class);
    }

    #[Route(path: '/store-api/context/gateway', name: 'store-api.context.gateway', methods: ['GET', 'POST'])]
    public function load(Request $request, Cart $cart, SalesChannelContext $context): ContextTokenResponse
    {
        $data = new RequestDataBag($request->request->all());

        return $this->contextGateway->process(new ContextGatewayPayloadStruct($cart, $context, $data));
    }
}
```

#### Storefront

A new `ContextGatewayController` for the Storefront will be introduced.
This controller will be the entry point for the Storefront client to interact with the `ContextGatewayRoute`.

Example implementation:

```php
<?php declare(strict_types=1);

#[Route(defaults: [PlatformRequest::ATTRIBUTE_ROUTE_SCOPE => [StorefrontRouteScope::ID]])]
class ContextGatewayController extends StorefrontController
{
    public function __construct(
        private readonly AbstractContextGatewayRoute $contextGatewayRoute,
        private readonly CartService $cartService,
    ) {
    }

    #[Route('/gateway/context', name: 'frontend.gateway.context', defaults: ['XmlHttpRequest' => true], methods: ['GET', 'POST'])]
    public function gateway(Request $request, SalesChannelContext $context): Response
    {
        $cart = $this->cartService->getCart($context->getToken(), $context);

        try {
            $response = $this->contextGatewayRoute->load($request, $cart, $context);
        } catch (\Throwable $e) {
            $this->addFlash(self::DANGER, $e->getMessage());
            return new JsonResponse(status: Response::HTTP_BAD_REQUEST);
        }

        return $response;
    }
}
```

#### Storefront SDK

Even though the client is free to initiate the context workflow in any manner,
as long as an `XMLHttpRequest` is made to the `/store-api/gateway/context` endpoint,
we propose the introduction of a helper class, `ContextGatewayClient`, within the Storefront SDK.

This client provides a convenient and consistent interface for apps to interact with the context gateway,
reducing the need for manual request setup and improving developer experience.

This client will work similarly to the existing `AppClient`,
but is specifically designed for initiating context gateway flows from the storefront.

The `ContextGatewayClient` will be instantiated with the app name
and expose a `request()` method to trigger the `/store-api/gateway/context` endpoint,
optionally including custom parameters.

Example implementation:

```typescript
export default class ContextGatewayClientService {
    private readonly name: string;

    constructor(name: string) {
        this.name = name;
    }
    
    public async request(options: Record<string, any> = {}, handleRedirect: boolean = true): Promise<Response> {
        const body = { appName: this.name, ...options };
        
        const requestOptions = {
            method: 'POST',
            headers: {
                'Content-Type': 'application/json',
                'X-Requested-With': 'XMLHttpRequest'
            },
            body: JSON.stringify(body)
        }
        
        const response = await fetch(window.router['frontend.gateway.context'], requestOptions);
        const result = await response.json();

        if (result.redirectUrl) {
            window.location.href = result.redirectUrl;
        }
        
        window.location.reload();
    }
}
```

#### App Manifest

To enable support for the `ContextGateway`, apps must declare a new endpoint in their `manifest.xml` file.
This is done by defining a `context` sub-key under the existing `<gateways>` section.
The provided URL will be called by the `AppContextGateway` when the context flow is initiated from the storefront.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest>
    <!-- ... -->

    <gateways>
        <!-- Optional: existing checkout gateway -->
        <!-- <checkout>https://example.com/checkout/gateway</checkout> -->

        <!-- Required for context gateway -->
        <context>https://example.com/context/gateway</context>
    </gateways>
</manifest>
```

### Command Structure

The `ContextGateway` will implement a command pattern inspired by the established structure used in the `CheckoutGateway`.

It will support a predefined set of commands that can be returned by the app server in the response.

Commands are executed **in the order they are provided**, with the following exception:

* The `context_register-customer` and `context_login-customer` commands are executed **first**, as they establish a new or updated context.
* All remaining commands will be executed **sequentially**, based on the order in the response, and operate on the resulting context.

This structure ensures that commands depending on user identity, language, or currency changes always act on the correct state.

#### Context Gateway App Payload

The app server receives a structured payload when invoked through the `AppContextGateway`.

The payload contains:

* The app source
* The current `SalesChannelContext`
* The current `Cart`
* Any **custom data** sent from the client (e.g., app name, user metadata, intent flags)

This payload enables app servers to make contextual decisions based on both the current session and additional input from the storefront.
Example payload sent to app-server:

```json5
{
    "source": {
        // information about the app source (version, shopId, etc.)
    },
    "salesChannelContext": SalesChannelContextObject,
    "cart": CartObject,
    "custom": {
        "anyCustomKey": "anyCustomValue"
        // "anyOtherCustomDataKey": "anyOtherCustomDataValue"
    },
    
}
```

Note that custom data sent by the client will be sent as a key-value pair under `custom` to the app-server.

#### Context Gateway App Response

Example response from app-server:

```json
[
  {
    "command": "context_register-customer",
    "payload": RegisterCustomerData,
  },
  {
    "command": "context_switch-language",
    "payload": {
        "iso": "de-DE"
    }
  },
  {
    "command": "context_switch-currency",
    "payload": {
        "iso": "USD"
    }
  }
]
```

Shopware will apply validation rules to ensure consistency and prevent conflicting command execution.

* The response must not contain more than **one `register-customer` or `login-customer` command**.
* All other command types must appear **at most once** in the response.

These constraints help prevent ambiguous or conflicting state changes during context manipulation.

### Command Structure

Each command in the context gateway is composed of two key elements:

* **Command class**\
  A class extending `AbstractContextGatewayCommand`.\
  This class holds the command’s payload and is uniquely identified by its command name.

* **Command handler class**\
  A class extending `AbstractContextGatewayCommandHandler`.\
  It contains the logic to execute supported commands and may handle multiple command types by implementing the `getSupportedCommands()` method.

This separation of data and execution logic ensures modularity and extensibility of the command processing system.

Example command class:

```php
<?php declare(strict_types=1);

class ChangeCurrencyCommand extends AbstractContextGatewayCommand
{
    public const COMMAND_KEY = 'context_change-currency';

    public function __construct(
        public readonly string $iso,
    ) {
    }

    public static function getDefaultKeyName(): string
    {
        return self::COMMAND_KEY;
    }
}
```

Example command handler class:

```php
<?php declare(strict_types=1);

class ChangeCurrencyCommandHandler extends AbstractContextGatewayCommandHandler
{
    public function __construct(
        private readonly EntityRepository $currencyRepository
    ) {
    }

    /**
     * @param ChangeCurrencyCommand $command
     */
    public function handle(AbstractContextGatewayCommand $command, SalesChannelContext $context, array &$parameters): void
    {
        $criteria = new Criteria();
        $criteria->addFilter(new EqualsFilter('isoCode', $command->iso));

        $currencyId = $this->currencyRepository->searchIds($criteria, $context->getContext())->firstId();

        if ($currencyId === null) {
            return;
        }

        // $parameters will be used by ContextSwitchRoute to update the context
        $parameters['currencyId'] = $currencyId;
    }

    public static function supportedCommands(): array
    {
        return [ChangeCurrencyCommand::class];
    }
```

#### Command Registry

Command handlers will be registered in the `ContextGatewayCommandRegistry` using a registry pattern.

All implementations of `AbstractContextGatewayCommandHandler` must be tagged with the `shopware.context.gateway.command` service tag.
This ensures they are automatically discovered and made available to the app system for command execution.

#### Event

A new event, `ContextGatewayCommandsCollectedEvent`, will be introduced.
This event is dispatched after the `AppContextGateway` collects all command responses from registered app servers, but before the commands are executed.

It allows plugins to inspect, modify, or append commands based on the full context and payload provided to the app servers.

## Consequences

### App PHP SDK

The `app-php-sdk` will be extended to support the new gateway and its data contract.

Enhancements include:

* Context gateway requests can be deserialized into a `ContextGatewayAction` object.
* Responses can easily be created with a `ContextGatewayResponse` object.
* Each supported context command will have a dedicated class, allowing strongly-typed manipulation and validation of its payload.

### App Bundle (Symfony)

The App Bundle will be updated to support the new gateway endpoint automatically.

Incoming context gateway requests and outgoing responses will be automatically resolved to the appropriate DTOs (`ContextGatewayAction`, `ContextGatewayResponse`),
making it seamless for app developers to implement handlers using standard Symfony controllers.

## Security Considerations

The `ContextGateway` introduces new responsibilities and associated risks due to its ability to manipulate the `SalesChannelContext`.

Potential concerns include:

* **Customer impersonation**: App servers have the ability to log in existing customers, even without knowing their passwords.
* **Trust boundary risks**: If an app server is compromised or malicious, it could exploit the gateway to impersonate users,
  access sensitive customer data, or perform unauthorized actions. However, this issue has always existed with the plugin system.

Particularly, allowing login based solely on an email address — without verifying credentials — poses a significant security risk.

### Mitigation

* Gateway command execution must enforce strict validation, logging, and safeguards (e.g., rate limiting).
* The ability to log in a customer should be gated by additional checks or explicit trust settings per app (a proposal could be custom ACL permissions per app and action).
* All actions performed via the context gateway should be auditable and traceable for monitoring and incident response.

---

---
url: /docs/guides/plugins/apps/gateways/context/command-reference.md
---

# Context Gateway Command Reference

## Available commands

| Command                            | Description                                                                                           | Payload                                                 | Since   |
|:-----------------------------------|:------------------------------------------------------------------------------------------------------|:--------------------------------------------------------|:--------|
| `context_add-customer-message` | Adds an error message to be displayed to the customer in the Storefront via FlashBag messages.        | `{"message": "string"}` | 6.7.1.0 |
| `context_change-billing-address` | Changes the billing address of a customer to the specified address ID.                                | `{"addressId": "string"}` | 6.7.1.0 |
| `context_change-shipping-address` | Changes the shipping address of a customer to the specified address ID.                               | `{"addressId": "string"}` | 6.7.1.0 |
| `context_change-currency` | Changes the active currency for a customer to the currency with the specified ISO 4217 currency code. | `{"iso": "string"}` | 6.7.1.0 |
| `context_change-language` | Changes the active language for a customer to the language with the specified BCP 47 language tag.    | `{"iso": "string"}` | 6.7.1.0 |
| `context_change-payment-method` | Changes the active payment method for a customer to the method with the specified technical name.     | `{"technicalName": "string"}` | 6.7.1.0 |
| `context_change-shipping-method` | Changes the active shipping method for a customer to the method with the specified technical name.    | `{"technicalName": "string"}` | 6.7.1.0 |
| `context_change-shipping-location` | Changes the active shipping location for a customer to the specified country/country state.         | `{"countryIso": "string", "countryStateIso": "string"}` | 6.7.1.0 |
| `context_login-customer` | Logs in an existing customer with the specified email.                                                | `{"customerEmail": "string"}` | 6.7.1.0 |
| `context_register-customer` | Register a new customer with the specified data and log them in.                                      | `{"data": "object (s. RegisterCustomerCommand)"}` | 6.7.1.0 |

## Available data for RegisterCustomerCommand

These properties can be set in the custom `data` object of the `context_register-customer` command.

| Field                    | Type   | Required                  | Description                                                                                                                   |
|:-------------------------|:-------|:--------------------------|-------------------------------------------------------------------------------------------------------------------------------|
| `title` | string |                           | The title of the customer, e.g., "Mr." or "Mrs."                                                                               |
| `accountType` | string |                           | The type of account, either "private" or "business"                                                                           |
| `firstName` | string | Yes                       | The first name of the customer                                                                                                |
| `lastName` | string | Yes                       | The last name of the customer                                                                                                 |
| `email` | string | Yes                       | The email address of the customer                                                                                             |
| `salutationId` | string |                           | The ID of the salutation to use for the customer                                                                              |
| `guest` | bool   |                           | Whether the customer is a guest (default: true)                                                                               |
| `storefrontUrl` | string | Yes                       | The storefront URL of the sales channel (You find available domains in the sales channel context -> sales channel -> domains) |
| `requestedGroupId` | string |                           | The ID of the customer group to assign to the customer                                                                        |
| `affiliateCode` | string |                           | The affiliate code to assign to the customer                                                                                  |
| `campaignCode` | string |                           | The campaign code to assign to the customer                                                                                   |
| `birthdayDay` | int    |                           | The day of the customer's birthday                                                                                            |
| `birthdayMonth` | int    |                           | The month of the customer's birthday                                                                                          |
| `birthdayYear` | int    |                           | The year of the customer's birthday                                                                                           |
| `password` | string | (for non-guest customers) | The password for the customer (plain text, will be hashed by the shop before being stored)                                              |
| `billingAddress` | object | Yes                       | The billing address of the customer, s. `AddressResponseStruct` for available fields                                          |
| `shippingAddress` | object |                           | The shipping address of the customer, s. `AddressResponseStruct` for available fields                                         |
| `vatIds` | array  |                           | An array of VAT IDs for the customer                                                                                          |
| `acceptedDataProtection` | bool   |                           | Whether the customer has accepted the data protection policy (default: false)                                                 |

### AddressResponseStruct

This structure is used for the `billingAddress` and `shippingAddress` fields in the `RegisterCustomerCommand`.

| Field                    | Type   | Required | Description                                           |
|:-------------------------|:-------|:---------|:------------------------------------------------------|
| `title` | string |          | The title of the address, e.g., "Mr." or "Mrs."        |
| `firstName` | string | Yes      | The first name of the address owner                   |
| `lastName` | string | Yes      | The last name of the address owner                    |
| `salutationId` | string |          | The ID of the salutation to use for the address owner |
| `street` | string | Yes      | The street of the address                             |
| `zipcode` | string | Yes      | The ZIP code of the address                           |
| `city` | string | Yes      | The city of the address                               |
| `company` | string |          | The company name for the address                      |
| `department` | string |          | The department name for the address                   |
| `countryStateId` | string |          | The ID of the country state for the address           |
| `countryId` | string | Yes      | The ID of the country for the address                 |
| `additionalAddressLine1` | string |          | Additional address line 1                             |
| `additionalAddressLine2` | string |          | Additional address line 2                             |
| `phoneNumber` | string |          | The phone number for the address                      |

---

---
url: /docs/v6.5/resources/guidelines/code/context-rules-rule-systems.md
---

# Context Rules and Rule Systems

* In a rule, there must never be a query against the database because all configured rules are validated in a request.
* Rules that check for the cart must always support the `\Shopware\Core\Checkout\Cart\Rule\CartRuleScope` class and the `\Shopware\Core\Checkout\Cart\Rule\LineItemScopeclass`.
* Rules may only access data provided in the appropriate scopes.

---

---
url: /docs/v6.6/resources/guidelines/code/context-rules-rule-systems.md
---

# Context Rules and Rule Systems

* In a rule, there must never be a query against the database because all configured rules are validated in a request.
* Rules that check for the cart must always support the `\Shopware\Core\Checkout\Cart\Rule\CartRuleScope` class and the `\Shopware\Core\Checkout\Cart\Rule\LineItemScopeclass`.
* Rules may only access data provided in the appropriate scopes.

---

---
url: /docs/guides/development/testing/ci.md
---

# Continuous Integration

Continuous Integration should, at a minimum, run static analysis and coding standards checks alongside the project or extension build to keep artifacts reproducible. Add sanity checks, such as smoke tests and lightweight integration tests, to catch regressions early.

Automated tests — unit, integration, and E2E where feasible — make refactors, upgrades, and dependency changes safer.

:::info
Follow the [Deployment guide](../../hosting/installation-updates/deployments/index.md) for information about promotion and release.
:::

## Cross-cutting practices

* Fail fast on coding standards and static analysis before slower E2E tests.
* Use the[Shopware CLI formatter](../../../products/tools/cli/formatter.md) to keep code style consistent and run the bundled validation tools in CI using [Shopware CLI validation tools](../../../products/tools/cli/validation.md).
* Produce artifacts once per commit (ZIP for plugins, deployment-ready image/package for apps, built assets for projects) and promote the same artifact through stages.

## Custom projects

* Reuse the [Project build command](../../../products/tools/cli/project-commands/build.md) to compile Storefront and Administration assets and warm caches. Run it in CI so deployments do not rebuild.
* Use environment-specific config only in deployment, not in CI. See [setup patterns](../../installation/index.md) you can mirror in pipelines.
* Add smoke tests against the HTTP layer plus DAL-level integration tests for custom entities.
* Cache Composer/NPM dependencies but keep lock files committed for deterministic builds.

## Custom/Store plugins

* Build and validate with [Extension build command](../../../products/tools/cli/extension-commands/build.md) to ensure the ZIP is reproducible.
* Run unit/integration tests with the Shopware test environment; keep fixtures inside the plugin to avoid coupling to project data.
* For Store plugins, add the Shopware Store validations early (linting, metadata, PHPStan) to catch review issues before submission [Store submission via CLI](../../../products/tools/cli/shopware-account-commands/releasing-extension-to-shopware-store.md).

---

---
url: /docs/resources/guidelines/code/contribution.md
---

# Contribution Guidelines

## Introduction

First of all, thank you! :)
You have decided to contribute code to our software and become a member of the large Shopware community.
We appreciate your hard work and want to handle it with the most possible respect.

To ensure the quality of our code and our products, we have created a list of guidelines for you.
It helps you and us to collaborate with our software.
Following these guidelines will help us integrate your changes into our daily workflow.

## Requirements for a successful pull request

To avoid your pull request getting rejected, you should always check that you provided all the necessary information so that we can easily integrate your changes.
Here is a checklist of requirements you should always consider when committing new changes:

* A pull request to the Shopware core always has to be made to the [main shopware](https://github.com/shopware/shopware) repository.

* Fill out the [pull request info template](https://github.com/shopware/shopware/blob/trunk/.github/PULL_REQUEST_TEMPLATE.md) as detailed as possible.

* If your change is relevant for the broader community document it in the `RELEASE_INFO` file, if you introduce a breaking change document it also in the `UPGRADE` file.

  Refer to the [release documentation guide](https://github.com/shopware/shopware/blob/trunk/delivery-process/documenting-a-release.md) for more detailed information about documenting your changes.

* Check if your pull request addresses the correct Shopware branch.
  It should always target the `trunk` branch.
  If you would like to have your changes in the previous major version, we have the possibility to do a backport quite easily.
  Let us know about this in the pull request description.

* Check if your implementation is missing some important parts - For example, translations, backwards compatibility, deprecations, etc.

* Provide tests for your implementation.

* Check if there is already an existing pull request tackling the same issue.

* Write your commit messages in English. The individual commit messages in the PR are not critical since the PR will be squashed on merge.
  However, ensure your **pull request title** follows the [Conventional Commits](https://www.conventionalcommits.org/) format, as this will become the final commit message.
  * Example PR titles:
    * `feat: Add new product import API`
    * `fix: Resolve cart calculation issue`
    * `docs: Update installation instructions`

::: danger
Pull requests which do not fulfill these requirements will most likely not be accepted by our team.
To avoid your changes going through unnecessary workflow cycles, make sure to check this list with every pull request.
:::

## The developing workflow on GitHub

When you create a new pull request on GitHub, please ensure:

1. Your PR title follows the **conventional commits** format as it will become the squashed commit message
2. You've provided all necessary information in the PR description
3. Your changes are complete and tested

You are responsible for maintaining and updating your pull request. This includes:

* Responding to review comments in a timely manner
* Updating the code according to review feedback
* Keeping the PR up to date with the target branch if conflicts arise
* Making sure that all pipeline checks succeed on your PR

::: tip
Once your PR is public, avoid rebasing or force-pushing to the branch.
Adding new commits makes it easier for reviewers to track changes and see what was updated in response to feedback.
The PR will be automatically squashed when merged.
:::

::: tip
Allow us to make changes to your PR.
This will help merge the PR faster, as we can fix minor issues ourselves.
Refer to the [GitHub Docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork) on how to do it.
:::

::: warning
Pull requests that become stale (no activity from the author for two weeks after a review or request for changes) will be closed.
You can always reopen the pull request when you're ready to continue working on it.
:::

## What happens after a pull request has been created

Everyday weekdays, we assign the pull request to a domain (team) which is responsible for the specific part of the Shopware software.
The area will then review your pull request and decide what to do next.
The team can either accept your pull request, decline it, or ask you to update it with more information or changes.

## Why a pull request gets declined

So the worst thing happened; Your pull request was declined.
No reason to be upset.
We know that it can sometimes be hard to understand why your pull request was rejected.
We want to be as transparent as possible, but sometimes it can also rely on internal decisions.

Here is a list of common reasons why we reject a pull request:

* The pull request does not fulfill the requirements of the list above.
* You did not update your pull request with the necessary info after a specific label was added.
* The change you made is already a part of a current change by Shopware and is handled internally.
* The benefit of your change is not relevant to the whole product but only to your intent.
* Your change implements a feature that does not fit our roadmap or our company values.

To avoid a decline of the PR beforehand, create a new issue or discussion in the Shopware repository.
Especially if you want to implement a new feature or change the behavior of an existing one.

---

---
url: /docs/v6.5/resources/guidelines/code/contribution.md
---

# Contribution Guidelines

## Introduction

First of all, thank you! :)
You have decided to contribute code to our software and become a member of the large Shopware community. We appreciate your hard work and want to handle it with the most possible respect.

To ensure the quality of our code and our products, we have created a list of guidelines for you. It helps you and us to collaborate with our software. Following these guidelines will help us integrate your changes into our daily workflow.

## Requirements for a successful pull request

To avoid your pull request getting rejected, you should always check that you provided all the necessary information so that we can easily integrate your changes into our internal workflow. Here is a checklist of requirements you should always consider when committing new changes:

* A pull request to the Shopware core always has to be made to the [main shopware](https://github.com/shopware/shopware) repository.
* Fill out the [pull request info template](https://github.com/shopware/shopware/blob/trunk/.github/PULL_REQUEST_TEMPLATE.md) as detailed as possible.
* Create a changelog file with documentation of your changes. Refer to [Changelog](https://github.com/shopware/shopware/blob/master/adr/2020-08-03-implement-new-changelog.md) section for more detailed information about writing changelog.
* Check if your pull request addresses the correct Shopware version. Breaks and features can't be merged in a patch release.
* Check if your implementation is missing some important parts - For example, translations, downward compatibility, compatibility with important plugins, etc.
* Provide the necessary tests for your implementation.
* Check if there is already an existing pull request tackling the same issue.
* Write your commit messages in English, have them short and descriptive, and squash your commits meaningfully.

::: danger
Pull requests which do not fulfill these requirements will never be accepted by our team. To avoid your changes going through unnecessary workflow cycles, make sure to check this list with every pull request.
:::

## The developing workflow on GitHub

When you create a new pull request on GitHub, it will normally get the first sight within a week. We do regular meetings to screen all new pull requests on GitHub. In this meeting, there is a team of Shopware developers of different specializations who will discuss your changes. Together we decide what will happen next to your pull request. We will set one of the following labels, which indicates the status of the pull request. Here is a list of all possible states:

|                                  GitHub Label / Tag                                  | What does it mean? |
|:------------------------------------------------------------------------------------:| :--- |
|       ![GitHub label incomplete](../../../assets/github-label-incomplete.png)        | Your pull request is incomplete. It is either missing some of the necessary information, or your code implementation is not sufficient to fix the issue. Mostly there will be a comment by our developers which gives you further information about what is missing.   **Important:** The label "Incomplete" means you have to take action. After your pull request has this label assigned, you have up to two weeks to update the pull request and provide the missing information or implementation. If there is no reaction from you within those two weeks, your pull request can be declined due to inactivity. This procedure ensures there are no orphaned pull requests in the backlog. |
|         ![GitHub label declined](../../../assets/github-label-declined.png)          | Your pull request was declined by our developers and is closed. We understand that it can sometimes be hard to understand the reason behind this. Mostly there will be a comment by our developers about why it was declined. |
|        ![GitHub label scheduled](../../../assets/github-label-scheduled.png)         | Your changes have been reviewed by our developers, and they decided that you provided a benefit for our product. Your pull request will be imported into our ticket system and will go through our internal workflow. You will find a comment containing the ticket number to follow the status. |
|        ![GitHub label quickpick](../../../assets/github-label-quickpick.png)         | The changes you provide seem to be easy to test and implement. Our developers decided to integrate this quickly into our software. There will probably be no ticket for this change to follow, but you will be informed by the accepted label on this pull request that your change was finally merged into the product. |
|         ![GitHub label accepted](../../../assets/github-label-accepted.png)          | Your changes are finally accepted. The pull request passed our internal workflow. Your changes will be released with one of the next releases. |
|      ![GitHub label feature request](../../../assets/github-label-feature.png)       | Your pull request includes a new feature that needs an internal discussion by our developers. We have to decide if the new feature provides a benefit for the product and at which point it should be scheduled on the roadmap. |
|      ![GitHub label refactoring](../../../assets/github-label-refactoring.png)       | Your pull request includes a larger refactoring which needs an internal discussion by our developers. This label will mainly be set when larger chunks of code have been re-written, renamed, or moved to different directories. |
|    ![GitHub label missing tests](../../../assets/github-label-missing-tests.png)     | Your pull request lacks the necessary tests for your changes. E.g. [Jest](../../../guides/plugins/plugins/testing/jest-admin) or [Cypress](../../../guides/plugins/plugins/testing/end-to-end-testing) tests for frontend changes or [PHPUnit](../../../guides/plugins/plugins/testing/php-unit) tests for backend changes. |

## Why a pull request gets declined

So the worst thing happened; Your pull request was declined. No reason to be upset. We know that it can sometimes be hard to understand why your pull request was rejected. We want to be as transparent as possible, but sometimes it can also rely on internal decisions.

Here is a list of common reasons why we reject a pull request:

* The pull request does not fulfill the requirements of the list above.
* You did not update your pull request with the necessary info after a specific label was added.
* The change you made is already a part of a current change by Shopware and is handled internally.
* The benefit of your change is not relevant to the whole product but only to your intent.
* The benefit of your change is too minor. Sometimes we do not have enough resources to handle every small change.
* Your change implements a feature that does not fit our roadmap or our company values.

---

---
url: /docs/v6.6/resources/guidelines/code/contribution.md
---

# Contribution Guidelines

## Introduction

First of all, thank you! :)
You have decided to contribute code to our software and become a member of the large Shopware community.
We appreciate your hard work and want to handle it with the most possible respect.

To ensure the quality of our code and our products, we have created a list of guidelines for you.
It helps you and us to collaborate with our software.
Following these guidelines will help us integrate your changes into our daily workflow.

## Requirements for a successful pull request

To avoid your pull request getting rejected, you should always check that you provided all the necessary information so that we can easily integrate your changes.
Here is a checklist of requirements you should always consider when committing new changes:

* A pull request to the Shopware core always has to be made to the [main shopware](https://github.com/shopware/shopware) repository.
* Fill out the [pull request info template](https://github.com/shopware/shopware/blob/trunk/.github/PULL_REQUEST_TEMPLATE.md) as detailed as possible.
* Create a changelog file with documentation of your changes.
  Refer to [Changelog](https://github.com/shopware/shopware/blob/master/adr/2020-08-03-implement-new-changelog.md) section for more detailed information about writing changelog.
* Check if your pull request addresses the correct Shopware branch.
  It should always target the `trunk` branch.
  If you would like to have your changes in the previous major version, we have the possibility to do a backport quite easily.
  Let us know about this in the pull request description.
* Check if your implementation is missing some important parts - For example, translations, backwards compatibility, deprecations, etc.
* Provide tests for your implementation.
* Check if there is already an existing pull request tackling the same issue.
* Write your commit messages in English. The individual commit messages in the PR are not critical since the PR will be squashed on merge.
  However, ensure your **pull request title** follows the [Conventional Commits](https://www.conventionalcommits.org/) format, as this will become the final commit message.
  * Example PR titles:
    * `feat: Add new product import API`
    * `fix: Resolve cart calculation issue`
    * `docs: Update installation instructions`

::: danger
Pull requests which do not fulfill these requirements will most likely not be accepted by our team.
To avoid your changes going through unnecessary workflow cycles, make sure to check this list with every pull request.
:::

## The developing workflow on GitHub

When you create a new pull request on GitHub, please ensure:

1. Your PR title follows the **conventional commits** format as it will become the squashed commit message
2. You've provided all necessary information in the PR description
3. Your changes are complete and tested

You are responsible for maintaining and updating your pull request. This includes:

* Responding to review comments in a timely manner
* Updating the code according to review feedback
* Keeping the PR up to date with the target branch if conflicts arise
* Making sure that all pipeline checks succeed on your PR

::: tip
Once your PR is public, avoid rebasing or force-pushing to the branch.
Adding new commits makes it easier for reviewers to track changes and see what was updated in response to feedback.
The PR will be automatically squashed when merged.
:::

::: tip
Allow us to make changes to your PR.
This will help merge the PR faster, as we can fix minor issues ourselves.
Refer to the [GitHub Docs](https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/allowing-changes-to-a-pull-request-branch-created-from-a-fork) on how to do it.
:::

::: warning
Pull requests that become stale (no activity from the author for two weeks after a review or request for changes) will be closed.
You can always reopen the pull request when you're ready to continue working on it.
:::

## What happens after a pull request has been created

Everyday weekdays, we assign the pull request to a domain (team) which is responsible for the specific part of the Shopware software.
The area will then review your pull request and decide what to do next.
The team can either accept your pull request, decline it, or ask you to update it with more information or changes.

## Why a pull request gets declined

So the worst thing happened; Your pull request was declined.
No reason to be upset.
We know that it can sometimes be hard to understand why your pull request was rejected.
We want to be as transparent as possible, but sometimes it can also rely on internal decisions.

Here is a list of common reasons why we reject a pull request:

* The pull request does not fulfill the requirements of the list above.
* You did not update your pull request with the necessary info after a specific label was added.
* The change you made is already a part of a current change by Shopware and is handled internally.
* The benefit of your change is not relevant to the whole product but only to your intent.
* Your change implements a feature that does not fit our roadmap or our company values.

To avoid a decline of the PR beforehand, create a new issue or discussion in the Shopware repository.
Especially if you want to implement a new feature or change the behavior of an existing one.

---

---
url: /docs/products/extensions/migration-assistant/concept/convert-and-mapping.md
---

# Convert and Mapping

## Overview

Data gathered by `Reader` objects is transferred to `Converter` objects that put the data in a format Shopware 6 is able to work with. Simultaneously entries in the underlying mapping table are inserted to map the old identifiers to the new ones for future migrations. The mapping is saved for the current connection. After the migration, the converted data will be removed, and the mapping will stay persistent.

## Converter

Converters are registered in the service container:

```php
$services->set(ProductConverter::class)
    ->abstract()
    ->parent(ShopwareConverter::class)
    ->args([
        // ...
    ]);
```

The converters have to extend the `ShopwareConverter` class and implement the `convert` method. This method will receive one data entry at a time. It will have to be returned in the right format to be usable for the `writer`.

```php
// SwagMigrationAssistant\Profile\Shopware\Converter\ProductConverter

abstract class ProductConverter extends ShopwareConverter
{
    // ...

    public function convert(
        array $data,
        Context $context,
        MigrationContextInterface $migrationContext
    ): ConvertStruct {
        $this->generateChecksum($data);

        // ...

        $converted = $this->getProductData($data, $converted);

        // ...

        $this->updateMainMapping($migrationContext, $context);

        // ...

        return new ConvertStruct($converted, $returnData, $mainMapping);
    }
}
```

As shown above, the `convert()` method accepts the source data, builds the necessary mappings, and returns a `ConvertStruct`. In a full implementation, converters do not perform validation of required or invalid fields. However, they should return early with a `ConvertStruct` that does not contain a converted entity if the data cannot reasonably be converted (for example, due to an unknown type).

Validation of the converted data is handled separately by the Error Resolution process, specifically through the `MigrationEntityValidationService` and the `MigrationFieldValidationService`.

Also, every `Converter` needs to implement the `getSourceIdentifier()` method like the below:

```php
// SwagMigrationAssistant\Profile\Shopware\Converter\ProductConverter

abstract class ProductConverter extends ShopwareConverter
{
    // ...

    public function getSourceIdentifier(array $data): string
    {
        return $data['detail']['ordernumber'];
    }
}
```

This is the main identifier of the incoming data, and it will be used to look for already migrated data (which will be covered later in this chapter by the Deltas concept).

## Mapping

Many entities rely on other entities, so they have to be converted in a specific order. Because of this and the Shopware Migration Assistant's ability to perform multiple migrations without resetting Shopware 6, source system identifiers must be mapped to their new counterparts. Find a mapping example in the following code snippet:

```php
// SwagMigrationAssistant\Profile\Shopware\Converter\ProductConverter

abstract class ProductConverter extends ShopwareConverter
{
    // ...

    private function getUuidForProduct(array &$data): array
    {
        $this->mainMapping = $this->mappingService->getOrCreateMapping(
            $this->connectionId,
            DefaultEntities::PRODUCT,
            $this->oldProductId,
            $this->context,
            $this->checksum
        );

        $converted = [];
        $converted['id'] = $this->mainMapping['entityId'];

        $mapping = $this->mappingService->getOrCreateMapping(
            $this->connectionId,
            DefaultEntities::PRODUCT_MAIN,
            $data['detail']['articleID'],
            $this->context,
            null,
            null,
            $converted['id']
        );

        // Take a look at the performance section below for details on this.
        $this->mappingIds[] = $mapping['id'];

        return $converted;
    }
}
```

The following function employs the `getOrCreateMapping()` function, which is part of the mapping service to acquire a unique identifier for the product that is about to get mapped to the source system's identifier and, at the same time, creating a new mapping entry in the `swag_migration_mapping` table. If there already is a unique identifier for the product, the `getOrCreateMapping()` method, instead of creating a duplicate entry, returns the existing identifier:

```php
// SwagMigrationAssistant\Migration\Mapping\MappingService

class MappingService implements MappingServiceInterface, ResetInterface
{
    // ...

    public function getOrCreateMapping(
        string $connectionId,
        string $entityName,
        string $oldIdentifier,
        Context $context,
        ?string $checksum = null,
        ?array $additionalData = null,
        ?string $uuid = null,
        ?string $entityValue = null,
    ): array {
        $mapping = $this->getMapping($connectionId, $entityName, $oldIdentifier, $context);

        if (!isset($mapping)) {
            return $this->createMapping($connectionId, $entityName, $oldIdentifier, $checksum, $additionalData, $uuid, $entityValue);
        }

        if ($additionalData !== null) {
            $mapping['additionalData'] = $additionalData;
        }

        if ($uuid !== null) {
            $mapping['entityId'] = $uuid;
        }

        if ($entityValue !== null) {
            $mapping['entityValue'] = $entityValue;
        }

        if (
            $uuid !== null
            || $additionalData !== null
            || $entityValue !== null
        ) {
            $this->saveMapping($mapping);
        }

        return $mapping;
    }
}
```

Sometimes it is not necessary to create a new identifier, and it may be enough to only get the mapping identifier. In the following example, there is an entity with a premapping and the converter simply uses the mapping service's `getMapping()` method:

```php
// SwagMigrationAssistant\Profile\Shopware\Converter\CustomerConverter

abstract class CustomerConverter extends ShopwareConverter
{
    // ...

    protected function getDefaultPaymentMethod(array $originalData): ?string
    {
        $paymentMethodMapping = $this->mappingService->getMapping(
            $this->connectionId,
            PaymentMethodReader::getMappingName(),
            $originalData['id'],
            $this->context
        );

        if ($paymentMethodMapping === null) {
            $this->loggingService->log(
                MigrationLogBuilder::fromMigrationContext($this->migrationContext)
                    ->withEntityName(CustomerDefinition::ENTITY_NAME)
                    ->withFieldName('defaultPaymentMethodId')
                    ->withFieldSourcePath('default_payment_method')
                    ->withSourceData($originalData)
                    ->build(ConvertEntityUnknownLog::class)
            );

            return null;
        }

        $this->mappingIds[] = $paymentMethodMapping['id'];

        return $paymentMethodMapping['entityId'];
    }
}
```

The `getMapping()` method only fetches the identifier from the database and doesn't create a new one:

```php
// SwagMigrationAssistant\Migration\Mapping\MappingService

class MappingService implements MappingServiceInterface, ResetInterface
{
    // ...

    public function getMapping(
        string $connectionId,
        string $entityName,
        string $oldIdentifier,
        Context $context,
    ): ?array {
        $cacheKey = $entityName . $oldIdentifier;
        if (isset($this->mappings[$cacheKey])) {
            return $this->mappings[$cacheKey];
        }

        $sql = 'SELECT id,
                       connection_id AS connectionId,
                       entity,
                       old_identifier AS oldIdentifier,
                       entity_id AS entityId,
                       entity_value AS entityValue,
                       checksum,
                       additional_data AS additionalData
                FROM swag_migration_mapping
                WHERE connection_id = :connectionId
                    AND entity = :entity
                    AND old_identifier = :oldIdentifier;';

        $mapping = $this->connection->fetchAssociative($sql, ['connectionId' => Uuid::fromHexToBytes($connectionId), 'entity' => $entityName, 'oldIdentifier' => $oldIdentifier]);

        if ($mapping === false) {
            return null;
        }

        $mapping['id'] = Uuid::fromBytesToHex($mapping['id']);
        $mapping['connectionId'] = Uuid::fromBytesToHex($mapping['connectionId']);
        $mapping['entityId'] = $mapping['entityId'] === null ? null : Uuid::fromBytesToHex($mapping['entityId']);

        if (!empty($mapping['additionalData'])) {
            $mapping['additionalData'] = \json_decode($mapping['additionalData'], true, 512, \JSON_THROW_ON_ERROR);
        } else {
            $mapping['additionalData'] = null;
        }

        $mapping['oldIdentifier'] = $mapping['oldIdentifier'] === null ? null : (string) $mapping['oldIdentifier'];
        $mapping['entityValue'] = $mapping['entityValue'] === null ? null : (string) $mapping['entityValue'];
        $mapping['checksum'] = $mapping['checksum'] === null ? null : (string) $mapping['checksum'];

        $this->mappings[$cacheKey] = $mapping;

        return $mapping;
    }
}
```

## Deltas

One of the parameters for the `getOrCreateMapping()` Method is the `checksum`. It is used to identify unchanged data (source system data that has not been changed since the last migration). This will greatly improve the performance of future migrations.

To get this checksum, you can use the `generateChecksum()` method of the base `Converter` class:

```php
// SwagMigrationAssistant\Migration\Converter\Converter

abstract class Converter implements ConverterInterface
{
   // ...

    /**
     * Generates a unique checksum for the data array to recognize changes
     * on repeated migrations.
     *
     * @param array<mixed> $data
     */
    protected function generateChecksum(array $data): void
    {
        $this->checksum = Hasher::hash(\serialize($data));
    }
}
```

This is used in the first line of the converter with the raw data that comes from the `Reader` object:

```php
// SwagMigrationAssistant\Profile\Shopware\Converter\ProductConverter

abstract class ProductConverter extends ShopwareConverter
{
    // ...

    public function convert(
        array $data,
        Context $context,
        MigrationContextInterface $migrationContext
    ): ConvertStruct {
        $this->generateChecksum($data);

        // ...
    }
}
```

For the checksum to be saved to the right mapping, make sure that you set the `mainMapping` attribute of the base `Converter` class. Internally the checksum of the main mapping of an entity will be compared to the incoming data checksum and if it is the same, it will be skipped by the converter and also by the writer (you will not receive the data with the same checksum in your converter), which increases the performance of repeated migrations massively. For more information, look at the corresponding `filterDeltas()` method in the `MigrationDataConverter` class. Important for the delta concept is to return the `mainMapping` with the `ConvertStruct`. This is necessary to map the converted data to the main mapping entry.

## Additional performance tips

The `Converter` base class also contains an array named `mappingIds`. This can be filled with all mapping IDs related to the current data. Internally the related mappings will be fetched all at once in future migrations, which reduces the performance impact of `getMapping()` calls (because not every call needs to query data from the database). So it is advised to add related mapping IDs in the following manner:

```php
// SwagMigrationAssistant\Profile\Shopware\Converter\ProductConverter

abstract class ProductConverter extends ShopwareConverter
{
    // ...

    private function getUnit(array $data): array
    {
        $unit = [];
        $mapping = $this->mappingService->getOrCreateMapping(
            $this->connectionId,
            DefaultEntities::UNIT,
            $data['id'],
            $this->context
        );
        $unit['id'] = $mapping['entityId'];
        $this->mappingIds[] = $mapping['id'];

        $this->applyUnitTranslation($unit, $data);
        $this->convertValue($unit, 'shortCode', $data, 'unit');
        $this->convertValue($unit, 'name', $data, 'description');

        return $unit;
    }
}
```

To save these mapping IDs in the `mainMapping`, it is necessary to call the `updateMainMapping()` before returning the `ConvertStruct`:

```php
// SwagMigrationAssistant\Profile\Shopware\Converter\ProductConverter

abstract class ProductConverter extends ShopwareConverter
{
    // ...

    public function convert(
        array $data,
        Context $context,
        MigrationContextInterface $migrationContext
    ): ConvertStruct {
        // ...

        $this->updateMainMapping($migrationContext, $context);

        $mainMapping = $this->mainMapping['id'] ?? null;

        return new ConvertStruct($converted, $returnData, $mainMapping);
    }
}
```

---

---
url: >-
  /docs/v6.5/products/extensions/migration-assistant/concept/convert-and-mapping.md
---

# Convert and Mapping

## Overview

Data gathered by `Reader` objects is transferred to `Converter` objects that put the data in a format Shopware 6 is able to work with. Simultaneously entries in the underlying mapping table are inserted to map the old identifiers to the new ones for future migrations. The mapping is saved for the current connection. After the migration, the converted data will be removed, and the mapping will stay persistent.

## Converter

All converters are registered in service container like this:

```html
<service id="SwagMigrationAssistant\Profile\Shopware\Converter\ProductConverter"
         parent="SwagMigrationAssistant\Profile\Shopware\Converter\ShopwareConverter" abstract="true">
    <argument type="service" id="SwagMigrationAssistant\Migration\Media\MediaFileService"/>
</service>
```

The converters have to extend the `ShopwareConverter` class and implement the `convert` method. This method will receive one data entry at a time. It will have to be returned in the right format to be usable for the `writer`.

```php
<?php declare(strict_types=1);

/* SwagMigrationAssistant/Profile/Shopware/Converter/ProductConverter.php */

abstract class ProductConverter extends ShopwareConverter
{
    /* ... */

    /**
     * @throws ParentEntityForChildNotFoundException
     */
    public function convert(
        array $data,
        Context $context,
        MigrationContextInterface $migrationContext
    ): ConvertStruct {
        $this->generateChecksum($data);
        $this->context = $context;
        $this->migrationContext = $migrationContext;
        $this->runId = $migrationContext->getRunUuid();
        $this->oldProductId = $data['detail']['ordernumber'];
        $this->mainProductId = $data['detail']['articleID'];
        $this->locale = $data['_locale'];

        $connection = $migrationContext->getConnection();
        $this->connectionName = '';
        $this->connectionId = '';
        if ($connection !== null) {
            $this->connectionId = $connection->getId();
            $this->connectionName = $connection->getName();
        }

        $fields = $this->checkForEmptyRequiredDataFields($data, $this->requiredDataFieldKeys);
        if (!empty($fields)) {
            $this->loggingService->addLogEntry(new EmptyNecessaryFieldRunLog(
                $this->runId,
                DefaultEntities::PRODUCT,
                $this->oldProductId,
                implode(',', $fields)
            ));

            return new ConvertStruct(null, $data);
        }

        $this->productType = (int) $data['detail']['kind'];
        unset($data['detail']['kind']);
        $isProductWithVariant = $data['configurator_set_id'] !== null;

        if ($this->productType === self::MAIN_PRODUCT_TYPE && $isProductWithVariant) {
            return $this->convertMainProduct($data);
        }

        if ($this->productType === self::VARIANT_PRODUCT_TYPE && $isProductWithVariant) {
            return $this->convertVariantProduct($data);
        }

        $converted = $this->getUuidForProduct($data);
        $converted = $this->getProductData($data, $converted);

        if (isset($data['categories'])) {
            $converted['categories'] = $this->getCategoryMapping($data['categories']);
        }
        unset($data['categories']);

        if (isset($data['shops'])) {
            $converted['visibilities'] = $this->getVisibilities($converted, $data['shops']);
        }
        unset($data['shops']);

        unset($data['detail']['id'], $data['detail']['articleID']);

        if (empty($data['detail'])) {
            unset($data['detail']);
        }

        $returnData = $data;
        if (empty($returnData)) {
            $returnData = null;
        }
        $this->updateMainMapping($migrationContext, $context);

        $mainMapping = $this->mainMapping['id'] ?? null;

        return new ConvertStruct($converted, $returnData, $mainMapping);
    }

    /* ... */
}
```

As you see above, the `convert` method gets the source system data, checks with `checkForEmptyRequiredDataFields` if the necessary data fields are filled, and returns a `ConvertStruct`. The `ConvertStruct` contains the converted value in the structure of Shopware 6 and all source system data which could not be mapped to the Shopware 6 structure. If the required fields are not filled, the convert method returns a `ConvertStruct` without a `converted` value and all of the given source system data as the `unmapped` value.

Also, every `Converter` needs to implement the `getSourceIdentifier` method like the below:

```php
/* SwagMigrationAssistant/Profile/Shopware/Converter/ProductConverter.php */

/**
 * Get the identifier of the source data, which is only known to the converter
 */
public function getSourceIdentifier(array $data): string
{
    return $data['detail']['ordernumber'];
}
```

This is the main identifier of the incoming data, and it will be used to look for already migrated data (which will be covered later in this chapter by the Deltas concept).

## Mapping

Many entities rely on other entities, so they have to be converted in a specific order. Because of this and the Shopware Migration Assistant's ability to perform multiple migrations without resetting Shopware 6, source system identifiers must be mapped to their new counterparts. Find a mapping example in the following code snippet:

```php
/* SwagMigrationAssistant/Profile/Shopware/Converter/ProductConverter.php */

private function getUuidForProduct(array &$data): array
{
    $this->mainMapping = $this->mappingService->getOrCreateMapping(
        $this->connectionId,
        DefaultEntities::PRODUCT,
        $this->oldProductId,
        $this->context,
        $this->checksum
    );

    $converted = [];
    $converted['id'] = $this->mainMapping['entityUuid'];

    $mapping = $this->mappingService->getOrCreateMapping(
        $this->connectionId,
        DefaultEntities::PRODUCT_MAIN,
        $data['detail']['articleID'],
        $this->context,
        null,
        null,
        $converted['id']
    );
    $this->mappingIds[] = $mapping['id']; // Take a look at the performance section below for details on this.

    return $converted;
}
```

The following function employs the `getOrCreateMapping` function, which is part of the mapping service to acquire a unique identifier for the product that is about to get mapped to the source system's identifier and, at the same time, creating a new mapping entry in the `swag_migration_mapping` table. If there already is a unique identifier for the product, the `getOrCreateMapping` method, instead of creating a duplicate entry, returns the existing identifier:

```php
/* SwagMigrationAssistant/Migration/Mapping/MappingService.php */

public function getOrCreateMapping(
    string $connectionId,
    string $entityName,
    string $oldIdentifier,
    Context $context,
    ?string $checksum = null,
    ?array $additionalData = null,
    ?string $uuid = null
): array {
    $mapping = $this->getMapping($connectionId, $entityName, $oldIdentifier, $context);

    if (!isset($mapping)) {
        return $this->createMapping($connectionId, $entityName, $oldIdentifier, $checksum, $additionalData, $uuid);
    }

    if ($uuid !== null) {
        $mapping['entityUuid'] = $uuid;
        $this->saveMapping($mapping);

        return $mapping;
    }

    return $mapping;
}
```

Sometimes it is not necessary to create a new identifier, and it may be enough to only get the mapping identifier. In the following example, there is an entity with a premapping and the converter simply uses the mapping service's `getMapping` method:

```php
/* SwagMigrationAssistant/Profile/Shopware/Converter/CustomerConverter.php */

protected function getDefaultPaymentMethod(array $originalData): ?string
{
    $paymentMethodMapping = $this->mappingService->getMapping(
        $this->connectionId,
        PaymentMethodReader::getMappingName(),
        $originalData['id'],
        $this->context
    );

    if ($paymentMethodMapping === null) {
        $this->loggingService->addLogEntry(new UnknownEntityLog(
            $this->runId,
            DefaultEntities::PAYMENT_METHOD,
            $originalData['id'],
            DefaultEntities::CUSTOMER,
            $this->oldCustomerId
        ));

        return null;
    }
    $this->mappingIds[] = $paymentMethodMapping['id'];

    return $paymentMethodMapping['entityUuid'];
}
```

The `getMapping` method only fetches the identifier from the database and doesn't create a new one:

```php
/* SwagMigrationAssistant/Migration/Mapping/MappingService.php */

public function getMapping(
    string $connectionId,
    string $entityName,
    string $oldIdentifier,
    Context $context
): ?array {
    if (isset($this->mappings[md5($entityName . $oldIdentifier)])) {
        return $this->mappings[md5($entityName . $oldIdentifier)];
    }

    $criteria = new Criteria();
    $criteria->addFilter(new EqualsFilter('connectionId', $connectionId));
    $criteria->addFilter(new EqualsFilter('entity', $entityName));
    $criteria->addFilter(new EqualsFilter('oldIdentifier', $oldIdentifier));
    $criteria->setLimit(1);

    $result =  $this->migrationMappingRepo->search($criteria, $context);

    if ($result->getTotal() > 0) {
        /** @var SwagMigrationMappingEntity $element */
        $element = $result->getEntities()->first();

        $mapping = [
            'id' => $element->getId(),
            'connectionId' => $element->getConnectionId(),
            'entity' => $element->getEntity(),
            'oldIdentifier' => $element->getOldIdentifier(),
            'entityUuid' => $element->getEntityUuid(),
            'checksum' => $element->getChecksum(),
            'additionalData' => $element->getAdditionalData(),
        ];
        $this->mappings[md5($entityName . $oldIdentifier)] = $mapping;

        return $mapping;
    }

    return null;
}
```

## Deltas

One of the parameters for the `getOrCreateMapping` Method is the `checksum`. It is used to identify unchanged data (source system data that has not been changed since the last migration). This will greatly improve the performance of future migrations.

To get this checksum, you can use the `generateChecksum` method of the base `Converter` class:

```php
/* SwagMigrationAssistant/Migration/Converter/Converter.php */

/**
 * Generates a unique checksum for the data array to recognize changes
 * on repeated migrations.
 */
protected function generateChecksum(array $data): void
{
    $this->checksum = md5(serialize($data));
}
```

This is used in the first line of the converter with the raw data that comes from the `Reader` object:

```php
/* SwagMigrationAssistant/Profile/Shopware/Converter/ProductConverter.php */

public function convert(
    array $data,
    Context $context,
    MigrationContextInterface $migrationContext
): ConvertStruct {
    $this->generateChecksum($data);

    /* ... */

    // This is also important, so the checksum can be saved to the right mapping!
    $this->mainMapping = $this->mappingService->getOrCreateMapping(
        $this->connectionId,
        DefaultEntities::PRODUCT,
        $this->oldProductId,
        $this->context,
        $this->checksum
    );

    /* ... */

    // Important to put the mainMapping['id'] to the ConvertStruct
    $mainMapping = $this->mainMapping['id'] ?? null;
    return new ConvertStruct($converted, $returnData, $mainMapping);

    /* ... */
}
```

For the checksum to be saved to the right mapping, make sure that you set the `mainMapping` attribute of the base `Converter` class. Internally the checksum of the main mapping of an entity will be compared to the incoming data checksum and if it is the same, it will be skipped by the converter and also by the writer (you will not receive the data with the same checksum in your converter), which increases the performance of repeated migrations massively. For more information, look at the corresponding `filterDeltas` method in the `MigrationDataConverter` class. Important for the delta concept is to return the `mainMapping` with the `ConvertStruct`. This is necessary to map the converted data to the main mapping entry.

## Additional performance tips

The `Converter` base class also contains an array named `mappingIds`. This can be filled with all mapping IDs related to the current data. Internally the related mappings will be fetched all at once in future migrations, which reduces the performance impact of `getMapping` calls (because not every call needs to query data from the database). So it is advised to add related mapping IDs in the following manner:

```php
/* SwagMigrationAssistant/Profile/Shopware/Converter/ProductConverter.php */

private function getUnit(array $data): array
{
    $unit = [];
    $mapping = $this->mappingService->getOrCreateMapping(
        $this->connectionId,
        DefaultEntities::UNIT,
        $data['id'],
        $this->context
    );
    $unit['id'] = $mapping['entityUuid'];
    $this->mappingIds[] = $mapping['id']; // Store the mapping id as related mapping

    $this->getUnitTranslation($unit, $data);
    $this->convertValue($unit, 'shortCode', $data, 'unit');
    $this->convertValue($unit, 'name', $data, 'description');

    return $unit;
}
```

To save these mapping IDs in the `mainMapping`, it is necessary to call the `updateMainMapping` before returning the `ConvertStruct`:

```php
/* SwagMigrationAssistant/Profile/Shopware/Converter/ProductConverter.php */

public function convert(
    array $data,
    Context $context,
    MigrationContextInterface $migrationContext
): ConvertStruct {
    /* ... */

    $this->updateMainMapping($this->migrationContext, $this->context);

    $mainMapping = $this->mainMapping['id'] ?? null;

    return new ConvertStruct($converted, $returnData, $mainMapping);

    /* ... */
}
```

---

---
url: >-
  /docs/v6.6/products/extensions/migration-assistant/concept/convert-and-mapping.md
---

# Convert and Mapping

## Overview

Data gathered by `Reader` objects is transferred to `Converter` objects that put the data in a format Shopware 6 is able to work with. Simultaneously entries in the underlying mapping table are inserted to map the old identifiers to the new ones for future migrations. The mapping is saved for the current connection. After the migration, the converted data will be removed, and the mapping will stay persistent.

## Converter

All converters are registered in service container like this:

```html
<service id="SwagMigrationAssistant\Profile\Shopware\Converter\ProductConverter"
         parent="SwagMigrationAssistant\Profile\Shopware\Converter\ShopwareConverter" abstract="true">
    <argument type="service" id="SwagMigrationAssistant\Migration\Media\MediaFileService"/>
</service>
```

The converters have to extend the `ShopwareConverter` class and implement the `convert` method. This method will receive one data entry at a time. It will have to be returned in the right format to be usable for the `writer`.

```php
<?php declare(strict_types=1);

/* SwagMigrationAssistant/Profile/Shopware/Converter/ProductConverter.php */

abstract class ProductConverter extends ShopwareConverter
{
    /* ... */

    /**
     * @throws ParentEntityForChildNotFoundException
     */
    public function convert(
        array $data,
        Context $context,
        MigrationContextInterface $migrationContext
    ): ConvertStruct {
        $this->generateChecksum($data);
        $this->context = $context;
        $this->migrationContext = $migrationContext;
        $this->runId = $migrationContext->getRunUuid();
        $this->oldProductId = $data['detail']['ordernumber'];
        $this->mainProductId = $data['detail']['articleID'];
        $this->locale = $data['_locale'];

        $connection = $migrationContext->getConnection();
        $this->connectionName = '';
        $this->connectionId = '';
        if ($connection !== null) {
            $this->connectionId = $connection->getId();
            $this->connectionName = $connection->getName();
        }

        $fields = $this->checkForEmptyRequiredDataFields($data, $this->requiredDataFieldKeys);
        if (!empty($fields)) {
            $this->loggingService->addLogEntry(new EmptyNecessaryFieldRunLog(
                $this->runId,
                DefaultEntities::PRODUCT,
                $this->oldProductId,
                implode(',', $fields)
            ));

            return new ConvertStruct(null, $data);
        }

        $this->productType = (int) $data['detail']['kind'];
        unset($data['detail']['kind']);
        $isProductWithVariant = $data['configurator_set_id'] !== null;

        if ($this->productType === self::MAIN_PRODUCT_TYPE && $isProductWithVariant) {
            return $this->convertMainProduct($data);
        }

        if ($this->productType === self::VARIANT_PRODUCT_TYPE && $isProductWithVariant) {
            return $this->convertVariantProduct($data);
        }

        $converted = $this->getUuidForProduct($data);
        $converted = $this->getProductData($data, $converted);

        if (isset($data['categories'])) {
            $converted['categories'] = $this->getCategoryMapping($data['categories']);
        }
        unset($data['categories']);

        if (isset($data['shops'])) {
            $converted['visibilities'] = $this->getVisibilities($converted, $data['shops']);
        }
        unset($data['shops']);

        unset($data['detail']['id'], $data['detail']['articleID']);

        if (empty($data['detail'])) {
            unset($data['detail']);
        }

        $returnData = $data;
        if (empty($returnData)) {
            $returnData = null;
        }
        $this->updateMainMapping($migrationContext, $context);

        $mainMapping = $this->mainMapping['id'] ?? null;

        return new ConvertStruct($converted, $returnData, $mainMapping);
    }

    /* ... */
}
```

As you see above, the `convert` method gets the source system data, checks with `checkForEmptyRequiredDataFields` if the necessary data fields are filled, and returns a `ConvertStruct`. The `ConvertStruct` contains the converted value in the structure of Shopware 6 and all source system data which could not be mapped to the Shopware 6 structure. If the required fields are not filled, the convert method returns a `ConvertStruct` without a `converted` value and all of the given source system data as the `unmapped` value.

Also, every `Converter` needs to implement the `getSourceIdentifier` method like the below:

```php
/* SwagMigrationAssistant/Profile/Shopware/Converter/ProductConverter.php */

/**
 * Get the identifier of the source data, which is only known to the converter
 */
public function getSourceIdentifier(array $data): string
{
    return $data['detail']['ordernumber'];
}
```

This is the main identifier of the incoming data, and it will be used to look for already migrated data (which will be covered later in this chapter by the Deltas concept).

## Mapping

Many entities rely on other entities, so they have to be converted in a specific order. Because of this and the Shopware Migration Assistant's ability to perform multiple migrations without resetting Shopware 6, source system identifiers must be mapped to their new counterparts. Find a mapping example in the following code snippet:

```php
/* SwagMigrationAssistant/Profile/Shopware/Converter/ProductConverter.php */

private function getUuidForProduct(array &$data): array
{
    $this->mainMapping = $this->mappingService->getOrCreateMapping(
        $this->connectionId,
        DefaultEntities::PRODUCT,
        $this->oldProductId,
        $this->context,
        $this->checksum
    );

    $converted = [];
    $converted['id'] = $this->mainMapping['entityUuid'];

    $mapping = $this->mappingService->getOrCreateMapping(
        $this->connectionId,
        DefaultEntities::PRODUCT_MAIN,
        $data['detail']['articleID'],
        $this->context,
        null,
        null,
        $converted['id']
    );
    $this->mappingIds[] = $mapping['id']; // Take a look at the performance section below for details on this.

    return $converted;
}
```

The following function employs the `getOrCreateMapping` function, which is part of the mapping service to acquire a unique identifier for the product that is about to get mapped to the source system's identifier and, at the same time, creating a new mapping entry in the `swag_migration_mapping` table. If there already is a unique identifier for the product, the `getOrCreateMapping` method, instead of creating a duplicate entry, returns the existing identifier:

```php
/* SwagMigrationAssistant/Migration/Mapping/MappingService.php */

public function getOrCreateMapping(
    string $connectionId,
    string $entityName,
    string $oldIdentifier,
    Context $context,
    ?string $checksum = null,
    ?array $additionalData = null,
    ?string $uuid = null
): array {
    $mapping = $this->getMapping($connectionId, $entityName, $oldIdentifier, $context);

    if (!isset($mapping)) {
        return $this->createMapping($connectionId, $entityName, $oldIdentifier, $checksum, $additionalData, $uuid);
    }

    if ($uuid !== null) {
        $mapping['entityUuid'] = $uuid;
        $this->saveMapping($mapping);

        return $mapping;
    }

    return $mapping;
}
```

Sometimes it is not necessary to create a new identifier, and it may be enough to only get the mapping identifier. In the following example, there is an entity with a premapping and the converter simply uses the mapping service's `getMapping` method:

```php
/* SwagMigrationAssistant/Profile/Shopware/Converter/CustomerConverter.php */

protected function getDefaultPaymentMethod(array $originalData): ?string
{
    $paymentMethodMapping = $this->mappingService->getMapping(
        $this->connectionId,
        PaymentMethodReader::getMappingName(),
        $originalData['id'],
        $this->context
    );

    if ($paymentMethodMapping === null) {
        $this->loggingService->addLogEntry(new UnknownEntityLog(
            $this->runId,
            DefaultEntities::PAYMENT_METHOD,
            $originalData['id'],
            DefaultEntities::CUSTOMER,
            $this->oldCustomerId
        ));

        return null;
    }
    $this->mappingIds[] = $paymentMethodMapping['id'];

    return $paymentMethodMapping['entityUuid'];
}
```

The `getMapping` method only fetches the identifier from the database and doesn't create a new one:

```php
/* SwagMigrationAssistant/Migration/Mapping/MappingService.php */

public function getMapping(
    string $connectionId,
    string $entityName,
    string $oldIdentifier,
    Context $context
): ?array {
    if (isset($this->mappings[md5($entityName . $oldIdentifier)])) {
        return $this->mappings[md5($entityName . $oldIdentifier)];
    }

    $criteria = new Criteria();
    $criteria->addFilter(new EqualsFilter('connectionId', $connectionId));
    $criteria->addFilter(new EqualsFilter('entity', $entityName));
    $criteria->addFilter(new EqualsFilter('oldIdentifier', $oldIdentifier));
    $criteria->setLimit(1);

    $result =  $this->migrationMappingRepo->search($criteria, $context);

    if ($result->getTotal() > 0) {
        /** @var SwagMigrationMappingEntity $element */
        $element = $result->getEntities()->first();

        $mapping = [
            'id' => $element->getId(),
            'connectionId' => $element->getConnectionId(),
            'entity' => $element->getEntity(),
            'oldIdentifier' => $element->getOldIdentifier(),
            'entityUuid' => $element->getEntityUuid(),
            'checksum' => $element->getChecksum(),
            'additionalData' => $element->getAdditionalData(),
        ];
        $this->mappings[md5($entityName . $oldIdentifier)] = $mapping;

        return $mapping;
    }

    return null;
}
```

## Deltas

One of the parameters for the `getOrCreateMapping` Method is the `checksum`. It is used to identify unchanged data (source system data that has not been changed since the last migration). This will greatly improve the performance of future migrations.

To get this checksum, you can use the `generateChecksum` method of the base `Converter` class:

```php
/* SwagMigrationAssistant/Migration/Converter/Converter.php */

/**
 * Generates a unique checksum for the data array to recognize changes
 * on repeated migrations.
 */
protected function generateChecksum(array $data): void
{
    $this->checksum = md5(serialize($data));
}
```

This is used in the first line of the converter with the raw data that comes from the `Reader` object:

```php
/* SwagMigrationAssistant/Profile/Shopware/Converter/ProductConverter.php */

public function convert(
    array $data,
    Context $context,
    MigrationContextInterface $migrationContext
): ConvertStruct {
    $this->generateChecksum($data);

    /* ... */

    // This is also important, so the checksum can be saved to the right mapping!
    $this->mainMapping = $this->mappingService->getOrCreateMapping(
        $this->connectionId,
        DefaultEntities::PRODUCT,
        $this->oldProductId,
        $this->context,
        $this->checksum
    );

    /* ... */

    // Important to put the mainMapping['id'] to the ConvertStruct
    $mainMapping = $this->mainMapping['id'] ?? null;
    return new ConvertStruct($converted, $returnData, $mainMapping);

    /* ... */
}
```

For the checksum to be saved to the right mapping, make sure that you set the `mainMapping` attribute of the base `Converter` class. Internally the checksum of the main mapping of an entity will be compared to the incoming data checksum and if it is the same, it will be skipped by the converter and also by the writer (you will not receive the data with the same checksum in your converter), which increases the performance of repeated migrations massively. For more information, look at the corresponding `filterDeltas` method in the `MigrationDataConverter` class. Important for the delta concept is to return the `mainMapping` with the `ConvertStruct`. This is necessary to map the converted data to the main mapping entry.

## Additional performance tips

The `Converter` base class also contains an array named `mappingIds`. This can be filled with all mapping IDs related to the current data. Internally the related mappings will be fetched all at once in future migrations, which reduces the performance impact of `getMapping` calls (because not every call needs to query data from the database). So it is advised to add related mapping IDs in the following manner:

```php
/* SwagMigrationAssistant/Profile/Shopware/Converter/ProductConverter.php */

private function getUnit(array $data): array
{
    $unit = [];
    $mapping = $this->mappingService->getOrCreateMapping(
        $this->connectionId,
        DefaultEntities::UNIT,
        $data['id'],
        $this->context
    );
    $unit['id'] = $mapping['entityUuid'];
    $this->mappingIds[] = $mapping['id']; // Store the mapping id as related mapping

    $this->getUnitTranslation($unit, $data);
    $this->convertValue($unit, 'shortCode', $data, 'unit');
    $this->convertValue($unit, 'name', $data, 'description');

    return $unit;
}
```

To save these mapping IDs in the `mainMapping`, it is necessary to call the `updateMainMapping` before returning the `ConvertStruct`:

```php
/* SwagMigrationAssistant/Profile/Shopware/Converter/ProductConverter.php */

public function convert(
    array $data,
    Context $context,
    MigrationContextInterface $migrationContext
): ConvertStruct {
    /* ... */

    $this->updateMainMapping($this->migrationContext, $this->context);

    $mainMapping = $this->mainMapping['id'] ?? null;

    return new ConvertStruct($converted, $returnData, $mainMapping);

    /* ... */
}
```

---

---
url: /docs/concepts/commerce/content/cookie-consent-management.md
---

# Cookie Consent Management

## Overview

Shopware provides a cookie consent management system with features designed to support GDPR compliance. The system allows shop administrators and developers to manage cookies transparently and give customers control over their data privacy. It handles cookie categorization, user consent tracking, and automatic re-consent when cookie configurations change.

::: warning
While Shopware provides tools and features to help with GDPR compliance, shop owners are ultimately responsible for ensuring their shop complies with GDPR and other applicable data protection regulations. This includes proper cookie configuration, privacy policies, and legal review of all data processing activities.
:::

::: info
The cookie-hash and re-consent functionality is available starting with Shopware 6.7.3.0.
:::

## How it works

The cookie consent system operates through several integrated components:

1. **Cookie Provider Service**: Collects all cookie definitions from core, plugins, and apps
2. **Store API Endpoint**: Exposes cookie configuration with a configuration hash
3. **Storefront Component**: Manages the cookie consent UI and user preferences
4. **Configuration Hash**: Tracks changes to trigger re-consent when needed

### Cookie Configuration Flow

```mermaid
sequenceDiagram
    participant User
    participant Storefront
    participant StoreAPI
    participant CookieProvider

    User->>Storefront: Visit shop
    Storefront->>StoreAPI: GET /store-api/cookie/groups
    StoreAPI->>CookieProvider: getCookieGroups()
    CookieProvider-->>StoreAPI: Cookie groups + hash
    StoreAPI-->>Storefront: Cookie configuration
    Storefront->>Storefront: Compare stored hash for current language
    alt Hash changed for language
        Storefront->>User: Show consent banner
    else Hash matches for language
        Storefront->>User: Apply stored preferences
    end
    User->>Storefront: Make choices
    Storefront->>Storefront: Store preferences + hash (with language ID)
```

## Cookie Categories

Cookies in Shopware are organized into four main categories according to GDPR requirements:

### Technically Required

Cookies that are essential for the shop to function (`cookie.groupRequired`). These cookies cannot be disabled by users.

**Examples:**

* Session management
* Shopping cart
* Security tokens
* Language preferences

### Comfort Functions

Cookies that enhance user experience but are not essential for basic functionality (`cookie.groupComfortFeatures`).

**Examples:**

* Video platform cookies (YouTube, Vimeo)
* Social media integrations
* Chat widgets
* Personalized content

### Marketing

Cookies used for marketing and advertising purposes, including tracking user behavior for personalized ads and remarketing (`cookie.groupMarketing`).

**Examples:**

* Marketing pixels (Facebook Pixel, Google Ads)
* Remarketing and advertising cookies
* Conversion tracking
* Affiliate tracking

### Statistics and Tracking

Cookies used for analytics and website optimization purposes (`cookie.groupStatistical`).

**Examples:**

* Google Analytics
* User interaction tracking (Hotjar, Crazy Egg)
* A/B testing
* User behavior analytics

## Configuration Hash Mechanism

The configuration hash is an important feature that helps support GDPR compliance by ensuring users are re-prompted when cookie handling changes.

### Mechanism Details

1. **Hash Generation**: A hash is calculated from all cookie configurations (names, descriptions, expiration times)
2. **Hash Storage**: The hash is stored in the browser as `cookie-config-hash`. The stored value is an object where the language ID is the key and the cookie hash is the value, for example: `{"019ada128cfb711aa7a0d00f476d5961":"998cdcc090e92b3ecdd057241d0fd01f"}`
3. **Change Detection**: On each visit, the current hash is compared with the stored hash for the current language
4. **Re-Consent Trigger**: If hashes differ for the current language, all non-essential cookies are removed and consent is requested again

::: info
**Domain and Language Handling**: Since cookies are stored per domain by the browser, installations using different domains for different languages don't encounter tracking conflicts. The domain itself serves as the primary separator. The language ID within the hash object is specifically designed to address scenarios where multiple languages are served from the same domain, ensuring proper per-language consent tracking.
:::

### When Hash Changes

The configuration hash changes when:

* New cookies are added by plugins/apps
* Existing cookies are modified or removed
* Cookie groups are restructured
* Cookie descriptions or settings change

This ensures users are always informed about changes to cookie handling, maintaining GDPR compliance.

## Cookie Groups vs Individual Cookies

### Individual Cookies

Single cookies that can be accepted or rejected independently.

**Use when:**

* Cookie serves a specific, standalone purpose
* No logical grouping with other cookies
* Maximum granular control needed

### Cookie Groups

Multiple related cookies grouped together for easier management.

**Use when:**

* Multiple cookies serve the same purpose (e.g., video platform)
* Cookies are interdependent
* Simplified user interface is desired

**Example:** YouTube group containing multiple YouTube-related cookies

## Key Cookies Used by the System

The cookie consent system itself uses special cookies:

| Cookie | Purpose | Lifetime |
|--------|---------|----------|
| `cookie-preference` | Stores user's consent choices | 30 days |
| `cookie-config-hash` | Tracks configuration changes per language | 30 days |

### Protected Cookies

Certain cookies are **never removed** by the consent system, even during re-consent:

* `session-*` - Session cookies required for shop functionality
* `timezone` - User's timezone preference

## Technical Implementation

Cookie configurations are defined using structured objects for type safety:

* **`CookieEntry`** - Individual cookie definition
* **`CookieGroup`** - Group of related cookies

This provides better IDE support, type checking, and consistency across implementations.

## Store API Integration

::: info
The Store API endpoint for cookie groups is available starting with Shopware 6.7.3.0.
:::

The cookie consent system exposes its configuration through the Store API endpoint:

**Endpoint:** `GET /store-api/cookie/groups`

This endpoint enables headless implementations, custom frontends, and third-party integrations to retrieve cookie configuration, the configuration hash, and the language ID. The hash is provided as a string, and the language ID is also returned by the endpoint. When stored in the browser's `cookie-config-hash` cookie, both values should be stored as an object where the language ID is the key and the hash is the value, for example: `{"019ada128cfb711aa7a0d00f476d5961":"998cdcc090e92b3ecdd057241d0fd01f"}`

For full API documentation, see the [Store API - Fetch all cookie groups](https://shopware.stoplight.io/docs/store-api/f9c70be044a15-fetch-all-cookie-groups) reference.

## Extension Points

The cookie consent system can be extended in multiple ways:

### For Plugins

Use an event listener to add custom cookies.

### For Apps

Define cookies in your `manifest.xml` file.

### JavaScript Events

React to user consent changes in your custom JavaScript.

## Best Practices

### 1. Categorize Correctly

Place cookies in the appropriate category:

* Only truly essential cookies should be "technically required" (`cookie.groupRequired`)
* User convenience features belong in "comfort functions" (`cookie.groupComfortFeatures`)
* Marketing and advertising cookies belong in "marketing" (`cookie.groupMarketing`)
* Analytics and optimization belong in "statistics and tracking" (`cookie.groupStatistical`)

### 2. Provide Clear Descriptions

Write clear, user-friendly cookie descriptions:

* Explain what the cookie does in simple terms
* Mention what data is collected
* State how long the cookie persists
* Link to privacy policy if relevant

### 3. Set Appropriate Expiration

Choose sensible expiration times:

* Session cookies for temporary data
* Days/weeks for user preferences
* Months/year for long-term settings
* Consider GDPR recommendations

### 4. Handle Consent Changes

Always check consent status before:

* Loading third-party scripts
* Setting marketing or advertising cookies
* Collecting analytics or statistics data
* Storing user behavior data

### 5. Test Re-Consent Flow

When updating cookie configurations:

* Test that hash changes trigger re-consent
* Verify non-essential cookies are removed
* Check that protected cookies remain
* Ensure UI displays correctly

## Features Supporting GDPR Compliance

Shopware's cookie consent system includes several features designed to help shop owners meet GDPR requirements:

* ✅ **Opt-in by default** - Users must actively consent (no pre-checked boxes)
* ✅ **Granular control** - Users can accept/reject individual categories
* ✅ **Re-consent on changes** - Automatic re-prompting when configuration changes
* ✅ **Clear information** - Transparent cookie descriptions and purposes
* ✅ **Easy withdrawal** - Users can change preferences at any time
* ✅ **Configuration tracking** - Hash mechanism ensures change detection
* ✅ **Documented lifecycle** - Full audit trail of cookie changes

::: info
These features provide technical support for GDPR compliance, but shop owners must also ensure they have proper legal documentation (privacy policy, terms of service), data processing agreements, and regular compliance audits. Consult with legal counsel to ensure full compliance with GDPR and other applicable regulations.
:::

---

---
url: /docs/guides/development/testing/store/cookies-and-privacy.md
---

# Cookies and privacy

Register cookies correctly in the [Cookie Consent Manager](../../../plugins/plugins/storefront/advanced/add-cookie-to-manager.md).

* Every cookie set from the store URL should be optional and not classified as technically required for running Shopware unless it truly is. We use **Technically required**, **Marketing**, and **Comfort features** (see below).
* All cookies must appear **unchecked** by default in the cookie configuration UI in the storefront, except where law and product behavior explicitly require otherwise.

## Cookie categories

Cookies may only be assigned to one of these categories in the Cookie Consent Manager:

* **Technically required** — Only cookies strictly necessary for the shop to function.
* **Marketing** — Analytics or data collection.
* **Comfort features** — Everything that does not fit the other two but is needed for a specific feature.

**Example:** A pop-up reminder cookie is not technically required; use Comfort features or tie it to the session cookie where appropriate.

## Privacy and personal data (DSGVO)

If personal data of customers (merchant and/or end customers) is processed with the extension under Art. 28 DSGVO:

* Enter the data processor’s details in **Subprocessor**.
* Enter any further processors under **Further subprocessors**.

If external services transmit personal data or are in use, this should be specified in the description.

---

---
url: /docs/products/extensions/b2b-suite/guides/core.md
---

# Core

The B2B Suite Core component includes features such as dependency injection, REST API, CRUD service, audit log, exception handling, currency management, entity-based access control, storefront authentication, and more. These features enable efficient B2B transactions, data management, security, and integration with other systems.

---

---
url: /docs/v6.5/products/extensions/b2b-suite/guides/core.md
---

# Core

The B2B Suite Core component includes features such as dependency injection, REST API, CRUD service, audit log, exception handling, currency management, entity-based access control, storefront authentication, and more. These features enable efficient B2B transactions, data management, security, and integration with other systems.

---

---
url: /docs/v6.6/products/extensions/b2b-suite/guides/core.md
---

# Core

The B2B Suite Core component includes features such as dependency injection, REST API, CRUD service, audit log, exception handling, currency management, entity-based access control, storefront authentication, and more. These features enable efficient B2B transactions, data management, security, and integration with other systems.

---

---
url: /docs/resources/references/core-reference.md
---

# Core Reference

The Core reference documents essential components like the DAL, administration panel, flags, filters, Flow Builder, and Rules for efficient platform usage. It details about the classes, methods, commands, events, etc, for your reference. This helps you understand how to use these features to enhance the functionality.

---

---
url: /docs/v6.5/resources/references/core-reference.md
---

# Core Reference

The Core reference documents essential components like the DAL, administration panel, flags, filters, Flow Builder, and Rules for efficient platform usage. It details about the classes, methods, commands, events, etc, for your reference. This helps you understand how to use these features to enhance the functionality.

---

---
url: /docs/v6.6/resources/references/core-reference.md
---

# Core Reference

The Core reference documents essential components like the DAL, administration panel, flags, filters, Flow Builder, and Rules for efficient platform usage. It details about the classes, methods, commands, events, etc, for your reference. This helps you understand how to use these features to enhance the functionality.

---

---
url: /frontends/guides/e-commerce/checkout.md
---

# Create a checkout

In this chapter you will learn how to

* Fetch and display payment and shipping information
* Create an order summary (totals, taxes)
* Place an order

## Shipping and payment information

:::warning
Please remember that payment and shipping methods shouldn't be cached.
It is important to refresh data before displaying it.
:::

Before fetching, ensure the cart is not empty by using `refreshCart` in the `useCart` composable.

**Get shipping methods**

```ts
const { getShippingMethods } = useCheckout();

await getShippingMethods();
```

**Display shipping methods**

```vue
<script setup lang="ts">
const {
  shippingMethods,
  setShippingMethod,
  selectedShippingMethod: shippingMethod,
  getShippingMethods,
} = useCheckout();

const selectedShippingMethod = computed({
  get(): string {
    return shippingMethod.value?.id || "";
  },
  async set(shippingMethodId: string) {
    await setShippingMethod({ id: shippingMethodId });
  },
});
</script>
<template>
  <div v-for="shippingMethod in shippingMethods" :key="shippingMethod.id">
    <input
      :id="shippingMethod.id"
      v-model="selectedShippingMethod"
      :value="shippingMethod.id"
      name="shipping-method"
      type="radio"
    />
    <label :for="shippingMethod.id">
      {{ shippingMethod.name }}
    </label>
  </div>
</template>
```

The shipping method position on the list is determined by the `position` field settled on the admin panel. Sorting logic in `useCheckout.ts::getShippingMethods()`

You can also display:

* Shipping delivery time
* Shipping icon
* Shipping description

**Get payment methods**

```ts
const { getPaymentMethods } = useCheckout();

await getPaymentMethods();
```

**Display payment methods**

```vue
<script setup lang="ts">
const {
  paymentMethods,
  selectedPaymentMethod: paymentMethod,
  setPaymentMethod,
} = useCheckout();

const selectedPaymentMethod = computed({
  get(): string {
    return paymentMethod.value?.id || "";
  },
  async set(paymentMethodId: string) {
    await setPaymentMethod({ id: paymentMethodId });
  },
});
</script>
<template>
  <div v-for="paymentMethod in paymentMethods" :key="paymentMethod.id">
    <input
      :id="paymentMethod.id"
      v-model="selectedPaymentMethod"
      :value="paymentMethod.id"
      name="payment-method"
      type="radio"
    />
    <label :for="paymentMethod.id">
      {{ paymentMethod.name }}
    </label>
  </div>
</template>
```

## Personal information

Each guest user has to provide billing data.
Those data will be used to create a standard or temporary account.

```vue
<script setup lang="ts">
const state = reactive({
  salutationId: "",
  firstName: "",
  lastName: "",
  email: "",
  password: "",
  guest: false,
  billingAddress: {
    street: "",
    zipcode: "",
    city: "",
    countryId: "",
  },
});
const { register } = useUser();
const { getCountries } = useCountries();
const { getSalutations } = useSalutations();
const invokeSubmit = () => {
  register(state);
};
</script>
<template>
  <form
    id="checkout-billing-address"
    name="checkout-billing-address"
    method="post"
    @submit.prevent="invokeSubmit"
  >
    <label for="salutation">Salutation</label>
    <select id="salutation" v-model="state.salutationId" name="salutation">
      <option disabled selected value="">Choose salutation...</option>
      <option
        v-for="salutation in getSalutations"
        :key="salutation.id"
        :value="salutation.id"
      >
        {{ salutation.displayName }}
      </option>
    </select>

    <label for="first-name">First name</label>
    <input
      id="first-name"
      v-model="state.firstName"
      type="text"
      name="first-name"
    />

    <label for="last-name">Last name</label>
    <input
      id="last-name"
      v-model="state.lastName"
      type="text"
      name="last-name"
    />

    <input id="create-account" v-model="state.guest" type="checkbox" />
    <label for="create-account">Do not create a customer account.</label>

    <label for="email-address">Email address</label>
    <input
      id="email-address"
      v-model="state.email"
      type="email"
      name="email-address"
    />

    <div v-if="!state.guest">
      <label for="password">Password</label>
      <input
        id="password"
        v-model="state.password"
        type="password"
        name="password"
      />
    </div>

    <label for="street-address">Street address</label>
    <input
      id="street-address"
      v-model="state.billingAddress.street"
      type="text"
      name="street-address"
    />

    <label for="postal-code">ZIP / Postal code</label>
    <input
      id="postal-code"
      v-model="state.billingAddress.zipcode"
      type="text"
      name="postal-code"
    />

    <label for="city">City</label>
    <input
      id="city"
      v-model="state.billingAddress.city"
      type="text"
      name="city"
    />

    <label for="country">Country</label>
    <select
      id="country"
      v-model="state.billingAddress.countryId"
      name="country"
    >
      <option disabled selected value="">Choose country...</option>
      <option
        v-for="country in getCountries"
        :key="country.id"
        :value="country.id"
      >
        {{ country.name }}
      </option>
    </select>

    <button type="submit">Save</button>
  </form>
</template>
```

## Order summary

We can use some helper methods from `useCart` composable to display an order summary and format prices.

Refer to [formatting prices](prices.html) for more information on displaying prices.

:::warning
Totals should **not** be calculated by the frontend. All calculations should be done on the backend side.
:::

```vue
<script setup lang="ts">
const { refreshCart, cartItems, subtotal, totalPrice, shippingTotal } =
  useCart();
const { getFormattedPrice } = usePrice();
await refreshCart();
</script>
<template>
  <div>
    <div>
      <p>Subtotal</p>
      <p>{{ getFormattedPrice(subtotal) }}</p>
    </div>
    <div>
      <p>Shipping estimate</p>
      <p>{{ getFormattedPrice(shippingTotal) }}</p>
    </div>
    <div>
      <p>Order total</p>
      <p>{{ getFormattedPrice(totalPrice) }}</p>
    </div>
  </div>
</template>
```

## Place an order

Placing an order requires

* A valid shipping address
* A selected payment method
* A selected shipping method

After placing an order with the `createOrder` method, the cart is refreshed automatically.

```ts
const { createOrder } = useCheckout();
const { refreshCart } = useCart();

const order = await createOrder();
refreshCart();
```

After creating an order, you can fetch order data. `orderId` is returned by the `createOrder` method from the `useCheckout` composable.
The backend allows fetching orders related only to the current user by checking the session.

```ts
const {
  loadOrderDetails,
  personalDetails,
  billingAddress,
  shippingAddress,
  order,
} = useOrderDetails({ order: { id: orderId } as any });

await loadOrderDetails();
```

## Guest checkout boundaries

Guest checkout uses the active Shopware customer from the current session
context. After a guest order is placed, do not let a later buyer continue with
the same guest context. A changed email, first name, or last name should start a
new guest registration instead of updating the existing guest address.

For simple synchronous flows, rotate the context with `logout()` after the order
is placed and before starting a new checkout. `logout()` refreshes the session
context and throws if the new context cannot be verified, so block checkout
progression when it fails.

```ts
const { logout } = useUser();

try {
  await logout();
} catch (error) {
  // Keep the user on a recoverable state instead of reusing the old guest.
  console.error("[Checkout][logout]", error);
}
```

For asynchronous payment or order-processing flows, the application backend
should own the boundary. Keep the old context token only while payment handlers
or recovery jobs still need it, expose the current boundary state to checkout
bootstrap, and block a second checkout until the first order is terminal or the
guest context has been safely rotated. Do not rely on success-page lifecycle
hooks such as route leave or unmount handlers as the authority for guest
rotation; the user can reload, close the tab, or open checkout in another tab.

---

---
url: /docs/v6.5/guides/plugins/themes/create-a-theme.md
---

# Create a First Theme

## Overview

This guide will show you how to create a theme from scratch. You will also learn how to install and activate your theme.

## Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files, as well as the command line.

## Create your first plugin theme

Let's get started with creating your plugin by finding a proper name for it.

### Name your plugin theme

First, you need to find a name for your theme. We're talking about a technical name here, so it needs to describe your theme appearance as short as possible, written in UpperCamelCase. To prevent issues with duplicated theme names, you should add a shorthand prefix for your company.\
Shopware uses "Swag" as a prefix for that case.\
For this example guide we'll use the theme name **SwagBasicExampleTheme.**

::: info
Notice: The name of a theme must begin with a capital letter too!
:::

### Create a plugin-based theme

Now that you've found your name, it's time to actually create your plugin.

Open your terminal and run the following command to create a new theme

```bash
bin/console theme:create SwagBasicExampleTheme

# you should get an output like this:

Creating theme structure under .../development/custom/plugins/SwagBasicExampleTheme
```

After your theme was created successfully Shopware has to know that it now exists. You have to refresh the plugin list by running the following command.

```bash
bin/console plugin:refresh

# you should get an output like this

[OK] Plugin list refreshed                                                                              

Shopware Plugin Service
=======================

 ----------------------- ------------------------------------ ------------- ----------------- -------- ----------- -------- ------------- 
  Plugin                  Label                                Version       Upgrade version   Author   Installed   Active   Upgradeable  
 ----------------------- ------------------------------------ ------------- ----------------- -------- ----------- -------- ------------- 
  SwagBasicExampleTheme   Theme SwagBasicExampleTheme plugin   9999999-dev                              No          No       No           
 ----------------------- ------------------------------------ ------------- ----------------- -------- ----------- -------- ------------- 

 1 plugins, 0 installed, 0 active , 0 upgradeable
```

Now Shopware recognises your plugin theme. The next step is the installation and activation of your theme. Run the following command in terminal.

```bash
# run this command to install and activate your plugin
bin/console plugin:install --activate SwagBasicExampleTheme

Shopware Plugin Lifecycle Service
=================================

 Install 1 plugin(s):
 * Theme SwagBasicExampleTheme plugin (vdev-trunk)

 Plugin "SwagBasicExampleTheme" has been installed and activated successfully.

 [OK] Installed 1 plugin(s).
```

Your theme was successfully installed and activated.

The last thing we need to do to work with the theme is to assign it to a sales channel. You can do that by running the `theme:change` command in the terminal and follow the instructions.

```bash
# run this to change the current Storefront theme
$ bin/console theme:change

# you will get an interactive prompt to change the 
# current theme of the Storefront like this

Please select a sales channel:
[0] Storefront | 64bbbe810d824c339a6c191779b2c205
[1] Headless | 98432def39fc4624b33213a56b8c944d
> 0

Please select a theme:
[0] Storefront
[1] SwagBasicExampleTheme
> 1

Set "SwagBasicExampleTheme" as new theme for sales channel "Storefront"
Compiling theme 13e0a4a46af547479b1347617926995b for sales channel SwagBasicExampleTheme
```

At first, we have to select a sales channel. The obvious choice here is the 'Storefront'. Afterwards enter the number for our theme.

Now your theme is fully installed, and you can start your customization.

### Directory structure of a theme

```bash
# structure of a plugin-based theme
├── composer.json
└── src
    ├── Resources
    │   ├── app
    │   │   └── storefront
    │   │       ├── dist
    │   │       │   └── storefront
    │   │       │       └── js
    │   │       │           └── swag-basic-example-theme.js
    │   │       └── src
    │   │           ├── assets
    │   │           ├── main.js
    │   │           └── scss
    │   │               ├── base.scss
    │   │               └── overrides.scss
    │   └── theme.json
    └── SwagBasicExampleTheme.php
```

## Next steps

Now that you have created your own theme, the next step is to learn how to make settings and adjustments.

* [Theme configuration](theme-configuration)
* [Add SCSS Styling and JavaScript to a theme](add-css-js-to-theme)
* [Add assets to theme](add-assets-to-theme)

---

---
url: /docs/v6.6/guides/plugins/themes/create-a-theme.md
---

# Create a First Theme

## Overview

This guide will show you how to create a theme from scratch. You will also learn how to install and activate your theme.

## Prerequisites

All you need for this guide is a running Shopware 6 instance and full access to both the files, as well as the command line.

## Create your first plugin theme

Let's get started with creating your plugin by finding a proper name for it.

### Name your plugin theme

First, you need to find a name for your theme. We're talking about a technical name here, so it needs to describe your theme appearance as short as possible, written in UpperCamelCase. To prevent issues with duplicated theme names, you should add a shorthand prefix for your company.\
Shopware uses "Swag" as a prefix for that case.\
For this example guide we'll use the theme name **SwagBasicExampleTheme.**

::: info
Notice: The name of a theme must begin with a capital letter too!
:::

### Create a plugin-based theme

Now that you've found your name, it's time to actually create your plugin.

Open your terminal and run the following command to create a new theme

```bash
bin/console theme:create SwagBasicExampleTheme

# you should get an output like this:

Creating theme structure under .../development/custom/plugins/SwagBasicExampleTheme
```

After your theme was created successfully Shopware has to know that it now exists. You have to refresh the plugin list by running the following command.

```bash
bin/console plugin:refresh

# you should get an output like this

[OK] Plugin list refreshed                                                                              

Shopware Plugin Service
=======================

 ----------------------- ------------------------------------ ------------- ----------------- -------- ----------- -------- ------------- 
  Plugin                  Label                                Version       Upgrade version   Author   Installed   Active   Upgradeable  
 ----------------------- ------------------------------------ ------------- ----------------- -------- ----------- -------- ------------- 
  SwagBasicExampleTheme   Theme SwagBasicExampleTheme plugin   9999999-dev                              No          No       No           
 ----------------------- ------------------------------------ ------------- ----------------- -------- ----------- -------- ------------- 

 1 plugins, 0 installed, 0 active , 0 upgradeable
```

Now Shopware recognises your plugin theme. The next step is the installation and activation of your theme. Run the following command in terminal.

```bash
# run this command to install and activate your plugin
bin/console plugin:install --activate SwagBasicExampleTheme

Shopware Plugin Lifecycle Service
=================================

 Install 1 plugin(s):
 * Theme SwagBasicExampleTheme plugin (vdev-trunk)

 Plugin "SwagBasicExampleTheme" has been installed and activated successfully.

 [OK] Installed 1 plugin(s).
```

Your theme was successfully installed and activated.

The last thing we need to do to work with the theme is to assign it to a sales channel. You can do that by running the `theme:change` command in the terminal and follow the instructions.

```bash
# run this to change the current Storefront theme
$ bin/console theme:change

# you will get an interactive prompt to change the 
# current theme of the Storefront like this

Please select a sales channel:
[0] Storefront | 64bbbe810d824c339a6c191779b2c205
[1] Headless | 98432def39fc4624b33213a56b8c944d
> 0

Please select a theme:
[0] Storefront
[1] SwagBasicExampleTheme
> 1

Set "SwagBasicExampleTheme" as new theme for sales channel "Storefront"
Compiling theme 13e0a4a46af547479b1347617926995b for sales channel SwagBasicExampleTheme
```

At first, we have to select a sales channel. The obvious choice here is the 'Storefront'. Afterwards enter the number for our theme.

Now your theme is fully installed, and you can start your customization.

### Directory structure of a theme

```bash
# structure of a plugin-based theme
├── composer.json
└── src
    ├── Resources
    │   ├── app
    │   │   └── storefront
    │   │       ├── dist
    │   │       │   └── storefront
    │   │       │       └── js
    |   |       |           └── swag-basic-example-theme  
    │   │       │               └── swag-basic-example-theme.js
    │   │       └── src
    │   │           ├── assets
    │   │           ├── main.js
    │   │           └── scss
    │   │               ├── base.scss
    │   │               └── overrides.scss
    │   └── theme.json
    └── SwagBasicExampleTheme.php
```

## Next steps

Now that you have created your own theme, the next step is to learn how to make settings and adjustments.

* [Theme configuration](theme-configuration)
* [Add SCSS Styling and JavaScript to a theme](add-css-js-to-theme)
* [Add assets to theme](add-assets-to-theme)

---

---
url: /frontends/guides/page-elements/footer-navigation.md
---

# Create a footer navigation

Implementing a footer navigation can be described in a few steps:

1. Use the [useNavigation](../../packages/composables/useNavigation) composable to `loadNavigationElements` and display a navigation configured in the admin panel.
2. Iterate over the `navigationElements` array of categories and display them.
3. Add some static links next to the dynamic ones if needed.
4. Resolve URLs and implement dedicated pages for them.

## Code example

```vue
<script setup lang="ts">
import { useNavigation } from "@shopware/composables";
import { getCategoryRoute } from "@shopware/helpers";
const { navigationElements, loadNavigationElements } = useNavigation({
  type: "footer-navigation", // footer-navigation selected
});
loadNavigationElements({
  // invoke an API call to fetch navigation categories
  depth: 1,
});
</script>
<template>
  <Transition>
    <footer v-if="navigationElements.length" class="bg-white dark:bg-gray-900">
      <div class="mx-auto w-full max-w-screen-xl">
        <div class="grid grid-cols-2 gap-8 px-4 py-6 lg:py-8 md:grid-cols-4">
          <div v-for="category in navigationElements" :key="category.id">
            <h2
              class="mb-6 text-sm font-semibold text-gray-900 uppercase dark:text-white"
            >
              {{ category.translated.name }}
            </h2>
            <ul
              class="text-gray-500 dark:text-gray-400 font-medium"
              v-if="category?.childCount"
            >
              <li
                class="mb-4"
                v-for="childCategory in category.children"
                :key="childCategory.id"
              >
                <a
                  :href="getCategoryRoute(childCategory)"
                  class="hover:underline"
                  >{{ childCategory.translated.name }}</a
                >
              </li>
            </ul>
          </div>
        </div>
      </div>
    </footer>
  </Transition>
  <style scoped>
    .v-enter-active,
    .v-leave-active {
      transition: opacity 0.5s ease;
    }

    .v-enter-from,
    .v-leave-to {
      opacity: 0;
    }
  </style>
</template>
```

[getCategoryUrl](../../packages/helpers#getcategoryurl) method imported from the `helpers` package can extract a SEO URL or technical URL for a given category.

:::warning
`getCategoryUrl` returns an absolute path for the corresponding category, which means you will get for example `/some-category/some-subcategory` and not the entire URL including domain.

By design, the URL can also point to a Product or Landing Page.
In order to resolve an entity assigned to each category path, utilize a [composable](../../packages/composables/useNavigation) dedicated for the expected entity:

1. `search` from `useNavigationSearch` to find the entity type.
2. Use a [dedicated composable](../routing.html#resolve-a-route-to-a-page) to process page resolving.
   :::

---

---
url: /frontends/guides/page-elements/login-form.md
---

# Create a login form

In this chapter, you will learn how to

* Sign in using username and password
* Display data of an authenticated user
* Display authentication errors
* Logout

## Build the form

Let us start by providing some reactive objects and input elements to get customer login credentials from the browser.

```vue{3,4,10,11}
<script setup lang="ts">
    const loginCredentials = reactive({
        username: "",
        password: "",
    })
    const invokeLogin = () => {}
</script>
<template>
    <div>
        <input type="text" v-model="loginCredentials.username" />
        <input type="password" v-model="loginCredentials.password" />

        <button @click="invokeLogin">Sign in</button>
    </div>
</template>
```

## Manage the user session

Now, the presentation layer has all required fields to perform a login process.

In the next step, use the `useUser` composable. It provides user data, login methods, and other interfaces.

```vue
<script setup lang="ts">
const {
  login, // login method, accepts username and password
  logout, // performing a logout
  errors, // errors from API prefixed with a method name, which is the source of the problem
  isLoggedIn, // flag that says if customer is logged in
  user, // the whole customer object
} = useUser();

const invokeLogin = () => login(loginCredentials);
</script>
...
```

The `invokeLogin` method is triggered using the `@click` event of the button. It executes the `login()` method from the `useUser` composable, accepting `loginCredentials` (the `v-model` of inputs) as an argument.

## Display user data

If the login process was successful, the `isLoggedIn` computed property becomes `true`. Now we can use `user` object to access customer data.

```vue{2,6}
<template>
  <div v-if="!isLoggedIn">
    <!-- DISPLAY FORM HERE -->
  </div>
  <div v-else>
    <h1>Hi, {{ user.firstName }}!</h1>
    <button @click="logout()">sign out</button>
  </div>
</template>
```

The example above shows the conditional visibility of content depending on the customer's logged in state.

## Handle authentication errors

To finish, we would like to inform the user about problems that may appear during the authentication.

In order to achieve it, the `errors` computed ref can be used:

```vue{5}
<template>
    <div v-if="!isLoggedIn">
        <div v-if="errors.login.length">
            {{ errors.login[0].detail }}
        </div>
    </div>
</template>
```

The example explains how to display only the first error that may appear in the response while processing the `login` method (see, the `errors` computed has prefixed `login` nested object).

## Full example

```vue
<script setup lang="ts">
const { logout, login, errors, isLoggedIn, user } = useUser();
const loginCredentials = reactive({
  username: "",
  password: "",
});
const invokeLogin = () => login(loginCredentials);
</script>
<template>
  <div v-if="!isLoggedIn">
    <h1>Sign in to your account</h1>
    <input type="text" v-model="loginCredentials.username" />
    <input type="password" v-model="loginCredentials.password" />
    <button @click="invokeLogin">sign in</button>
    <div v-if="errors.login.length">
      {{ errors.login[0].detail }}
    </div>
  </div>
  <div v-else>
    <h1>Hi, {{ user.firstName }}!</h1>
    <button @click="logout()">sign out</button>
  </div>
</template>
<style scoped>
.errors {
  color: red;
  margin-top: 10px;
}
</style>
```

---

---
url: /frontends/guides/page-elements/navigation.md
---

# Create a navigation

In this chapter you will learn how to

* Fetch the navigation of a store
* Display navigation items

## Fetch the navigation

We can retrieve the navigation of a store using the `useNavigation` composable hook.

```js
const { loadNavigationElements, navigationElements } = useNavigation();
```

The `navigationElements` property is a reactive reference to the navigation items which is updated as we fetch the navigation elements:

```js
await loadNavigationElements({ depth: 2 });
```

## Build a navigation template

Now all values can be accessed in the template to build a navigation menu

Note that all the navigation items are in type `Category`, and thanks to this the `getCategoryUrl` helper can be used to extract the correct pretty URL or technical URL as a fallback.

```vue
<script setup lang="ts">
import { getCategoryUrl } from "@shopware/helpers";
const { loadNavigationElements, navigationElements } = useNavigation();
await loadNavigationElements({ depth: 2 });
</script>

<template>
  <ul>
    <li
      v-for="navigationElement in navigationElements"
      :key="navigationElement.id"
    >
      <RouterLink
        :to="getCategoryRoute(navigationElement)"
        :target="
          navigationElement.externalLink || navigationElement.linkNewTab
            ? '_blank'
            : ''
        "
      >
        {{ navigationElement.translated.name }}
      </RouterLink>
    </li>
  </ul>
</template>
```

There is an additional attribute `target` used, in order to open a link in another window (external links or configured as `new tab` link).

## Full example: simple top navigation

::: tip 🙋‍♀️ How to use this example?
Copy the snippet and paste it into your project. It's often useful to extract it into its own component and use it in a higher-level component like a page or layout.
:::

```vue
<script setup lang="ts">
const { loadNavigationElements, navigationElements } = useNavigation();
await loadNavigationElements({ depth: 2 });

const { path: currentPath } = useRoute();

const isActive = (path: string) => {
  return "/" + path === currentPath;
};
</script>

<template>
  <div class="w-full shadow-lg mb-10 bg-white fixed">
    <nav
      class="w-full flex flex-col divide-gray-200 divide-y md:flex-row md:max-w-screen-xl md:mx-auto md:divide-y-0 md:divide-x"
    >
      <RouterLink
        v-for="navigationElement in navigationElements"
        :key="navigationElement.id"
        :to="'/' + navigationElement.seoUrls[0]?.seoPathInfo"
      >
        <div
          class="flex p-4 h-full border-l-5 hover:border-gray-200 md:border-l-none md:border-b-5 md:w-60 transition duration-200 items-center"
          :class="[
            isActive(navigationElement.seoUrls[0]?.seoPathInfo)
              ? 'border-indigo-500'
              : 'border-white',
          ]"
        >
          {{ navigationElement.translated.name }}
        </div>
      </RouterLink>
    </nav>
  </div>
</template>
```

## Next steps

---

---
url: /docs/guides/development/integrations-api/flows/create-product.md
---

# Create a Product and Complete Checkout

This guide shows a tested local end-to-end flow for Shopware development:

1. Create a category and product with the Admin API
2. Read the product with the Store API
3. Add the product to a cart
4. Register a customer in the current Store API context
5. Place an order
6. Handle payment if needed

It is written as a golden path for local development on `http://127.0.0.1:8000`. Troubleshooting tips appear below.

## What to expect in local development

A few details matter a lot in local setups:

* Store API requests use `sw-access-key`, not `sw-access-token`
* On this setup, `/store-api/context` is called with `GET`
* Store API context tokens are ephemeral and may expire during longer debugging sessions
* `register` or `login` may return a new `Sw-Context-Token`
* If the context changes, your cart may no longer contain the items you added earlier
* Product creation requires a price in the **system default currency**
* Customer registration requires real IDs such as `salutationId` and `countryId`

Because of that, the safest approach is to follow one known good sequence from start to finish.

## Before you start

Make sure your local Shopware instance is running:

* Storefront: `http://127.0.0.1:8000`
* Administration: `http://127.0.0.1:8000/admin`

You also need:

* `curl`
* `jq`
* An admin user, for example `admin / shopware` in a local default setup
* A Store API sales channel access key

## Step 1: Get an Admin API token

For local development, you can use the Administration password grant shortcut:

```bash
ADMIN_TOKEN=$(curl -s -X POST "http://127.0.0.1:8000/api/oauth/token" \
 -H "Content-Type: application/json" \
  -d '{
 "grant_type": "password",
 "client_id": "administration",
 "scopes": "write",
 "username": "admin",
 "password": "shopware"
 }' | jq -r '.access_token')

printf '%s\n' "$ADMIN_TOKEN"
```

## Step 2: Inspect your local API schemas

Use the generated schemas for two different questions:

* **OpenAPI spec**: Which endpoint should I call, and what does the payload look like?
* **Entity schema**: Which fields and associations exist on product, category, order, and other entities?

Download the Admin API schemas:

```bash
curl -s "http://127.0.0.1:8000/api/_info/openapi3.json" \
 -H "Authorization: Bearer $ADMIN_TOKEN" \
  -o openapi.json
```

Download the entity schema as well:

```bash
curl -s "http://127.0.0.1:8000/api/_info/open-api-schema.json" \
 -H "Authorization: Bearer $ADMIN_TOKEN" \
  -o entity-schema.json
```

Quick checks:

```bash
ls -lh openapi.json entity-schema.json
head -n 5 openapi.json
head -n 5 entity-schema.json
```

You can do the same for the Store API later with `/store-api/_info/openapi3.json`.

## Step 3: Look up the IDs you need before creating products

A product usually needs related IDs, such as:

* `taxId`
* `salesChannelId`
* `currencyId`

Use Admin API search endpoints for this.

### Find a tax ID

```bash
curl -s -X POST "http://127.0.0.1:8000/api/search/tax" \
 -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
 -d '{
    "limit": 10,
    "sort": [{ "field": "name", "order": "ASC" }]
 }' | jq
```

Choose the tax rate you want to use — for example, the standard rate.

### Find a sales channel ID and Store API access key

```bash
curl -s -X POST "http://127.0.0.1:8000/api/search/sales-channel" \
 -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
 -d '{
    "limit": 10,
    "includes": {
      "sales_channel": ["id", "name", "accessKey"]
 }
 }' | jq
```

Pick the sales channel you want to test against — for example, `Storefront`.

### Find a currency ID

Use the system default currency, because product writes require a price in the default currency:

```bash
curl -s -X POST "http://127.0.0.1:8000/api/search/currency" \
 -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
 -d '{
    "limit": 10,
    "includes": {
      "currency": ["id", "name", "isoCode", "isSystemDefault"]
 }
 }' | jq
```

### Save the IDs you want to use

```bash
TAX_ID="<example string>"
SALES_CHANNEL_ID="<example string>"
CURRENCY_ID="<example string>"
STORE_API_ACCESS_KEY="<example string>"
```

## Step 4: Create a category with the Admin API

```bash
CATEGORY_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | tr -d '-')

curl -s -X POST "http://127.0.0.1:8000/api/category" \
 -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
 -d "{
    \"id\": \"$CATEGORY_ID\",
    \"name\": \"My Example Category\",
    \"active\": true
 }"
```

Verify it:

```bash
curl -s -X POST "http://127.0.0.1:8000/api/search/category" \
 -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
 -d "{
    \"ids\": [\"$CATEGORY_ID\"],
    \"includes\": {
      \"category\": [\"id\", \"name\", \"active\"]
 }
 }" | jq
```

The `ids` and `includes` criteria are standard search-criteria features.

## Step 5: Create a product with the Admin API

```bash
PRODUCT_ID=$(uuidgen | tr '[:upper:]' '[:lower:]' | tr -d '-')
PRODUCT_NUMBER="MyExample-001"

curl -s -X POST "http://127.0.0.1:8000/api/product" \
 -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
 -d "{
    \"id\": \"$PRODUCT_ID\",
    \"name\": \"My Example Product\",
    \"productNumber\": \"$PRODUCT_NUMBER\",
    \"stock\": 10,
    \"active\": true,
    \"taxId\": \"$TAX_ID\",
    \"price\": [
 {
        \"currencyId\": \"$CURRENCY_ID\",
        \"gross\": 19.99,
        \"net\": 16.80,
        \"linked\": true
 }
 ],
    \"visibilities\": [
 {
        \"salesChannelId\": \"$SALES_CHANNEL_ID\",
        \"visibility\": 30
 }
 ],
    \"categories\": [
 { \"id\": \"$CATEGORY_ID\" }
 ]
 }"
```

### About `visibilities`

Use `visibilities` to assign a product to one or more sales channels and define how visible it should be in each channel.

Each visibility entry contains:

```bash
{
  "salesChannelId": "<sales-channel-id>",
  "visibility": 30
}
```

`visibility` is required because product availability is resolved per sales channel. A product is only considered available in a sales-channel context when it has a matching visibility entry for that `salesChannelId`.

Allowed values:

* `10` (`VISIBILITY_LINK`): hide in listings and search
* `20` (`VISIBILITY_SEARCH`): hide in listings
* `30` (`VISIBILITY_ALL`): visible everywhere

Verify it:

```bash
curl -s -X POST "http://127.0.0.1:8000/api/search/product" \
 -H "Authorization: Bearer $ADMIN_TOKEN" \
  -H "Content-Type: application/json" \
 -H "sw-inheritance: 1" \
  -d "{
    \"ids\": [\"$PRODUCT_ID\"],
    \"associations\": {
      \"categories\": {}
 },
    \"includes\": {
      \"product\": [\"id\", \"name\", \"productNumber\", \"active\", \"translated\", \"categories\"],
      \"category\": [\"id\", \"name\"]
 }
 }" | jq
```

The `sw-inheritance` header tells the API to consider parent-child inheritance when reading products and variants.

## Step 6: Create a Store API context

The Store API uses two important headers:

* `sw-access-key`: authenticates against the Store API sales channel
* `sw-context-token`: identifies the shopper context

Get a fresh Store API context:

```bash
curl -i "http://127.0.0.1:8000/store-api/context" \
 -H "sw-access-key: $STORE_API_ACCESS_KEY"
```

Look for the `Sw-Context-Token` response header and store its value:

```bash
STORE_CONTEXT_TOKEN="REPLACE_ME"
echo "$STORE_CONTEXT_TOKEN"
```

You can also extract it automatically:

```bash
STORE_CONTEXT_TOKEN=$(curl -si "http://127.0.0.1:8000/store-api/context" \
 -H "sw-access-key: $STORE_API_ACCESS_KEY" \
  | tr -d '\r' | awk -F': ' 'tolower($1)=="sw-context-token" {print $2}')

echo "$STORE_CONTEXT_TOKEN"
```

## Step 7: Read the product with the Store API

Use a Store API search request with search criteria. The following example searches by term and sorts by name:

```bash
curl -s -X POST "http://127.0.0.1:8000/store-api/search" \
 -H "sw-access-key: $STORE_API_ACCESS_KEY" \
  -H "sw-context-token: $STORE_CONTEXT_TOKEN" \
 -H "Content-Type: application/json" \
  -d '{
 "term": "My Example Product",
 "limit": 5,
 "sort": [
 { "field": "name", "order": "ASC", "naturalSorting": true }
 ],
 "includes": {
 "product": ["id", "name", "translated", "calculatedPrice"]
 }
 }' | jq
```

The following example shows how to find the product you created in a storefront-style listing:

```bash
curl -s -X POST "http://127.0.0.1:8000/store-api/search" \
 -H "sw-access-key: $STORE_API_ACCESS_KEY" \
  -H "sw-context-token: $STORE_CONTEXT_TOKEN" \
 -H "Content-Type: application/json" \
  -d "{
    \"filter\": [
 { \"type\": \"equals\", \"field\": \"active\", \"value\": true },
 { \"type\": \"equals\", \"field\": \"productNumber\", \"value\": \"$PRODUCT_NUMBER\" }
 ],
    \"sort\": [
 { \"field\": \"name\", \"order\": \"ASC\" }
 ],
    \"page\": 1,
    \"limit\": 10,
    \"includes\": {
      \"product\": [\"id\", \"name\", \"productNumber\", \"translated\", \"calculatedPrice\"]
 }
 }" | jq
```

Useful search-criteria options:

* `includes` restricts the response to the fields you need
* `page` and `limit` control pagination
* `filter` applies exact or nested filtering
* `term` performs a weighted text search
* `sort` controls ordering

If your project uses a different Store API search/listing endpoint, confirm the exact path in your local `store-api/_info/openapi3.json`.

## Step 8: Add the product to the cart

Use the product ID from the previous step:

```bash
curl -s -X POST "http://127.0.0.1:8000/store-api/checkout/cart/line-item" \
 -H "sw-access-key: $STORE_API_ACCESS_KEY" \
  -H "sw-context-token: $STORE_CONTEXT_TOKEN" \
 -H "Content-Type: application/json" \
  -d "{
    \"items\": [
 {
        \"id\": \"$PRODUCT_ID\",
        \"referencedId\": \"$PRODUCT_ID\",
        \"type\": \"product\",
        \"quantity\": 1
 }
 ]
 }" | jq
```

Verify the cart:

```bash
curl -s -X GET "http://127.0.0.1:8000/store-api/checkout/cart" \
 -H "sw-access-key: $STORE_API_ACCESS_KEY" \
  -H "sw-context-token: $STORE_CONTEXT_TOKEN" | jq
```

If your local schema shows slightly different cart payload requirements, trust your local `store-api` OpenAPI spec.

## Step 9: Prepare checkout state

Before placing an order, you typically need:

* a customer in the current Store API context
* active billing and shipping addresses
* a shipping method
* a payment method

You can inspect your local Store API reference in the browser at `http://127.0.0.1:8000/store-api/_info/stoplightio.html`, or inspect the raw schema:

```bash
curl -s "http://127.0.0.1:8000/store-api/_info/openapi3.json" -o store-openapi.json
jq -r '.paths | keys[]' store-openapi.json | grep -E 'checkout|account|address|payment|shipping|order|context'
```

Typical relevant endpoints include:

* `/account/register`
* `/account/login`
* `/account/address`
* `/context`
* `/payment-method`
* `/shipping-method`
* `/checkout/cart`
* `/checkout/order`
* `/handle-payment`

Rule of thumb:

* Admin API: create and manage data
* Store API: act like a shopper

## Step 10: Register or log in as a customer, then place the order

On a typical local setup, `POST /store-api/checkout/order` requires a logged-in customer. If you call it with an anonymous context, Shopware returns `Customer is not logged in.` First, register a customer or log in within the current Store API context.

### 10.1 Fetch salutationId and countryId

For registration, fetch real IDs for:

* `salutationId` from `/store-api/salutation`
* `countryId` from `/store-api/country`

For example:

```bash
COUNTRY_ID="019d2b446e29724fa4715c70c9c3eae1"
SALUTATION_ID="019d2b446e2573ba9a3ea2d002050cbe"
```

### 10.2 Register the customer

```bash
curl -i -X POST "http://127.0.0.1:8000/store-api/account/register" \
 -H "sw-access-key: $STORE_API_ACCESS_KEY" \
  -H "sw-context-token: $STORE_CONTEXT_TOKEN" \
 -H "Content-Type: application/json" \
  -d "{
    \"salutationId\": \"$SALUTATION_ID\",
    \"firstName\": \"FirstName\",
    \"lastName\": \"LastName\",
    \"email\": \"name-test@example.com\",
    \"password\": \"shopware123!\",
    \"acceptedDataProtection\": true,
    \"storefrontUrl\": \"http://127.0.0.1:8000\",
    \"billingAddress\": {
      \"firstName\": \"FirstName\",
      \"lastName\": \"LastName\",
      \"street\": \"Teststr. 1\",
      \"zipcode\": \"12345\",
      \"city\": \"Test City\",
      \"countryId\": \"$COUNTRY_ID\"
 }
 }"
```

Use the `Sw-Context-Token` value from the response for subsequent requests:

```bash
STORE_CONTEXT_TOKEN="REPLACE_ME_WITH_NEW_TOKEN"
```

### 10.3 Re-add the product if the context token changed

After `/store-api/account/register` or `/store-api/account/login`, Shopware may return a new `Sw-Context-Token`. If the token changes, add the product to the cart again in that new context before calling `/store-api/checkout/order`.

```bash
curl -s -X POST "http://127.0.0.1:8000/store-api/checkout/cart/line-item" \
 -H "sw-access-key: $STORE_API_ACCESS_KEY" \
  -H "sw-context-token: $STORE_CONTEXT_TOKEN" \
 -H "Content-Type: application/json" \
  -d "{
    \"items\": [
 {
        \"id\": \"$PRODUCT_ID\",
        \"referencedId\": \"$PRODUCT_ID\",
        \"type\": \"product\",
        \"quantity\": 1
 }
 ]
 }" | jq
```

Verify that the cart is not empty:

```bash
curl -s "http://127.0.0.1:8000/store-api/checkout/cart" \
 -H "sw-access-key: $STORE_API_ACCESS_KEY" \
  -H "sw-context-token: $STORE_CONTEXT_TOKEN" | jq
```

### 10.4 Place the order

Once the Store API context has:

* A logged-in customer
* A cart with your product
* Valid billing and shipping data

You can usually place the order directly on a local default setup. If your instance requires an explicit payment or shipping selection first, inspect `/payment-method`, `/shipping-method`, and `/context`.

Create the order:

```bash
curl -s -X POST "http://127.0.0.1:8000/store-api/checkout/order" \
 -H "sw-access-key: $STORE_API_ACCESS_KEY" \
  -H "sw-context-token: $STORE_CONTEXT_TOKEN" \
 -H "Content-Type: application/json" \
  -d '{
 "customerComment": "Test order from local API walkthrough"
 }' | jq
```

If the cart is empty, Shopware returns the message: `Cart is empty.`

In that case, add the product to the cart again in the current context, then retry the order request.

### 10.5 Handle payment if required

Some payment methods require an extra payment step after order creation:

```bash
curl -s -X POST "http://127.0.0.1:8000/store-api/handle-payment" \
 -H "sw-access-key: $STORE_API_ACCESS_KEY" \
  -H "sw-context-token: $STORE_CONTEXT_TOKEN" \
 -H "Content-Type: application/json" \
  -d '{
 "orderId": "REPLACE_ME",
 "finishUrl": "http://127.0.0.1:8000/checkout/finish",
 "errorUrl": "http://127.0.0.1:8000/checkout/confirm"
 }' | jq
```

If `/store-api/handle-payment` returns `"redirectUrl": null`, the selected payment method does not require an additional redirect-based flow.

## Troubleshooting

### Schema endpoints return `500` or missing-table errors

Your database may not be initialized correctly. Re-run installation and setup.

### Product does not show up in the Store API

Check all of the following:

* The product is `active`
* The product has a valid `price`
* The product has `visibilities` for your sales channel
* You are using the correct Store API access key
* Your Storefront sales channel domain matches your local URL

### Which headers matter most?

For this walkthrough:

* Admin API: `Authorization: Bearer $ADMIN_TOKEN`, optionally `sw-language-id`, `sw-version-id`, `sw-inheritance`, `sw-currency-id` depending on your use case
* Store API: `sw-access-key`, `sw-context-token`

---

---
url: /frontends/guides/e-commerce/product-listing.md
---

# Create a product listing

In this chapter you will learn how to

* Initialize the `useListing` composable
* Search for products
* Display products in a listing
* Implement a pagination
* Apply sortings, pagination, and filters
* Use the `helpers` package
* Configure variants presentation for store API

## Listing context

Product listing is a structure related to the predefined areas and it has always the same interface: `ProductListingResult`:

* Response of product-listing endpoint `/store-api/product-listing/{id}`
* Product search result
* Cms Page (via `product-listing` element, nested among other CMS element)

## Listing type and context

Before using the composable, define the type related to the context:

* `categoryListing` for navigation/category/cms pages
* `productSearchListing` for search page

```ts{3}
const { search, getElements } = useListing({
  listingType: "categoryListing",
  categoryId: "dfd52ab937f840fd87e9d24ebf6bd245",
});
```

The `categoryId` is obligatory only if the current page is not a result of using `useCms` composable (generated from Shopping Experiences).

:::info
If the `useListing` composable is used within a CMS Page, `categoryId` is resolved internally.
:::

## Define search criteria

In order to get the expected products, we need to define the search criteria. This criteria is an object of type Search Parameters explained in [documentation of API](https://shopware.stoplight.io/docs/store-api/cf710bf73d0cd-search-queries).

```ts
const { search } = useListing();

search({
  limit: 2, // get only 2 products
  p: 1, // page 1
  includes: {
    // things we actually need in the response for learning purposes
    product: ["id", "name", "cover", "calculatedPrice"],
    product_media: ["media"],
    media: ["url"],
  },
});
```

:::tip
Don't use [`includes`](https://shopware.stoplight.io/docs/store-api/cf710bf73d0cd-search-queries#includes-apialias) parameter if you want to have the whole entity object available in the response.
:::

## Display listing elements

In order to display products of product listing we need to:

* Invoke the `search()` method with a positive result
* Iterate over `getElements` array of elements, where each element has the `Product` type.

```vue{11,22}
<script setup lang="ts">
const { search, getElements } = useListing({
    listingType: "categoryListing",
    categoryId: "dfd52ab937f840fd87e9d24ebf6bd245", // entrypoint to browse
    defaultSearchCriteria: { // set the default criteria
        limit: 3,
        p: 1,
    },
});

search({ // invoke search() method
  includes: { // omit this parameter if you want to use the whole product entity
    product: ["id", "name", "cover", "calculatedPrice", "translated"],
    product_media: ["media"],
    media: ["url", "thumbnails"],
  },
});
</script>
<template>
 <div>
    <!-- iterate the getElements array -->
    <div v-for="product in getElements" :key="product.id">
        {{ product.name }}
        <!-- use other properties of type Product -->
    </div>
 </div>
</template>
```

## Sorting

Available methods of `useListing` to manage sorting order:

* `getSortingOrders()` - returns all available sorting options
* `getCurrentSortingOrder()` - returns the current order, available in the response
* `changeCurrentSortingOrder()` - sets the new order, invoking a `search` method internally

```ts{3-5}
// part of <script setup> section
const {
  getCurrentSortingOrder,
  getSortingOrders,
  changeCurrentSortingOrder,
} = useListing({
  listingType: "categoryListing",
  categoryId: "dfd52ab937f840fd87e9d24ebf6bd245",
  defaultSearchCriteria: {
    limit: 3,
    p: 1,
  },
});
```

Show all available sortings:

```html
<!-- part of <template> -->
<select>
  <option
    v-for="sortingOrder in getSortingOrders"
    :key="sortingOrder.key"
    :value="sortingOrder.key"
    :selected="sortingOrder.key === getCurrentSortingOrder"
  >
    {{ sortingOrder.label }}
  </option>
</select>
```

Refresh the product listing on option's change:

```ts{4-6}
const onOrderChange = (onOrderChangeEvent: Event) => {
    // accept the DOM Event and extract the option's value
    // pass the value to the listing method that triggers the search() method internally
    changeCurrentSortingOrder(
        (onOrderChangeEvent.target as HTMLSelectElement).value
    );
};
```

Add event listener to the `<select>` element:

```html
<select @change="onOrderChange"></select>
```

## Enable adding to the cart

To achieve this, you can use `useCart` composable which expose `addProduct` method, including other useful functions to manage a cart.

```ts
// part of <script setup> section
const { addProduct } = useCart();
```

Utilize the method in a template:

```html
<!-- part of <template> -->
<div>price: {{ product?.calculatedPrice?.unitPrice }} $</div>
<button @click="addProduct(product)">Add to cart</button>
```

Now, when the customer clicks the `Add to cart` button, a proper request is sent to the API. The cart is then refreshed and is up to date in the entire application.

:::tip
Alternative tip - Instead of using `useCart`, you can use `useAddToCart` composable when you create a separate Vue component to keep a single `Product` for product listing. That option would enhance the code organization.
:::

## Add pagination

Pagination is available by using three methods from `useListing` composable:

* `getCurrentPage`
* `changeCurrentPage` - invokes `search()` method internally with the provided number of the page
* `getTotalPagesCount` - calculates the number of available pages depending on products per page parameters (i.e. `limit` in search criteria)

```ts{5-7}
// part of <script setup> section
const {
    search,
    getElements,
    getCurrentPage,
    changeCurrentPage,
    getTotalPagesCount,
    getAvailableFilters
} = useListing({
    listingType: "categoryListing",
    categoryId: "dfd52ab937f840fd87e9d24ebf6bd245",
    defaultSearchCriteria: {
        limit: 3,
        p: 1,
    },
})
```

The implementation can look similar to:

```html
<!-- part of <template> -->
<div>
  <div>Pages: {{ getTotalPagesCount }}</div>
  <button
    v-if="getCurrentPage > 1"
    @click="changeCurrentPage(getCurrentPage - 1)"
  >
    prev
  </button>
  <span> {{ getCurrentPage }} </span>
  <button
    v-if="getCurrentPage < getTotalPagesCount"
    @click="changeCurrentPage(getCurrentPage + 1)"
  >
    next
  </button>
</div>
```

## Using Filters

:::info Available Filters
For more information about filters available in the Store API scope, see [Search Queries > Filter](https://shopware.stoplight.io/docs/store-api/cf710bf73d0cd-search-queries#filter)
:::

Available filters are strictly related to the aggregation's object available in the API response.

Built-in aggregations:

* manufacturer
* price
* rating
* shipping-free
* properties (contain all property entities configured in the admin panel)

### Get list of all available filters

[comment]: # "mermaid source: https://gist.github.com/mkucmus/4002882a229c2a9eb60fe83b84483b2b"

The diagram explains the source of available filters. The API response contains aggregations that are parsed into one interface structure.

In order to get the list of available filters, use the following command:

```ts
const { getAvailableFilters } = useListing(/** parameters omitted */);
```

You can then iterate the filter objects available in the array. The filter object has a [ListingFilter](https://github.com/shopware/frontends/blob/main/packages/types/shopware-6-client/response/ListingResult.d.ts#L19) interface and depending on the `code`, or `displayType`, the handling process can be different. Let us have a closer look at it:

`ListingFilter.code`: **manufacturer**

```vue{15,17}
<script setup lang="ts">
const { getAvailableFilters, getCurrentFilters, setCurrentFilters } = useListing(/** parameters omitted */)

const selectManufacturerAndSearch = (manufacturerId: string) => {
  setCurrentFilters({
    code: "manufacturer",
    value: manufacturerId
  })
}

// element from getAvailableFilters.value
// i.e: getAvailableFilters.value?.find(({code}) => code === "manufacturer")?.[0]
const manufacturerFilter = {
  apiAlias:"manufacturer_aggregation",
  code:"manufacturer",
  label:"manufacturer",
  entities: [
      {
        "extensions": {
          "foreignKeys": {
            "apiAlias": "array_struct"
          }
        },
        "_uniqueIdentifier": "1d39db66fd184de8bdcfbf995197f8ea",
        "versionId": "0fa91ce3e96a4bc2be4bd9ce752c3425",
        "translated": {
          "name": "Boomers Gourmet",
          "description": "Description",
          "customFields": {}
        },
        "createdAt": "2020-08-06T06:26:30.608+00:00",
        "updatedAt": null,
        "mediaId": "ef102a5043174d8b936623b175c8af57",
        "name": "Boomers Gourmet",
        "link": "http://www.gewuerze-boomers.de/",
        "description": "Description",
        "media": null,
        "translations": null,
        "id": "1d39db66fd184de8bdcfbf995197f8ea",
        "customFields": null,
        "apiAlias": "product_manufacturer"
      },]
    { // other manufacturer objects
    }
  ]
}
</script>
<template>
<h3>{{ manufacturerFilter.label }}</h3>
  <div v-for="manufacturer in manufacturerFilter?.entities">
    <input
        type="checkbox"
        :id="`filter-mobile-${manufacturerFilter.code}-${manufacturer.id}`"
        :key="manufacturer.id"
        :name="manufacturerFilter.code"
        @click="selectManufacturerAndSearch(manufacturer.id)"
        :checked="getCurrentFilters['manufacturer']?.includes(manufacturer.id)"
      />
      <label :for="`filter-mobile-${manufacturerFilter.code}-${manufacturer.id}`">
        {{ manufacturer.name }}
      </label>
  </div>

</template>
```

* All available options for the Manufacturer filter are displayed in `v-for` loop. See `entities` property for the same.
* If the `manufacturer.id` is present in `getCurrentFilters['manufacturer']` array, set the option as checked.
* On the `click` event, invoke `setCurrentFilters({code, value})` method with code (`manufacturer`) and value (specific manufacturer ID) provided.

***

`ListingFilter.code`: **properties**

[Properties](https://docs.shopware.com/en/shopware-6-en/products/properties?category=shopware-6-en/catalogues) is a generic type of filter responsible for displaying property entities that can describe a product that is configured on the backend side.

Despite being in the same filter group, every entity of property defined in the admin panel is available separately.

```ts
const ColorFilter: ListingFiler = {
  name: "Color",
  // other properties omitted
  options: [
    {
      id: "yellow-id",
      name: "Yellow",
      // other props omitted
    },
    {
      id: "green-id",
      name: "Gellow",
      // other props omitted
    },
  ],
};
```

### Apply filter value

In order to apply a specific filter you need to be aware of:

* Filter code (see available codes at [ListingFilterCode](https://github.com/shopware/frontends/blob/main/packages/types/shopware-6-client/response/ListingResult.d.ts#L7))
* Value

```vue
<script setup lang="ts">
const { setCurrentFilters } = useListing(/** parameters omitted */);

setCurrentFilters({
  code: "properties",
  value: "some-property-id",
});

// or

setCurrentFilters({
  code: "rating",
  value: 5, // 5 stars rated products
});
</script>
```

### Get list of applied (active) filters or its options

```vue
<script setup lang="ts">
const { getCurrentFilters } = useListing(/** parameters omitted */);
</script>
<template>
  {{ getCurrentFilters.navigationId }}
  <!-- "category-A-ID-1" -->
  {{ getCurrentFilters.manufacturer }}
  <!-- ["manufacturer-A-option-ID-1"] -->
  {{ getCurrentFilters.price }}
  <!-- { min: 0, max: 299 } -->
  {{ getCurrentFilters.rating }}
  <!-- null -->
  {{ getCurrentFilters.["shipping-free"] }}
  <!-- false -->
  {{ getCurrentFilters.properties }}
  <!-- ["property-A-option-ID-1", "property-A-option-ID-2", "property-B-option-ID-1"]-->
</template>
```

You can achieve that by comparing stored value with displayed one.

| Filter        | Where to find?                       | Data structure                 |
| ------------- | ------------------------------------ | ------------------------------ |
| Manufacturer  | `getCurrentFilters.manufacturer`     | `array[id: string]`            |
| Price         | `getCurrentFilters.price`            | `{ min: number, max: number }` |
| Rating        | `getCurrentFilters.rating`           | `number`                       |
| Shipping free | `getCurrentFilters["shipping-free"]` | `boolean`                      |
| Properties    | `getCurrentFilters.properties`       | `array[id: string]`            |

The selected/active filters for its options/values are flattened and limited only to the bare values.

:::info
Active filters for `Properties` contain only the list of ID's of properties' option. Therefore, they don't have any meta-info explaining what is the source of the option.
:::

## Helpers package

The purpose of `@shopware/helpers` is to make developer's life easier.

In the present case, we could use the product's thumbnail or use the translated name, or even get the product details page's URL, if the application supports a routing.

```ts
// part of <script setup> section
import {
  getSmallestThumbnailUrl,
  getProductUrl,
  getTranslatedProperty,
} from "@shopware/helpers";
```

```html
<img
  :src="getSmallestThumbnailUrl(product)"
  width="100"
  height="100"
  :alt="product.name"
/>
<a :href="getProductUrl(product)">
  {{ getTranslatedProperty(product, "name") }}
</a>
```

## Variants presentation

You have three different options for presenting your variants to your audience. These can be configured via the administration, for every product with variants. In this section, we explain how the output of the store API changes depending on the configuration. The default option is `Expand property values in product listings` without any property selection, this leads to a randomly selected variant.

**To open the Product listing configuration for the Storefront presentation (also changes the output of the store API), proceed as follows in your administration:**

Hover over `Cataloges` > Click on `Products` > Use the Search or Pagination to find your Product > Click on the Product with Variants you want to change > Click on the Tab `Variants` > Click on the Button `Storefront presentation` > A new window/modals opens > Click on `Product lists` on the left side > Here you can change the configuration of how the product with variants should be presented.

:::info Additional ressources
More about Variants can be found in the [Customer documentation](https://docs.shopware.com/en/shopware-6-en/catalogues/products#variants). If you want to customise a product, please also check [Custom products](https://docs.shopware.com/en/shopware-6-en/extensions/customproducts) and do not use variants.
:::

### Display single product (main product)

Configuration is set to `Display single product` and `Main product` is selected.


Changes you will see in the **store API output** with that configuration:

* The store API returns `one element`
* The data comes from the `Parent (main) product`, e.g. stock, sales, product number and so on.
* If the association `children` is set, all the variant product data is returned in the `children` array
  * The `childCount` should be greater than zero, it should contain the number of all possible variants
* `parentId` and `optionsIds` will always be null

:::warning Too many children & big json files
It is good practice to return only the necessary data in your custom frontend. This means selecting only the required children and monitoring the JSON file size. Large files can slow down performance as they need to be downloaded and parsed.
:::

### Display single product (Variant)

Configuration is set to `Display single product` and a `Variant product` is selected.


Changes you will see in the **store API output** with that configuration:

* The store API returns `one element`
* The data comes from the selected `Product variant`, e.g. stock, sales, product number and so on.
* If you add the association `children`, an empty array is always returned, as a variant cannot be a parent product
* The `childCount` should be zero, as a variant cannot be a parent product
* `parentId` will contain the id of the parent product and `optionsIds` will contain the options from that variant product

:::info Use case example
You always want to display the cheapest product on the product list as preselected. So that the customer can add it to the shopping cart more quickly.
:::

### Expand property values in product listings

Changes you will see in the **store API output** with that configuration:

* The store API returns `multiple elements` for each selected property, but not the parent product
* Data will be collected from the matching Variant products e.g. stock, sales, productNumber and so on.
* If you add the association `children`, an empty array is always returned, as a variant cannot be a parent product
* The `childCount` should be zero, as a variant cannot be a parent product
* `parentId` will contain the id of the parent product and `optionsIds` will contain the options from that matching variant product

:::info Use case example
You could expand a property like `color` to display all the different images of a T-shirt directly in the product listing. The size selection can still be made on the product detail page so as not to overload the product list.
:::

## Full example: condensed product listing UI

::: tip 🙋‍♀️ How to use this example?
Copy the snippet and paste it into your project. It's often useful to extract it into its own component and use it in a higher-level component like a page or layout.
:::

This listing shows the product name and price with soft hover effects and a fade-in animation.

```vue
<script setup lang="ts">
import { useProductSearchSuggest } from "@shopware/composables";
import { getTranslatedProperty } from "@shopware/helpers";

const { search, searchTerm, getTotal, getProducts } = useProductSearchSuggest();

onMounted(() => {
  // Replace that with your custom logic to fetch products
  searchTerm.value = "sal";
  search();
});

const addProductAndRefresh = async ({ id }) => {
  await addProduct({ id });
  refreshCart();
};

const { addProduct, refreshCart } = useCart();
</script>

<template>
  <div
    class="grid grid-cols-2 md:grid-cols-4 gap-3 max-w-screen-xl mx-auto p-3 transition-opacity pt-32"
    :class="[getTotal > 0 ? 'opacity-100' : 'opacity-0']"
  >
    <div v-for="product in getProducts" :key="product.id" class="h-96 group">
      <div class="h-48">
        <div
          class="h-full w-full object-cover bg-white cursor-pointer overflow-hidden"
        >
          <img
            :src="product.cover.media.url"
            class="w-full h-full object-cover group-hover:scale-110 transition-all duration-300"
          />
        </div>
        <div class="h-36 py-5 font-light flex flex-col justify-between">
          <h3
            class="text-xl line-clamp-1 mb-2 group-hover:text-gray-800"
            @click="addProduct({ id: product.id })"
          >
            {{ getTranslatedProperty(product, "name") }}
          </h3>
          <p class="text-gray-700 group-hover:text-gray-500">
            {{ product.calculatedPrice.totalPrice }} €
          </p>
        </div>
        <div
          class="bg-gray-300 p-2 h-12 flex items-center justify-center text-gray-800 cursor-pointer hover:bg-gray-400"
          @click="addProductAndRefresh({ id: product.id })"
        >
          Add to basket
        </div>
      </div>
    </div>
  </div>
</template>
```

---

---
url: /docs/guides/plugins/themes/create-a-theme.md
---

# Create a Theme

## Overview

This guide covers how to create, install, and activate a custom Shopware 6 theme.

## Prerequisites

All you need:

* A running Shopware 6 instance
* Full file system and CLI access

## Name your plugin theme

Use **UpperCamelCase**, e.g., `SwagBasicExampleTheme`, beginning with a capital letter and ideally with a company prefix to avoid duplication. Choose a name that describes your theme appearance as succinctly and clearly as possible.

### Create a plugin-based theme

Run the following command in your terminal:

```bash
bin/console theme:create SwagBasicExampleTheme
```

You should get an output like this:

```bash
Creating theme structure under .../development/custom/plugins/SwagBasicExampleTheme
```

Shopware needs to know that your new theme exists. Refresh the plugin list by running:

```bash
bin/console plugin:refresh
```

You should get an output like this:

```bash
[OK] Plugin list refreshed                                                                              

Shopware Plugin Service
=======================

 ----------------------- ------------------------------------ ------------- ----------------- -------- ----------- -------- ------------- 
  Plugin                  Label                                Version       Upgrade version   Author   Installed   Active   Upgradeable  
 ----------------------- ------------------------------------ ------------- ----------------- -------- ----------- -------- ------------- 
  SwagBasicExampleTheme   Theme SwagBasicExampleTheme plugin   9999999-dev                              No          No       No           
 ----------------------- ------------------------------------ ------------- ----------------- -------- ----------- -------- ------------- 

 1 plugins, 0 installed, 0 active , 0 upgradeable
```

### Activating the theme

The next command installs and activates the theme:

```bash
bin/console plugin:install --activate SwagBasicExampleTheme
```

The output should look like this, indicating success:

```bash
Shopware Plugin Lifecycle Service
=================================

 Install 1 plugin(s):
 * Theme SwagBasicExampleTheme plugin (vdev-trunk)

 Plugin "SwagBasicExampleTheme" has been installed and activated successfully.

 [OK] Installed 1 plugin(s).
```

### Assign to a sales channel

The final step in this guide involves assigning the theme to a sales channel and changing the default Storefront theme. Run this command:

```bash
# run this to change the current Storefront theme
$ bin/console theme:change
```

You should see an interactive prompt like this:

```bash
Please select a sales channel:
[0] Storefront | 64bbbe810d824c339a6c191779b2c205
[1] Headless | 98432def39fc4624b33213a56b8c944d
> 0

Please select a theme:
[0] Storefront
[1] SwagBasicExampleTheme
> 1

Set "SwagBasicExampleTheme" as new theme for sales channel "Storefront"
Compiling theme 13e0a4a46af547479b1347617926995b for sales channel SwagBasicExampleTheme
```

First, select `Storefront` as the sales channel. Then enter your theme's number. This fully installs your theme, and you can start your customization.

### Directory structure of a theme

The structure of a plugin-based theme:

```bash
├── composer.json
└── src
    ├── Resources
    │   ├── app
    │   │   └── storefront
    │   │       ├── dist
    │   │       │   └── storefront
    │   │       │       └── js
    |   |       |           └── swag-basic-example-theme  
    │   │       │               └── swag-basic-example-theme.js
    │   │       └── src
    │   │           ├── assets
    │   │           ├── main.js
    │   │           └── scss
    │   │               ├── base.scss
    │   │               └── overrides.scss
    │   └── theme.json
    └── SwagBasicExampleTheme.php
```

## Troubleshooting

When the theme is not visible, run the command:

```bash
bin/console plugin:refresh
bin/console plugin:list
```

When the theme is not applied, run the command:

```bash
bin/console theme:change
bin/console theme:compile
```

When there are errors no changes, run the command:

```bash
bin/console cache:clear
```

Also helpful:

* Check `var/log/`
* Verify file permissions in `custom/plugins/`

## Next steps

Now that you have created a theme, learn how to configure settings and styling:

* [Theme configuration](../themes/configuration/theme-configuration.md)
* [Add SCSS Styling and JavaScript to a theme](../themes/styling/add-css-js-to-theme.md)
* [Add assets to theme](../themes/assets/add-assets-to-theme.md)

---

---
url: /frontends/guides/features/wishlist.md
---

# Create a wishlist

In this chapter you will learn how to use the built-in wishlist API to create wishlist functionalities in your application. Specifically, you will learn how to

* Create a wishlist page
* Synchronize local and remote wishlist data
* Add products to and remove products from the wishlist

## Remote and local wishlists

In Shopware's Store API, only authenticated (logged-in) users can manage a custom wishlist.

The composables related to wishlists are built in a way that allows you to maintain a local (in-memory) wishlist for unauthenticated users and synchronize it with the server when the user logs in.

::: info
The `useWishlist` and `useProductWishlist` view helpers decide whether to use the local or the server wishlist based on the user's authentication status.
:::

| Composable           | Description                            |
| -------------------- | -------------------------------------- |
| `useLocalWishlist`   | manages the local (in-memory) wishlist |
| `useSyncWishlist`    | manages the remote (server) wishlist   |
| `useWishlist`        | view helper for the wishlist page      |
| `useProductWishlist` | view helper for a single product       |

## Get wishlist

You can use the `useWishlist` composable to get the wishlist products.

:::tip
`getWishlistProducts` method will detect if the customer is logged in or not
:::

```vue
<script>
import type { Schemas } from "#shopware";

// Contains a list of products ids in the wishlist
const { getWishlistProducts, items } = useWishlist();
const { apiClient } = useShopwareContext();

// Load products data
const loadProductsByItemIds = async (itemIds: string[]): Promise<void> => {
  isLoading.value = true;

  try {
    // Backend API call for product data
    const result = await apiClient.invoke("readProduct post /product", {
      body: {
        ids: itemIds || items.value,
      },
    });

    products.value = result.data.elements;
  } catch (error) {
    console.error(error);
  }
};

// Watch changes and update product data
watch(
  items,
  (items, oldItems) => {
    if (items.length !== oldItems?.length) {
      products.value = products.value.filter(({ id }) => items.includes(id));
    }
    if (!items.length) {
      return;
    }
    loadProductsByItemIds(items);
  },
  {
    immediate: true,
  }
);

onMounted(async () => {
  // Fetch wishlist products
  await getWishlistProducts();
});
</script>
<template>
  <div v-if="products.length">
    <h1>Wishlist</h1>
    <ProductCard
      v-for="product in products"
      :key="product.id"
      :product="product"
    />
  </div>
</template>
```

## Add product to the wishlist

You can use the `useProductWishlist` composable to add a product to the wishlist.
If the product is already added to the wishlist, the API will return an error.
To avoid such a situation, `isInWishlist` property should protect `addToWishlist` method.

:::tip
`addToWishlist` method will detect if the customer is logged in or not
:::

```vue
<script setup lang="ts">
// Mocked product
const product: Schemas["Product"] = {
  id: "7b5b97bd48454979b14f21c8ef38ce08",
};
const { addToWishlist, isInWishlist } = useProductWishlist(product);
</script>

<template>
  <button v-if="!isInWishlist" @click="addToWishlist">
    Add product to wishlist
  </button>
</template>
```

## Remove product from the wishlist

You can use the `useProductWishlist` composable to remove a product from the wishlist.
If the product doesn't exist in the wishlist, the API will return an error.
To avoid such a situation, `isInWishlist` property should protect `removeFromWishlist` method.

:::tip
`removeFromWishlist` method will detect if the customer is logged in or not
:::

```vue
<script setup lang="ts">
// Mocked product
const product: Product = {
  id: "7b5b97bd48454979b14f21c8ef38ce08",
};
const { removeFromWishlist, isInWishlist } = useProductWishlist(product);
</script>

<template>
  <button v-if="isInWishlist" @click="removeFromWishlist">
    Remove product from the wishlist
  </button>
</template>
```

## Merge wishlists

To synchronize the local wishlist with the remote wishlist (associated with the user's account), the `mergeWishlistProducts()` method must be triggered after the customer has logged in.

```vue{10}
<script setup lang="ts">
const formData = ref({
  username: "",
  password: "",
});
const invokeLogin = async (): Promise<void> => {
  try {
    // Login function
    await login(formData.value);
    mergeWishlistProducts();
  } catch (error) {
    console.error(error);
  }
};
</script>
<template>
  <form @submit.prevent="invokeLogin">
    <div>
      <label for="email-address">Email address</label>
      <input
        id="email-address"
        v-model="formData.username"
        name="email"
        type="email"
        autocomplete="email"
        required
        placeholder="Email address"
      />
    </div>
    <div>
      <label for="password" class="sr-only">Password</label>
      <input
        id="password"
        v-model="formData.password"
        name="password"
        type="password"
        autocomplete="current-password"
        required
        placeholder="Password"
      />
    </div>
    <div>
      <button type="submit">Sign in</button>
    </div>
  </form>
</template>
```

---

---
url: /docs/guides/plugins/apps/administration/starter-admin-extension.md
---

# Create an Admin Extension

This guide explains how to set up an extension for the Administration UI.

![An admin notification](../../../../assets/extension-api-notification.png)

## Prerequisites

In order to follow this guide, make sure you are familiar with and meet the following requirements:

* Basic CLI usage (creating files, directories, running commands)
* Installed [shopware-cli](../../../../products/tools/cli/) tools
* We will use the following libraries/software
  * npm
  * live-server (small local development live-reloading server)

## Create the app wrapper

Create the app "wrapper", the so-called app manifest. It is just a single XML file with some basic configuration.

### Create manifest file

Create the manifest file in a new directory. We'll call it our "project directory":

```text
SimpleNotification/
├─ manifest.xml
```

::: info
When using a self-hosted Shopware version, you can create the project directory in the `custom/apps` directory of your Shopware installation. However, the descriptions in this guide apply to both Shopware cloud and self-hosted stores.
:::

Next, add the basic configuration to the file:

::: code-group

```xml [manifest.xml]
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        <name>SimpleNotification</name>
        <label>Hi Developer App</label>
        <description>This app shows a notification in the admin panel</description>
        <author>shopware AG</author>
        <copyright>(c) shopware AG</copyright>
        <version>1.0.0</version>
        <license>MIT</license>
    </meta>
</manifest>
```

:::

## Set up communication between Shopware and the app

Next, we need to set up an entry point, so Shopware and your app can communicate. The entry point is a static `.html` file, which includes the Extension SDK script and defines our extension.

![Communication between the admin panel and your entry point](../../../../assets/extension-api-communication.png)

The file will be rendered as a hidden iFrame within your admin panel. Using `postMessage` requests, the iFrame and your admin panel can communicate and exchange data.

Let's create an `index.html` file in a directory called `src`.

```text
SimpleNotification/
├─ src/
│  ├─ index.html
├─ manifest.xml
```

```html
// src/index.html
<!doctype html>
<html>
    <head>
        <script src="https://unpkg.com/@shopware-ag/meteor-admin-sdk/cdn"></script>
    </head>
    <script>
        sw.notification.dispatch({
            title: 'Hi there',
            message: 'Looks like someone sent you a message'
        });
    </script>
</html>
```

This file contains the basic setup for our app to display the notification:

* The HTML is rendered in a hidden iFrame when the Administration panel is loaded.
* The Meteor Admin SDK script is loaded through a CDN and exposed as the `sw` object.
* We use the `notification.dispatch` SDK method to display a simple notification with a title and a message.

### Start the local development server

Next, we need to start the live server, so you don't always have to reload the page manually.

```bash
npm install -g live-server
live-server src
```

Now the file should be available on <http://127.0.0.1:8080>.

### Add the entry point link to your manifest

The final step of the setup is to configure your app to use that file as an entry point.

To do that, we have to add an `admin` section to our `manifest.xml` file and pass it into the `base-app-url` tag:

::: code-group

```xml [manifest.xml]
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        <!-- ... -->
    </meta>
  <setup>
    <registrationUrl>http://127.0.0.1:8000/app/lifecycle/register</registrationUrl>
    <secret>TestSecret</secret>
  </setup>
    <admin>
        <base-app-url>http://127.0.0.1:8080</base-app-url>
    </admin>
</manifest>
```

:::

Since the URL to your entry point is only available locally, you will only be able to see changes on your own machine. If you want to share it, for development purposes, you need to host the entry point file somewhere or use services to expose local files as public URLs, such as [ngrok](https://ngrok.com/).

For production usage, you should host the entry point file on a public CDN or a static site hosting.

## Install the app

In this last step, we will install the app using the Shopware CLI tools.

::: info
If this is your first time using the Shopware CLI, you have to [install](../../../../products/tools/cli/installation) it first. Next, configure it using the `shopware-cli project config init` command.
:::

```bash
shopware-cli project extension upload SimpleNotification --activate --increase-version
```

This command will create a zip file from the specified extension directory and upload it to your configured store.
The `--increase-version` parameter increases the version specified in the `manifest.xml` file. This flag is required so Shopware picks up changes made to the `manifest.xml` since the last installation.
When the app is successfully installed, you will see the notification pop up once you open the Shopware admin panel - congratulations!

## Next steps

This example showed end-to-end how to create a local dev environment and connect it with your Shopware Store. There is a lot more to learn and try out, so why not move on with one of those topics:

* Add [new sections](https://developer.shopware.com/resources/admin-extension-sdk/api-reference/ui/component-section.html) or [entire modules](https://developer.shopware.com/resources/admin-extension-sdk/api-reference/ui/mainModule.html) to the UI
* The Meteor Admin SDK also offers [TypeScript support](https://developer.shopware.com/resources/admin-extension-sdk/getting-started/installation.html#using-npm-require-bundling), including autocompletion
* Don't want to extend the admin panel? Have a look at [App Scripts](../app-scripts/index.md)

---

---
url: /frontends/guides/cms/create-blocks.md
---

# Create Blocks (CMS)

Make sure, you've created a new file as described in [customize components](customize-components.html#create-new-files).

Next, import the correct type for your block and use it to define the `content` property:

```vue
<!-- components/cms/CmsBlockImageThreeColumn.vue -->
<script setup lang="ts">
import { CmsBlockImageThreeColumn } from "@shopware/composables";

const props = defineProps<{
  content: CmsBlockImageThreeColumn;
}>();
</script>
```

## Slots

:::info Only for `cms-base` package
Also here, if you are not using the `cms-base` package, you have to come up with your own implementation of a generic component that handles the slot resolution. In that case, please ignore the mentions of `CmsGenericElement`.
:::

Since blocks are usually layouts, they have slots which can be filled with dynamic content - CMS elements. Since blocks are flexible, the specific type of the element is not known in advance.

For that reason, there's a generic element `CmsGenericElement` which can be placed in every slot. It receives the `content` configuration as its only prop.

Let's build the `image-three-column` block, which has three slots - `left`, `center` and `right`.

```vue{4-15}
<!-- components/cms/CmsBlockImageThreeColumn.vue -->
<template>
    <div class="grid grid-cols-3">
        <CmsGenericElement
            :content="props.content.slots.filter(
                (slot) => slot.slot === 'left')
            " />
        <CmsGenericElement
            :content="props.content.slots.filter(
                (slot) => slot.slot === 'center')
            " />
        <CmsGenericElement
            :content="props.content.slots.filter(
                (slot) => slot.slot === 'right')
            " />
    </div>
</template>
```

That works, but it's quite repetiive and hard to read. So we can use another composable `useCmsBlock` which makes our lives way easier.

```vue{8,10-12,16-18}
<script setup lang="ts">
import { CmsBlockImageThreeColumn } from "@shopware/composables";

const props = defineProps<{
  content: CmsBlockImageThreeColumn;
}>();

const { getSlotContent } = useCmsBlock(props.content);

const leftContent = getSlotContent("left");
const rightContent = getSlotContent("right");
const centerContent = getSlotContent("center");
</script>
<template>
    <div class="grid grid-cols-3">
        <CmsGenericElement :content="leftContent" />
        <CmsGenericElement :content="centerContent" />
        <CmsGenericElement :content="rightContent" />
    </div>
</template>
```

No you can go ahead and override blocks and elements step by step.

---

---
url: /frontends/guides/cms/content-pages.md
---

# Create content pages

In this chapter you will learn how to display content pages with data from Shopware's own CMS. It is based on the mechanism of routing and fetching page content described in the [previous chapter](../routing). The case of building fully custom components from scratch will be covered as well. Specifically, you will learn how to

* Render a content page using the cms-base package
* Render a content page using custom components

## Use the cms-base package

Using the cms-base package, you don't have to implement any CMS components by yourself. You can start with a working implementation but add and override single components as you need. It requires a couple dependencies for styling and validation purposes to work properly.

### Install the package

Depending on which template you are using you need to install the package first.
See [install the package](../../concepts/shopping-experiences#install-the-package).

### Render the page

Now, you can import all components from the `@shopware/cms-base-layer` package and use them in your templates. The most straightforward way to render a page is to use the `CmsPage` component. It takes a `content` prop and resolves all subordinate sections, blocks and elements automatically. Put the following code in your catch-all component that also handles the [routing logic](../routing#resolve-a-route-to-a-page).

```vue-html
<CmsPage v-if="data" :content="data.cmsPage"/>
```

:::warning This will only work
if you followed the previous chapter on [routing](../routing). The `data` value in this example is a reactive reference to either a product, a category or a landing page response. If you are not sure how to get the data otherwise, check that chapter and see how the data is fetched.
:::

### Customize components

The `cms-base` package has an opinionated style of components and is based on Tailwind.css. If you want to override components or add custom ones, you can build them right into your project or import them as a separate package.

## Use custom components

If you use custom components and not the cms-base package, you have to ensure the correct rendering of the page. You also need to re-create all components that the Shopware CMS uses. For the creation of custom components - such as elements or blocks, you can follow the instructions given in [Shopping Experiences](../../concepts/shopping-experiences) and benefit from typehinting and the `useCms*` composables.

---

---
url: /frontends/guides/cms/create-elements.md
---

# Create Elements (CMS)

Start with importing the correct element type from the `@shopware/composables` package and using it in the `defineProps` method to define the type of your `content` property:

```vue
<!-- components/cms/CmsElementImage.vue -->

<script setup lang="ts">
import { CmsElementImage } from "@shopware/composables";

const props = defineProps<{
  content: CmsElementImage;
}>();
</script>
```

Now, you can use `props.content` to access all properties of the element in your template.

```vue{8}
<!-- components/cms/CmsElementImage.vue -->

<script setup lang="ts">
// see above
</script>

<template>
    <img :src="props.content.data.media.url" />
</template>
```

However, for some elements the configuration can be quite complex, so there are composables to give you a hand:

```vue{10-14,18-20}
<!-- components/cms/CmsElementImage.vue -->

<script setup lang="ts">
import { CmsElementImage, useCmsElementImage } from "@shopware/composables";

const props = defineProps<{
    content: CmsElementImage
}>();

const {
    containerStyle, // padding, background-color etc.
    displayMode, // cover, contain, stretch etc.
    imageAttrs, // automatically resolves src, alt and srcset attributes
} = useCmsElementImage(props.content);
</script>

<template>
    <div :style="containerStyle">
        <img v-bind="imageAttrs"/>
    </div>
</template>
```

---

---
url: >-
  /docs/products/extensions/b2b-components/employee-management/guides/creating-own-permissions-via-app.md
---

# Create Permissions via App

The App needs to use the API to extend and create permissions. Therefore, the apps can send a request to the Store API and pass the required parameters to the `/store-api/permission` route.

After doing that, the already existing permissions created by Shopware or added by plugin, will be merged with the permission created by apps.

It is important to note that permissions have a unique name. So a permission named `employee.read` can neither be added by apps nor by plugins, because this name is already in use. So a new name can better be added by making use of snippets.

## Snippets

The Snippet for the new permissions has to be added to the following namespace: `b2b.role-edit.permissions.[name]`. The placeholder has to be replaced by the name of the new permission, e.g., `b2b.role-edit.permissions.order.delete`.

---

---
url: >-
  /docs/v6.5/products/extensions/b2b-components/employee-management/guides/creating-own-permissions-via-app.md
---

# Create Permissions via App

App needs to use the API to extend and create permissions. Therefore, the apps can send a request to the Store API and pass the required parameters to [`/store-api/permission`]() route.

After doing that, the already existing permissions created by Shopware or added by plugin, will be merged with the permission created by apps.

It is important to note that permissions have a unique name. So a permission named `employee.read` can neither be added by apps nor by plugins, because this name is already in use. So a new name can better be added by making use of snippets.

## Snippets

The Snippet for the new permissions have to be added to the following namespace: `b2b.role-edit.permissions.[name]`. The placeholder has to be replaced by the name of the new permission, e.g., `b2b.role-edit.permissions.order.delete`.

---

---
url: >-
  /docs/v6.6/products/extensions/b2b-components/employee-management/guides/creating-own-permissions-via-app.md
---

# Create Permissions via App

The App needs to use the API to extend and create permissions. Therefore, the apps can send a request to the Store API and pass the required parameters to the `/store-api/permission` route.

After doing that, the already existing permissions created by Shopware or added by plugin, will be merged with the permission created by apps.

It is important to note that permissions have a unique name. So a permission named `employee.read` can neither be added by apps nor by plugins, because this name is already in use. So a new name can better be added by making use of snippets.

## Snippets

The Snippet for the new permissions has to be added to the following namespace: `b2b.role-edit.permissions.[name]`. The placeholder has to be replaced by the name of the new permission, e.g., `b2b.role-edit.permissions.order.delete`.

---

---
url: >-
  /docs/products/extensions/migration-assistant/guides/creating-a-new-migration-profile.md
---

# Creating a New Migration Profile

If you want to migrate your data from a different source system than Shopware, create a new migration profile for the Migration Assistant. But if you want to convert your plugin data from a Shopware system to Shopware 6, look at this article on [Extending a Shopware Migration Profile](extending-a-shopware-migration-profile).

## Setup

First, it is required that you already have installed the [Migration Assistant](https://github.com/shopware/SwagMigrationAssistant) plugin in Shopware 6 and have created a demo source system database with a `product` table. To create the table, use this SQL statement:

```sql
CREATE TABLE product
(
  id int PRIMARY KEY NOT NULL AUTO_INCREMENT,
  product_number varchar(255) NOT NULL,
  price float NOT NULL,
  stock int NOT NULL,
  product_name varchar(255) NOT NULL,
  tax float NOT NULL
);
```

This table should simulate a simple third-party source system, which should be migrated in the following steps.

## Creating a profile

In the first step, you have to create a new profile for your source system:

```php
<?php declare(strict_types=1);

namespace SwagMigrationOwnProfileExample;

use SwagMigrationAssistant\Migration\Profile\ProfileInterface;

class OwnProfile implements ProfileInterface
{
    public const PROFILE_NAME = 'ownProfile';

    public const SOURCE_SYSTEM_NAME = 'MySourceSystem';

    public const SOURCE_SYSTEM_VERSION = '1.0';

    public const AUTHOR_NAME = 'shopware AG';

    public const ICON_PATH = '/swagmigrationassistant/static/img/migration-assistant-plugin.svg';

    public function getName(): string
    {
        return self::PROFILE_NAME;
    }

    public function getSourceSystemName(): string
    {
        return self::SOURCE_SYSTEM_NAME;
    }

    public function getVersion(): string
    {
        return self::SOURCE_SYSTEM_VERSION;
    }

    public function getAuthorName(): string
    {
        return self::AUTHOR_NAME;
    }

    public function getIconPath(): string
    {
        return self::ICON_PATH;
    }
}
```

The profile itself does not contain any logic and is used to bundle the executing classes. To use this profile, you have to register and tag it in the `services.php` with `shopware.migration.profile`:

```php
$services->set(SwagMigrationOwnProfileExample\Profile\OwnProfile\OwnProfile::class)
    ->tag('shopware.migration.profile');
```

## Creating a gateway

Next, you have to create a new gateway which supports your profile:

```php
<?php declare(strict_types=1);

namespace SwagMigrationOwnProfileExample\Profile\OwnProfile\Gateway;

use Shopware\Core\Framework\Context;
use SwagMigrationAssistant\Migration\EnvironmentInformation;
use SwagMigrationAssistant\Migration\Gateway\GatewayInterface;
use SwagMigrationAssistant\Migration\Gateway\Reader\ReaderRegistry;
use SwagMigrationAssistant\Migration\MigrationContextInterface;
use SwagMigrationAssistant\Migration\RequestStatusStruct;
use SwagMigrationAssistant\Profile\Shopware\Exception\DatabaseConnectionException;
use SwagMigrationAssistant\Profile\Shopware\Gateway\Connection\ConnectionFactoryInterface;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\OwnProfile;

class OwnLocaleGateway implements GatewayInterface
{
    public const GATEWAY_NAME = 'local';

    private ConnectionFactoryInterface $connectionFactory;

    private ReaderRegistry $readerRegistry;

    public function __construct(
        ReaderRegistry $readerRegistry,
        ConnectionFactoryInterface $connectionFactory
    ) {
        $this->readerRegistry = $readerRegistry;
        $this->connectionFactory = $connectionFactory;
    }

    public function getName(): string
    {
        return self::GATEWAY_NAME;
    }

    public function supports(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof OwnProfile;
    }

    public function getSnippetName(): string
    {
        return 'swag-migration.wizard.pages.connectionCreate.gateways.shopwareLocal';
    }

    /**
     * Reads the given entity type from via context from its connection and returns the data
     */
    public function read(MigrationContextInterface $migrationContext): array
    {
        // TODO: Implement read() method.
        return [];
    }

    public function readEnvironmentInformation(
        MigrationContextInterface $migrationContext,
        Context $context
    ): EnvironmentInformation {
        $connection = $this->connectionFactory->createDatabaseConnection($migrationContext);
        $profile = $migrationContext->getProfile();

        try {
            $connection->connect();
        } catch (\Exception $e) {
            $error = new DatabaseConnectionException();

            return new EnvironmentInformation(
                $profile->getSourceSystemName(),
                $profile->getVersion(),
                '-',
                [],
                [],
                new RequestStatusStruct($error->getErrorCode(), $error->getMessage())
            );
        }
        $connection->close();

        $totals = $this->readTotals($migrationContext, $context);

        return new EnvironmentInformation(
            $profile->getSourceSystemName(),
            $profile->getVersion(),
            'Example Host Name',
            $totals,
            [],
            new RequestStatusStruct(),
            false
        );
    }

    public function readTotals(MigrationContextInterface $migrationContext, Context $context): array
    {
        $readers = $this->readerRegistry->getReaderForTotal($migrationContext);

        $totals = [];
        foreach ($readers as $reader) {
            $total = $reader->readTotal($migrationContext);

            if ($total === null) {
                continue;
            }

            $totals[$total->getEntityName()] = $total;
        }

        return $totals;
    }
}
```

As you have seen above, the gateway uses the `ConnectionFactory` to test the connection to the source system. You can also implement your own way to check this, but using this factory is the simplest way for a gateway to connect to a local database. Like the profile, you have to register the new gateway in the `services.php` and tag it with `shopware.migration.gateway`:

```php
use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

$services->set(SwagMigrationOwnProfileExample\Profile\OwnProfile\Gateway\OwnLocaleGateway::class)
    ->args([
        service(SwagMigrationAssistant\Migration\Gateway\Reader\ReaderRegistry::class),
        service(SwagMigrationAssistant\Profile\Shopware\Gateway\Connection\ConnectionFactory::class),
    ])
    ->tag('shopware.migration.gateway');
```

## Creating a credentials page

If you want to try your current progress in the Administration, you can select the profile and gateway in the migration wizard. If you try to go to the next page, there will be an error message because no credentials page was found. To create a new credentials page, you have to add an `index.js` for your new component into `Resources/app/administration/src/own-profile/profile`:

```javascript
import { Component } from 'src/core/shopware';
import template from './swag-migration-profile-ownProfile-local-credential-form.html.twig';

Component.register('swag-migration-profile-ownProfile-local-credential-form', {
    template,

    props: {
        credentials: {
            type: Object,
            default() {
                return {};
            }
        }
    },

    data() {
        return {
            inputCredentials: {
                dbHost: '',
                dbPort: '3306',
                dbUser: '',
                dbPassword: '',
                dbName: ''
            }
        };
    },

    watch: {
        credentials: {
            immediate: true,
            handler(newCredentials) {
                if (newCredentials === null) {
                    this.emitCredentials(this.inputCredentials);
                    return;
                }

                this.inputCredentials = newCredentials;
                this.emitOnChildRouteReadyChanged(
                    this.areCredentialsValid(this.inputCredentials)
                );
            }
        },

        inputCredentials: {
            deep: true,
            handler(newInputCredentials) {
                this.emitCredentials(newInputCredentials);
            }
        }
    },

    methods: {
        areCredentialsValid(newInputCredentials) {
            return (newInputCredentials.dbHost !== '' &&
                newInputCredentials.dbPort !== '' &&
                newInputCredentials.dbName !== '' &&
                newInputCredentials.dbUser !== '' &&
                newInputCredentials.dbPassword !== ''
            );
        },

        emitOnChildRouteReadyChanged(isReady) {
            this.$emit('onChildRouteReadyChanged', isReady);
        },

        emitCredentials(newInputCredentials) {
            this.$emit('onCredentialsChanged', newInputCredentials);
            this.emitOnChildRouteReadyChanged(
                this.areCredentialsValid(newInputCredentials)
            );
        },

        onKeyPressEnter() {
            this.$emit('onTriggerPrimaryClick');
        }
    }
});
```

As you can see above, currently, the template does not exist and you have to create this file: `swag-migration-profile-ownProfile-local-credential-form.html.twig`

```html
{% block own_profile_page_credentials %}
    <div class="swag-migration-wizard swag-migration-wizard-page-credentials"
         @keypress.enter="onKeyPressEnter">
        {% block own_profile_page_credentials_content %}
            <div class="swag-migration-wizard__content">
                {% block own_profile_page_credentials_information %}
                    <div class="swag-migration-wizard__content-information">
                        {% block own_profile_page_credentials_local_hint %}
                            {{ $tc('swag-migration.wizard.pages.credentials.shopware55.local.contentInformation') }}
                        {% endblock %}
                    </div>
                {% endblock %}

                {% block own_profile_page_credentials_credentials %}
                    <div class="swag-migration-wizard__form">
                        {% block own_profile_page_credentials_local_db_host_port_group %}
                            <sw-container columns="1fr 80px"
                                          gap="16px">
                                {% block own_profile_page_credentials_local_dbhost_field %}
                                    <sw-text-field v-autofocus
                                                   name="sw-field--dbHost"
                                                   :label="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbHostLabel')"
                                                   :placeholder="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbHostPlaceholder')"
                                                   v-model="inputCredentials.dbHost">
                                    </sw-text-field>
                                {% endblock %}

                                {% block own_profile_page_credentials_local_dbport_field %}
                                    <sw-field name="sw-field--dbPort"
                                              :label="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbPortLabel')"
                                              v-model="inputCredentials.dbPort">
                                    </sw-field>
                                {% endblock %}
                            </sw-container>
                        {% endblock %}

                        {% block own_profile_page_credentials_local_dbuser_field %}
                            <sw-field name="sw-field--dbUser"
                                      :label="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbUserLabel')"
                                      :placeholder="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbUserPlaceholder')"
                                      v-model="inputCredentials.dbUser">
                            </sw-field>
                        {% endblock %}

                        {% block own_profile_page_credentials_local_dbpassword_field %}
                            <sw-field name="sw-field--dbPassword"
                                      type="password"
                                      :label="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbPasswordLabel')"
                                      :placeholder="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbPasswordPlaceholder')"
                                      v-model="inputCredentials.dbPassword">
                            </sw-field>
                        {% endblock %}

                        {% block own_profile_page_credentials_local_dbname_field %}
                            <sw-field name="sw-field--dbName"
                                      :label="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbNameLabel')"
                                      :placeholder="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbNamePlaceholder')"
                                      v-model="inputCredentials.dbName">
                            </sw-field>
                        {% endblock %}
                    </div>
                {% endblock %}
            </div>
        {% endblock %}
    </div>
{% endblock %}
```

Note that the component name isn't random and consists of:

1. The prefix: `swag-migration-profile-`
2. The name of the profile
3. The name of the gateway
4. The suffix: `-credential-form`

To see your credentials page, you have to register this component in your `main.js`:

```javascript
import './own-profile/profile';
```

## Creating a dataSet and dataSelection

Now the credential page is loaded in the Administration and the connection check will succeed. But there is no data selection if you open the data selection table. To add an entry to this table, you have to create a `ProductDataSet` first:

```php
<?php declare(strict_types=1);

namespace SwagMigrationOwnProfileExample\Profile\OwnProfile\DataSelection\DataSet;

use SwagMigrationAssistant\Migration\DataSelection\DataSet\DataSet;
use SwagMigrationAssistant\Migration\MigrationContextInterface;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\OwnProfile;

class ProductDataSet extends DataSet
{
    /**
     * Returns the entity identifier of this DataSet
     */
    public static function getEntity(): string
    {
        return 'product';
    }

    /**
     * Supports only an OwnProfile
     */
    public function supports(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof OwnProfile;
    }
}
```

Now you have to use this `ProductDataSet` in the new `ProductDataSelection`:

```php
<?php declare(strict_types=1);

namespace SwagMigrationOwnProfileExample\Profile\OwnProfile\DataSelection;

use SwagMigrationAssistant\Migration\DataSelection\DataSelectionInterface;
use SwagMigrationAssistant\Migration\DataSelection\DataSelectionStruct;
use SwagMigrationAssistant\Migration\MigrationContextInterface;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\DataSelection\DataSet\ProductDataSet;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\OwnProfile;

class ProductDataSelection implements DataSelectionInterface
{
    /**
     * Identifier of this DataSelection
     */
    public const IDENTIFIER = 'products';

    /**
     * Supports only an OwnProfile
     */
    public function supports(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof OwnProfile;
    }

    public function getData(): DataSelectionStruct
    {
        return new DataSelectionStruct(
            self::IDENTIFIER,
            $this->getDataSets(),
            $this->getDataSetsRequiredForCount(),
            /*
             * Snippet of the original ProductDataSelection, if you
             * want to use your own title, you have to create a new snippet
             */
            'swag-migration.index.selectDataCard.dataSelection.products',
            100
        );
    }

    /**
     * Returns all DataSets, which should be migrated with this DataSelection
     */
    public function getDataSets(): array
    {
        return [
            new ProductDataSet()
        ];
    }

    public function getDataSetsRequiredForCount(): array
    {
        return $this->getDataSets();
    }
}
```

::: info
The order in the `getDataSets` array is important as it determines the order in which the entities are processed. Because of that, the manufacturers, for example, have to be positioned before the products so that the products can use those later on.
:::

To see the created `ProductDataSelection` in the Administration, you have to register it both in the `services.php` and tag them with `shopware.migration.data_selection` and `shopware.migration.data_set`:

```php
$services->set(SwagMigrationOwnProfileExample\Profile\OwnProfile\DataSelection\ProductDataSelection::class)
    ->tag('shopware.migration.data_selection');

$services->set(SwagMigrationOwnProfileExample\Profile\OwnProfile\DataSelection\DataSet\ProductDataSet::class)
    ->tag('shopware.migration.data_set');
```

## Creating a product gateway reader

Currently, you can see the `DataSelection` in the Administration, but if you select it and start a migration, no product will be migrated. That is because the gateway `read` function isn't implemented yet. But before you can implement this function, you have to create a new `ProductReader` first:

```php
<?php declare(strict_types=1);

namespace SwagMigrationOwnProfileExample\Profile\OwnProfile\Gateway\Reader;

use Doctrine\DBAL\Driver\ResultStatement;
use SwagMigrationAssistant\Migration\MigrationContextInterface;
use SwagMigrationAssistant\Migration\TotalStruct;
use SwagMigrationAssistant\Profile\Shopware\Gateway\Local\Reader\AbstractReader;
use SwagMigrationAssistant\Profile\Shopware\Gateway\Local\ShopwareLocalGateway;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\DataSelection\DataSet\ProductDataSet;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\OwnProfile;

class ProductReader extends AbstractReader
{
    /**
     * Supports only an OwnProfile and the ProductDataSet
     */
    public function supports(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof OwnProfile
            && $migrationContext->getDataSet()::getEntity() === ProductDataSet::getEntity();
    }

    /**
     * Supports only an OwnProfile and the ProductDataSet for totals
     */
    public function supportsTotal(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof OwnProfile
            && $migrationContext->getGateway()->getName() === ShopwareLocalGateway::GATEWAY_NAME;
    }

    /**
     * Creates a database connection and sets the connection class variable
     */
    protected function setConnection(MigrationContextInterface $migrationContext): void
    {
        $this->connection = $this->connectionFactory->createDatabaseConnection($migrationContext);
    }

    public function readTotal(MigrationContextInterface $migrationContext): ?TotalStruct
    {
        $this->setConnection($migrationContext);

        $query = $this->connection->createQueryBuilder()
            ->select('COUNT(*)')
            ->from('product')
            ->execute();

        $total = 0;
        if ($query instanceof ResultStatement) {
            $total = (int) $query->fetchColumn();
        }

        return new TotalStruct(ProductDataSet::getEntity(), $total);
    }

    /**
     * Fetches all entities out of the product table with the given limit
     */
    public function read(MigrationContextInterface $migrationContext, array $params = []): array
    {
        $this->setConnection($migrationContext);

        $query = $this->connection->createQueryBuilder();
        $query->from('product');
        $query->addSelect('*');

        $query->setFirstResult($migrationContext->getOffset());
        $query->setMaxResults($migrationContext->getLimit());

        return $query->execute()->fetchAll(\PDO::FETCH_ASSOC);
    }
}
```

Then you have to register this in `services.php` and tag it with `shopware.migration.reader`:

```php
$services->set(SwagMigrationOwnProfileExample\Profile\OwnProfile\Gateway\Reader\ProductReader::class)
    ->parent(SwagMigrationAssistant\Profile\Shopware\Gateway\Local\Reader\AbstractReader::class)
    ->args([
        service(SwagMigrationAssistant\Profile\Shopware\Gateway\Connection\ConnectionFactory::class),
    ])
    ->tag('shopware.migration.reader');
```

Once the `ProductReader` is created and registered, you can use it in the `read` method of the `OwnLocaleGateway`:

```php
<?php declare(strict_types=1);

namespace SwagMigrationOwnProfileExample\Profile\OwnProfile\Gateway;

use Shopware\Core\Framework\Context;
use SwagMigrationAssistant\Migration\EnvironmentInformation;
use SwagMigrationAssistant\Migration\Gateway\GatewayInterface;
use SwagMigrationAssistant\Migration\Gateway\Reader\ReaderRegistry;
use SwagMigrationAssistant\Migration\MigrationContextInterface;
use SwagMigrationAssistant\Migration\RequestStatusStruct;
use SwagMigrationAssistant\Profile\Shopware\Exception\DatabaseConnectionException;
use SwagMigrationAssistant\Profile\Shopware\Gateway\Connection\ConnectionFactoryInterface;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\OwnProfile;

class OwnLocaleGateway implements GatewayInterface
{
    public const GATEWAY_NAME = 'local';

    private ConnectionFactoryInterface $connectionFactory;

    private ReaderRegistry $readerRegistry;

    public function __construct(
        ReaderRegistry $readerRegistry,
        ConnectionFactoryInterface $connectionFactory
    ) {
        $this->readerRegistry = $readerRegistry;
        $this->connectionFactory = $connectionFactory;
    }

    public function getName(): string
    {
        return self::GATEWAY_NAME;
    }

    public function supports(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof OwnProfile;
    }

    public function getSnippetName(): string
    {
        return 'swag-migration.wizard.pages.connectionCreate.gateways.shopwareLocal';
    }

    public function read(MigrationContextInterface $migrationContext): array
    {
        $reader = $this->readerRegistry->getReader($migrationContext);

        return $reader->read($migrationContext);
    }

    public function readEnvironmentInformation(
        MigrationContextInterface $migrationContext,
        Context $context
    ): EnvironmentInformation {
        $connection = $this->connectionFactory->createDatabaseConnection($migrationContext);
        $profile = $migrationContext->getProfile();

        try {
            $connection->connect();
        } catch (\Exception $e) {
            $error = new DatabaseConnectionException();

            return new EnvironmentInformation(
                $profile->getSourceSystemName(),
                $profile->getVersion(),
                '-',
                [],
                [],
                new RequestStatusStruct($error->getErrorCode(), $error->getMessage())
            );
        }
        $connection->close();

        $totals = $this->readTotals($migrationContext, $context);

        return new EnvironmentInformation(
            $profile->getSourceSystemName(),
            $profile->getVersion(),
            'Example Host Name',
            $totals,
            [],
            new RequestStatusStruct(),
            false
        );
    }

    public function readTotals(MigrationContextInterface $migrationContext, Context $context): array
    {
        $readers = $this->readerRegistry->getReaderForTotal($migrationContext);

        $totals = [];
        foreach ($readers as $reader) {
            $total = $reader->readTotal($migrationContext);

            if ($total === null) {
                continue;
            }

            $totals[$total->getEntityName()] = $total;
        }

        return $totals;
    }
}
```

## Creating a converter

By using the gateway reader, you fetch all products but don't use this data yet. In this step, you implement the logic of the converter:

```php
<?php declare(strict_types=1);

namespace SwagMigrationOwnProfileExample\Profile\OwnProfile\Converter;

use Shopware\Core\Framework\Context;
use SwagMigrationAssistant\Migration\Converter\ConvertStruct;
use SwagMigrationAssistant\Migration\DataSelection\DefaultEntities;
use SwagMigrationAssistant\Migration\MigrationContextInterface;
use SwagMigrationAssistant\Profile\Shopware\Converter\ShopwareConverter;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\DataSelection\DataSet\ProductDataSet;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\OwnProfile;

class ProductConverter extends ShopwareConverter
{
    private string $connectionId;

    private Context $context;

    public function getSourceIdentifier(array $data): string
    {
        return $data['id'];
    }

    /**
     * Supports only an OwnProfile and the ProductDataSet
     */
    public function supports(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof OwnProfile &&
            $migrationContext->getDataSet()::getEntity() === ProductDataSet::getEntity();
    }

    /**
     * Writes the created mapping
     */
    public function writeMapping(Context $context): void
    {
        $this->mappingService->writeMapping($context);
    }

    public function convert(array $data, Context $context, MigrationContextInterface $migrationContext): ConvertStruct
    {
        $this->generateChecksum($data);
        $this->connectionId = $migrationContext->getConnection()->getId();
        $this->context = $context;

        /**
         * Gets the product uuid out of the mapping table or creates a new one
         */
        $this->mainMapping = $this->mappingService->getOrCreateMapping(
            $migrationContext->getConnection()->getId(),
            ProductDataSet::getEntity(),
            $data['id'],
            $context,
            $this->checksum
        );

        $converted['id'] = $this->mainMapping['entityUuid'];
        $this->convertValue($converted, 'productNumber', $data, 'product_number');
        $this->convertValue($converted, 'name', $data, 'product_name');
        $this->convertValue($converted, 'stock', $data, 'stock', self::TYPE_INTEGER);

        if (isset($data['tax'])) {
            $converted['tax'] = $this->getTax($data);
            $converted['price'] = $this->getPrice($data, $converted['tax']['taxRate']);
        }

        unset(
          $data['id'],
          $data['product_number'],
          $data['product_name'],
          $data['stock'],
          $data['tax'],
          $data['price']
        );

        if (empty($data)) {
            $data = null;
        }
        $this->updateMainMapping($migrationContext, $context);

        return new ConvertStruct($converted, $data, $this->mainMapping['id']);
    }

    private function getTax(array $data): array
    {
        $taxRate = (float) $data['tax'];

        /**
         * Gets the tax uuid by the given tax rate
         */
        $taxUuid = $this->mappingService->getTaxUuid($this->connectionId, $taxRate, $this->context);

        /**
         * If no tax rate is found, create a new one
         */
        if ($taxUuid === null) {
            $mapping = $this->mappingService->createMapping(
                $this->connectionId,
                DefaultEntities::TAX,
                $data['id']
            );
            $taxUuid = $mapping['entityUuid'];
        }

        return [
            'id' => $taxUuid,
            'taxRate' => $taxRate,
            'name' => 'Own profile tax rate (' . $taxRate . ')',
        ];
    }

    private function getPrice(array $data, float $taxRate): array
    {
        $gross = (float) $data['price'] * (1 + $taxRate / 100);

        /**
         * Gets the currency uuid by the given iso code
         */
        $currencyUuid = $this->mappingService->getCurrencyUuid(
            $this->connectionId,
            'EUR',
            $this->context
        );

        if ($currencyUuid === null) {
            return [];
        }

        $price = [];
        $price[] = [
            'currencyId' => $currencyUuid,
            'gross' => $gross,
            'net' => (float) $data['price'],
            'linked' => true,
        ];

        return $price;
    }
}
```

If you don't know which properties or requirements your entity has in Shopware 6, you may check the corresponding `EntityDefinition`. For this example, look at the `ProductEntityDefinition` to know how to convert the data exactly.

To use this converter, you must register it in the `services.php`:

```php
$services->set(SwagMigrationOwnProfileExample\Profile\OwnProfile\Converter\ProductConverter::class)
    ->args([
        service(SwagMigrationAssistant\Migration\Mapping\MappingService::class),
        service(SwagMigrationAssistant\Migration\Logging\LoggingService::class),
    ])
    ->tag('shopware.migration.converter');
```

To write new entities, you have to create a new writer class, but for the product entity, you can use the `ProductWriter`:

```php
<?php declare(strict_types=1);

namespace SwagMigrationAssistant\Migration\Writer;

use SwagMigrationAssistant\Migration\DataSelection\DefaultEntities;

class ProductWriter extends AbstractWriter
{
    public function supports(): string
    {
        return DefaultEntities::PRODUCT;
    }
}
```

This writer will be called automatically as the `getEntityName` method of your `ProductDataSet` is compared with the return value of the `supports` method of the writer in the `WriterRegistry`. These values are identical, and so the writer will be used to write your product entities.

## Source

Check out this [GitHub repository](https://github.com/shopwareArchive/swag-docs-create-migration-profile) containing a full example source.

---

---
url: >-
  /docs/v6.5/products/extensions/migration-assistant/guides/creating-a-new-migration-profile.md
---

# Creating a New Migration Profile

If you want to migrate your data from a different source system than Shopware, create a new migration profile for the Migration Assistant. But if you want to convert your plugin data from a Shopware system to Shopware 6, look at this article on [Extending a Shopware Migration Profile](extending-a-shopware-migration-profile).

## Setup

First of all, it is required that you already have installed the [Migration Assistant](https://github.com/shopware/SwagMigrationAssistant) plugin in Shopware 6 and have created a demo source system database with a `product` table. To create the table, use this SQL statement:

```sql
CREATE TABLE product
(
  id int PRIMARY KEY NOT NULL AUTO_INCREMENT,
  product_number varchar(255) NOT NULL,
  price float NOT NULL,
  stock int NOT NULL,
  product_name varchar(255) NOT NULL,
  tax float NOT NULL
);
```

This table should simulate a simple third-party source system, which should be migrated in the following steps.

## Creating a profile

In the first step, you have to create a new profile for your source system:

```php
<?php declare(strict_types=1);

namespace SwagMigrationOwnProfileExample;

use SwagMigrationAssistant\Migration\Profile\ProfileInterface;

class OwnProfile implements ProfileInterface
{
    public const PROFILE_NAME = 'ownProfile';

    public const SOURCE_SYSTEM_NAME = 'MySourceSystem';

    public const SOURCE_SYSTEM_VERSION = '1.0';

    public const AUTHOR_NAME = 'shopware AG';

    public const ICON_PATH = '/swagmigrationassistant/static/img/migration-assistant-plugin.svg';

    public function getName(): string
    {
        return self::PROFILE_NAME;
    }

    public function getSourceSystemName(): string
    {
        return self::SOURCE_SYSTEM_NAME;
    }

    public function getVersion(): string
    {
        return self::SOURCE_SYSTEM_VERSION;
    }

    public function getAuthorName(): string
    {
        return self::AUTHOR_NAME;
    }

    public function getIconPath(): string
    {
        return self::ICON_PATH;
    }
}
```

The profile itself does not contain any logic and is used to bundle the executing classes. To use this profile, you have to register and tag it in the `service.xml` with `shopware.migration.profile`:

```html
<service id="SwagMigrationOwnProfileExample\Profile\OwnProfile\OwnProfile">
    <tag name="shopware.migration.profile"/>
</service>
```

## Creating a gateway

Next, you have to create a new gateway which supports your profile:

```php
<?php declare(strict_types=1);

namespace SwagMigrationOwnProfileExample\Profile\OwnProfile\Gateway;

use Shopware\Core\Framework\Context;
use SwagMigrationAssistant\Migration\EnvironmentInformation;
use SwagMigrationAssistant\Migration\Gateway\GatewayInterface;
use SwagMigrationAssistant\Migration\Gateway\Reader\ReaderRegistry;
use SwagMigrationAssistant\Migration\MigrationContextInterface;
use SwagMigrationAssistant\Migration\RequestStatusStruct;
use SwagMigrationAssistant\Profile\Shopware\Exception\DatabaseConnectionException;
use SwagMigrationAssistant\Profile\Shopware\Gateway\Connection\ConnectionFactoryInterface;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\OwnProfile;

class OwnLocaleGateway implements GatewayInterface
{
    public const GATEWAY_NAME = 'local';

    private ConnectionFactoryInterface $connectionFactory;

    private ReaderRegistry $readerRegistry;

    public function __construct(
        ReaderRegistry $readerRegistry,
        ConnectionFactoryInterface $connectionFactory
    ) {
        $this->readerRegistry = $readerRegistry;
        $this->connectionFactory = $connectionFactory;
    }

    public function getName(): string
    {
        return self::GATEWAY_NAME;
    }

    public function supports(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof OwnProfile;
    }

    public function getSnippetName(): string
    {
        return 'swag-migration.wizard.pages.connectionCreate.gateways.shopwareLocal';
    }

    /**
     * Reads the given entity type from via context from its connection and returns the data
     */
    public function read(MigrationContextInterface $migrationContext): array
    {
        // TODO: Implement read() method.
        return [];
    }

    public function readEnvironmentInformation(
        MigrationContextInterface $migrationContext,
        Context $context
    ): EnvironmentInformation {
        $connection = $this->connectionFactory->createDatabaseConnection($migrationContext);
        $profile = $migrationContext->getProfile();

        try {
            $connection->connect();
        } catch (\Exception $e) {
            $error = new DatabaseConnectionException();

            return new EnvironmentInformation(
                $profile->getSourceSystemName(),
                $profile->getVersion(),
                '-',
                [],
                [],
                new RequestStatusStruct($error->getErrorCode(), $error->getMessage())
            );
        }
        $connection->close();

        $totals = $this->readTotals($migrationContext, $context);

        return new EnvironmentInformation(
            $profile->getSourceSystemName(),
            $profile->getVersion(),
            'Example Host Name',
            $totals,
            [],
            new RequestStatusStruct(),
            false
        );
    }

    public function readTotals(MigrationContextInterface $migrationContext, Context $context): array
    {
        $readers = $this->readerRegistry->getReaderForTotal($migrationContext);

        $totals = [];
        foreach ($readers as $reader) {
            $total = $reader->readTotal($migrationContext);

            if ($total === null) {
                continue;
            }

            $totals[$total->getEntityName()] = $total;
        }

        return $totals;
    }
}
```

As you have seen above, the gateway uses the `ConnectionFactory` to test the connection to the source system. You can also implement your own way to check this, but using this factory is the simplest way for a gateway to connect to a local database. Like the profile, you have to register the new gateway in the `service.xml` and tag it with `shopware.migration.gateway`:

```html
<service id="SwagMigrationOwnProfileExample\Profile\OwnProfile\Gateway\OwnLocaleGateway">
    <argument type="service" id="SwagMigrationAssistant\Migration\Gateway\Reader\ReaderRegistry"/>
    <argument type="service" id="SwagMigrationAssistant\Profile\Shopware\Gateway\Connection\ConnectionFactory"/>
    <tag name="shopware.migration.gateway"/>
</service>
```

## Creating a credentials page

If you want to try your current progress in the Administration, you can select the profile and gateway in the migration wizard. If you try to go to the next page, there will be an error message because no credentials page was found. To create a new credentials page, you have to add an `index.js` for your new component into `Resources/app/administration/src/own-profile/profile`:

```javascript
import { Component } from 'src/core/shopware';
import template from './swag-migration-profile-ownProfile-local-credential-form.html.twig';

Component.register('swag-migration-profile-ownProfile-local-credential-form', {
    template,

    props: {
        credentials: {
            type: Object,
            default() {
                return {};
            }
        }
    },

    data() {
        return {
            inputCredentials: {
                dbHost: '',
                dbPort: '3306',
                dbUser: '',
                dbPassword: '',
                dbName: ''
            }
        };
    },

    watch: {
        credentials: {
            immediate: true,
            handler(newCredentials) {
                if (newCredentials === null) {
                    this.emitCredentials(this.inputCredentials);
                    return;
                }

                this.inputCredentials = newCredentials;
                this.emitOnChildRouteReadyChanged(
                    this.areCredentialsValid(this.inputCredentials)
                );
            }
        },

        inputCredentials: {
            deep: true,
            handler(newInputCredentials) {
                this.emitCredentials(newInputCredentials);
            }
        }
    },

    methods: {
        areCredentialsValid(newInputCredentials) {
            return (newInputCredentials.dbHost !== '' &&
                newInputCredentials.dbPort !== '' &&
                newInputCredentials.dbName !== '' &&
                newInputCredentials.dbUser !== '' &&
                newInputCredentials.dbPassword !== ''
            );
        },

        emitOnChildRouteReadyChanged(isReady) {
            this.$emit('onChildRouteReadyChanged', isReady);
        },

        emitCredentials(newInputCredentials) {
            this.$emit('onCredentialsChanged', newInputCredentials);
            this.emitOnChildRouteReadyChanged(
                this.areCredentialsValid(newInputCredentials)
            );
        },

        onKeyPressEnter() {
            this.$emit('onTriggerPrimaryClick');
        }
    }
});
```

As you can see above, currently, the template does not exist and you have to create this file: `swag-migration-profile-ownProfile-local-credential-form.html.twig`

```html
{% block own_profile_page_credentials %}
    <div class="swag-migration-wizard swag-migration-wizard-page-credentials"
         @keypress.enter="onKeyPressEnter">
        {% block own_profile_page_credentials_content %}
            <div class="swag-migration-wizard__content">
                {% block own_profile_page_credentials_information %}
                    <div class="swag-migration-wizard__content-information">
                        {% block own_profile_page_credentials_local_hint %}
                            {{ $tc('swag-migration.wizard.pages.credentials.shopware55.local.contentInformation') }}
                        {% endblock %}
                    </div>
                {% endblock %}

                {% block own_profile_page_credentials_credentials %}
                    <div class="swag-migration-wizard__form">
                        {% block own_profile_page_credentials_local_db_host_port_group %}
                            <sw-container columns="1fr 80px"
                                          gap="16px">
                                {% block own_profile_page_credentials_local_dbhost_field %}
                                    <sw-text-field v-autofocus
                                                   name="sw-field--dbHost"
                                                   :label="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbHostLabel')"
                                                   :placeholder="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbHostPlaceholder')"
                                                   v-model="inputCredentials.dbHost">
                                    </sw-text-field>
                                {% endblock %}

                                {% block own_profile_page_credentials_local_dbport_field %}
                                    <sw-field name="sw-field--dbPort"
                                              :label="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbPortLabel')"
                                              v-model="inputCredentials.dbPort">
                                    </sw-field>
                                {% endblock %}
                            </sw-container>
                        {% endblock %}

                        {% block own_profile_page_credentials_local_dbuser_field %}
                            <sw-field name="sw-field--dbUser"
                                      :label="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbUserLabel')"
                                      :placeholder="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbUserPlaceholder')"
                                      v-model="inputCredentials.dbUser">
                            </sw-field>
                        {% endblock %}

                        {% block own_profile_page_credentials_local_dbpassword_field %}
                            <sw-field name="sw-field--dbPassword"
                                      type="password"
                                      :label="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbPasswordLabel')"
                                      :placeholder="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbPasswordPlaceholder')"
                                      v-model="inputCredentials.dbPassword">
                            </sw-field>
                        {% endblock %}

                        {% block own_profile_page_credentials_local_dbname_field %}
                            <sw-field name="sw-field--dbName"
                                      :label="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbNameLabel')"
                                      :placeholder="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbNamePlaceholder')"
                                      v-model="inputCredentials.dbName">
                            </sw-field>
                        {% endblock %}
                    </div>
                {% endblock %}
            </div>
        {% endblock %}
    </div>
{% endblock %}
```

Note that the component name isn't random and consists of:

1. The prefix: `swag-migration-profile-`
2. The name of the profile
3. The name of the gateway
4. The suffix: `-credential-form`

To see your credentials page, you have to register this component in your `main.js`:

```javascript
import './own-profile/profile';
```

## Creating a dataSet and dataSelection

Now the credentials page is loaded in the Administration and the connection check will succeed. But there is no data selection if you open the data selection table. To add an entry to this table, you have to create a `ProductDataSet` first:

```php
<?php declare(strict_types=1);

namespace SwagMigrationOwnProfileExample\Profile\OwnProfile\DataSelection\DataSet;

use SwagMigrationAssistant\Migration\DataSelection\DataSet\DataSet;
use SwagMigrationAssistant\Migration\MigrationContextInterface;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\OwnProfile;

class ProductDataSet extends DataSet
{
    /**
     * Returns the entity identifier of this DataSet
     */
    public static function getEntity(): string
    {
        return 'product';
    }

    /**
     * Supports only an OwnProfile
     */
    public function supports(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof OwnProfile;
    }
}
```

Now you have to use this `ProductDataSet` in the new `ProductDataSelection`:

```php
<?php declare(strict_types=1);

namespace SwagMigrationOwnProfileExample\Profile\OwnProfile\DataSelection;

use SwagMigrationAssistant\Migration\DataSelection\DataSelectionInterface;
use SwagMigrationAssistant\Migration\DataSelection\DataSelectionStruct;
use SwagMigrationAssistant\Migration\MigrationContextInterface;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\DataSelection\DataSet\ProductDataSet;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\OwnProfile;

class ProductDataSelection implements DataSelectionInterface
{
    /**
     * Identifier of this DataSelection
     */
    public const IDENTIFIER = 'products';

    /**
     * Supports only an OwnProfile
     */
    public function supports(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof OwnProfile;
    }

    public function getData(): DataSelectionStruct
    {
        return new DataSelectionStruct(
            self::IDENTIFIER,
            $this->getDataSets(),
            $this->getDataSetsRequiredForCount(),
            /*
             * Snippet of the original ProductDataSelection, if you
             * want to use your own title, you have to create a new snippet
             */
            'swag-migration.index.selectDataCard.dataSelection.products',
            100
        );
    }

    /**
     * Returns all DataSets, which should be migrated with this DataSelection
     */
    public function getDataSets(): array
    {
        return [
            new ProductDataSet()
        ];
    }

    public function getDataSetsRequiredForCount(): array
    {
        return $this->getDataSets();
    }
}
```

::: info
The order in the `getDataSets` array is important as it determines the order in which the entities are processed. Because of that, the manufacturers, for example, have to be positioned before the products so that the products can use those later on.
:::

To see the created `ProductDataSelection` in the Administration, you have to register it both in the `services.xml` and tag them with `shopware.migration.data_selection` and `shopware.migration.data_set`:

```html
<service id="SwagMigrationOwnProfileExample\Profile\OwnProfile\DataSelection\ProductDataSelection">
    <tag name="shopware.migration.data_selection"/>
</service>

<service id="SwagMigrationOwnProfileExample\Profile\OwnProfile\DataSelection\DataSet\ProductDataSet">
    <tag name="shopware.migration.data_set"/>
</service>
```

## Creating a product gateway reader

Currently, you can see the `DataSelection` in the Administration, but if you select it and start a migration, no product will be migrated. That is because the gateway `read` function isn't implemented yet. But before you can implement this function, you have to create a new `ProductReader` first:

```php
<?php declare(strict_types=1);

namespace SwagMigrationOwnProfileExample\Profile\OwnProfile\Gateway\Reader;

use Doctrine\DBAL\Driver\ResultStatement;
use SwagMigrationAssistant\Migration\MigrationContextInterface;
use SwagMigrationAssistant\Migration\TotalStruct;
use SwagMigrationAssistant\Profile\Shopware\Gateway\Local\Reader\AbstractReader;
use SwagMigrationAssistant\Profile\Shopware\Gateway\Local\ShopwareLocalGateway;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\DataSelection\DataSet\ProductDataSet;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\OwnProfile;

class ProductReader extends AbstractReader
{
    /**
     * Supports only an OwnProfile and the ProductDataSet
     */
    public function supports(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof OwnProfile
            && $migrationContext->getDataSet()::getEntity() === ProductDataSet::getEntity();
    }

    /**
     * Supports only an OwnProfile and the ProductDataSet for totals
     */
    public function supportsTotal(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof OwnProfile
            && $migrationContext->getGateway()->getName() === ShopwareLocalGateway::GATEWAY_NAME;
    }

    /**
     * Creates a database connection and sets the connection class variable
     */
    protected function setConnection(MigrationContextInterface $migrationContext): void
    {
        $this->connection = $this->connectionFactory->createDatabaseConnection($migrationContext);
    }

    public function readTotal(MigrationContextInterface $migrationContext): ?TotalStruct
    {
        $this->setConnection($migrationContext);

        $query = $this->connection->createQueryBuilder()
            ->select('COUNT(*)')
            ->from('product')
            ->execute();

        $total = 0;
        if ($query instanceof ResultStatement) {
            $total = (int) $query->fetchColumn();
        }

        return new TotalStruct(ProductDataSet::getEntity(), $total);
    }

    /**
     * Fetches all entities out of the product table with the given limit
     */
    public function read(MigrationContextInterface $migrationContext, array $params = []): array
    {
        $this->setConnection($migrationContext);

        $query = $this->connection->createQueryBuilder();
        $query->from('product');
        $query->addSelect('*');

        $query->setFirstResult($migrationContext->getOffset());
        $query->setMaxResults($migrationContext->getLimit());

        return $query->execute()->fetchAll(\PDO::FETCH_ASSOC);
    }
}
```

Then you have to register this in `services.xml` and tag it with `shopware.migration.reader`:

```html
<service id="SwagMigrationOwnProfileExample\Profile\OwnProfile\Gateway\Reader\ProductReader"
    parent="SwagMigrationAssistant\Profile\Shopware\Gateway\Local\Reader\AbstractReader">
    <argument type="service" id="SwagMigrationAssistant\Profile\Shopware\Gateway\Connection\ConnectionFactory"/>
    <tag name="shopware.migration.reader"/>
</service>
```

Once the `ProductReader` is created and registered, you can use it in the `read` method of the `OwnLocaleGateway`:

```php
<?php declare(strict_types=1);

namespace SwagMigrationOwnProfileExample\Profile\OwnProfile\Gateway;

use Shopware\Core\Framework\Context;
use SwagMigrationAssistant\Migration\EnvironmentInformation;
use SwagMigrationAssistant\Migration\Gateway\GatewayInterface;
use SwagMigrationAssistant\Migration\Gateway\Reader\ReaderRegistry;
use SwagMigrationAssistant\Migration\MigrationContextInterface;
use SwagMigrationAssistant\Migration\RequestStatusStruct;
use SwagMigrationAssistant\Profile\Shopware\Exception\DatabaseConnectionException;
use SwagMigrationAssistant\Profile\Shopware\Gateway\Connection\ConnectionFactoryInterface;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\OwnProfile;

class OwnLocaleGateway implements GatewayInterface
{
    public const GATEWAY_NAME = 'local';

    private ConnectionFactoryInterface $connectionFactory;

    private ReaderRegistry $readerRegistry;

    public function __construct(
        ReaderRegistry $readerRegistry,
        ConnectionFactoryInterface $connectionFactory
    ) {
        $this->readerRegistry = $readerRegistry;
        $this->connectionFactory = $connectionFactory;
    }

    public function getName(): string
    {
        return self::GATEWAY_NAME;
    }

    public function supports(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof OwnProfile;
    }

    public function getSnippetName(): string
    {
        return 'swag-migration.wizard.pages.connectionCreate.gateways.shopwareLocal';
    }

    public function read(MigrationContextInterface $migrationContext): array
    {
        $reader = $this->readerRegistry->getReader($migrationContext);

        return $reader->read($migrationContext);
    }

    public function readEnvironmentInformation(
        MigrationContextInterface $migrationContext,
        Context $context
    ): EnvironmentInformation {
        $connection = $this->connectionFactory->createDatabaseConnection($migrationContext);
        $profile = $migrationContext->getProfile();

        try {
            $connection->connect();
        } catch (\Exception $e) {
            $error = new DatabaseConnectionException();

            return new EnvironmentInformation(
                $profile->getSourceSystemName(),
                $profile->getVersion(),
                '-',
                [],
                [],
                new RequestStatusStruct($error->getErrorCode(), $error->getMessage())
            );
        }
        $connection->close();

        $totals = $this->readTotals($migrationContext, $context);

        return new EnvironmentInformation(
            $profile->getSourceSystemName(),
            $profile->getVersion(),
            'Example Host Name',
            $totals,
            [],
            new RequestStatusStruct(),
            false
        );
    }

    public function readTotals(MigrationContextInterface $migrationContext, Context $context): array
    {
        $readers = $this->readerRegistry->getReaderForTotal($migrationContext);

        $totals = [];
        foreach ($readers as $reader) {
            $total = $reader->readTotal($migrationContext);

            if ($total === null) {
                continue;
            }

            $totals[$total->getEntityName()] = $total;
        }

        return $totals;
    }
}
```

## Creating a converter

By using the gateway reader, you fetch all products but don't use this data yet. In this step, you implement the logic of the converter:

```php
<?php declare(strict_types=1);

namespace SwagMigrationOwnProfileExample\Profile\OwnProfile\Converter;

use Shopware\Core\Framework\Context;
use SwagMigrationAssistant\Migration\Converter\ConvertStruct;
use SwagMigrationAssistant\Migration\DataSelection\DefaultEntities;
use SwagMigrationAssistant\Migration\MigrationContextInterface;
use SwagMigrationAssistant\Profile\Shopware\Converter\ShopwareConverter;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\DataSelection\DataSet\ProductDataSet;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\OwnProfile;

class ProductConverter extends ShopwareConverter
{
    private string $connectionId;

    private Context $context;

    public function getSourceIdentifier(array $data): string
    {
        return $data['id'];
    }

    /**
     * Supports only an OwnProfile and the ProductDataSet
     */
    public function supports(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof OwnProfile &&
            $migrationContext->getDataSet()::getEntity() === ProductDataSet::getEntity();
    }

    /**
     * Writes the created mapping
     */
    public function writeMapping(Context $context): void
    {
        $this->mappingService->writeMapping($context);
    }

    public function convert(array $data, Context $context, MigrationContextInterface $migrationContext): ConvertStruct
    {
        $this->generateChecksum($data);
        $this->connectionId = $migrationContext->getConnection()->getId();
        $this->context = $context;

        /**
         * Gets the product uuid out of the mapping table or creates a new one
         */
        $this->mainMapping = $this->mappingService->getOrCreateMapping(
            $migrationContext->getConnection()->getId(),
            ProductDataSet::getEntity(),
            $data['id'],
            $context,
            $this->checksum
        );

        $converted['id'] = $this->mainMapping['entityUuid'];
        $this->convertValue($converted, 'productNumber', $data, 'product_number');
        $this->convertValue($converted, 'name', $data, 'product_name');
        $this->convertValue($converted, 'stock', $data, 'stock', self::TYPE_INTEGER);

        if (isset($data['tax'])) {
            $converted['tax'] = $this->getTax($data);
            $converted['price'] = $this->getPrice($data, $converted['tax']['taxRate']);
        }

        unset(
          $data['id'],
          $data['product_number'],
          $data['product_name'],
          $data['stock'],
          $data['tax'],
          $data['price']
        );

        if (empty($data)) {
            $data = null;
        }
        $this->updateMainMapping($migrationContext, $context);

        return new ConvertStruct($converted, $data, $this->mainMapping['id']);
    }

    private function getTax(array $data): array
    {
        $taxRate = (float) $data['tax'];

        /**
         * Gets the tax uuid by the given tax rate
         */
        $taxUuid = $this->mappingService->getTaxUuid($this->connectionId, $taxRate, $this->context);

        /**
         * If no tax rate is found, create a new one
         */
        if ($taxUuid === null) {
            $mapping = $this->mappingService->createMapping(
                $this->connectionId,
                DefaultEntities::TAX,
                $data['id']
            );
            $taxUuid = $mapping['entityUuid'];
        }

        return [
            'id' => $taxUuid,
            'taxRate' => $taxRate,
            'name' => 'Own profile tax rate (' . $taxRate . ')',
        ];
    }

    private function getPrice(array $data, float $taxRate): array
    {
        $gross = (float) $data['price'] * (1 + $taxRate / 100);

        /**
         * Gets the currency uuid by the given iso code
         */
        $currencyUuid = $this->mappingService->getCurrencyUuid(
            $this->connectionId,
            'EUR',
            $this->context
        );

        if ($currencyUuid === null) {
            return [];
        }

        $price = [];
        $price[] = [
            'currencyId' => $currencyUuid,
            'gross' => $gross,
            'net' => (float) $data['price'],
            'linked' => true,
        ];

        return $price;
    }
}
```

If you don't know which properties or requirements your entity has in Shopware 6, you may check the corresponding `EntityDefinition`. For this example, look at the `ProductEntityDefinition` to know how to convert the data exactly.

To use this converter, you must register it in the `services.xml`:

```html
<service id="SwagMigrationOwnProfileExample\Profile\OwnProfile\Converter\ProductConverter">
    <argument type="service" id="SwagMigrationAssistant\Migration\Mapping\MappingService"/>
    <argument type="service" id="SwagMigrationAssistant\Migration\Logging\LoggingService"/>
    <tag name="shopware.migration.converter"/>
</service>
```

To write new entities, you have to create a new writer class, but for the product entity, you can use the `ProductWriter`:

```php
<?php declare(strict_types=1);

namespace SwagMigrationAssistant\Migration\Writer;

use SwagMigrationAssistant\Migration\DataSelection\DefaultEntities;

class ProductWriter extends AbstractWriter
{
    public function supports(): string
    {
        return DefaultEntities::PRODUCT;
    }
}
```

This writer will be called automatically as the `getEntityName` method of your `ProductDataSet` is compared with the return value of the `supports` method of the writer in the `WriterRegistry`. These values are identical, and so the writer will be used to write your product entities.

## Source

Check out this [GitHub repository](https://github.com/shopware/swag-docs-create-migration-profile) containing a full example source.

---

---
url: >-
  /docs/v6.6/products/extensions/migration-assistant/guides/creating-a-new-migration-profile.md
---

# Creating a New Migration Profile

If you want to migrate your data from a different source system than Shopware, create a new migration profile for the Migration Assistant. But if you want to convert your plugin data from a Shopware system to Shopware 6, look at this article on [Extending a Shopware Migration Profile](extending-a-shopware-migration-profile).

## Setup

First, it is required that you already have installed the [Migration Assistant](https://github.com/shopware/SwagMigrationAssistant) plugin in Shopware 6 and have created a demo source system database with a `product` table. To create the table, use this SQL statement:

```sql
CREATE TABLE product
(
  id int PRIMARY KEY NOT NULL AUTO_INCREMENT,
  product_number varchar(255) NOT NULL,
  price float NOT NULL,
  stock int NOT NULL,
  product_name varchar(255) NOT NULL,
  tax float NOT NULL
);
```

This table should simulate a simple third-party source system, which should be migrated in the following steps.

## Creating a profile

In the first step, you have to create a new profile for your source system:

```php
<?php declare(strict_types=1);

namespace SwagMigrationOwnProfileExample;

use SwagMigrationAssistant\Migration\Profile\ProfileInterface;

class OwnProfile implements ProfileInterface
{
    public const PROFILE_NAME = 'ownProfile';

    public const SOURCE_SYSTEM_NAME = 'MySourceSystem';

    public const SOURCE_SYSTEM_VERSION = '1.0';

    public const AUTHOR_NAME = 'shopware AG';

    public const ICON_PATH = '/swagmigrationassistant/static/img/migration-assistant-plugin.svg';

    public function getName(): string
    {
        return self::PROFILE_NAME;
    }

    public function getSourceSystemName(): string
    {
        return self::SOURCE_SYSTEM_NAME;
    }

    public function getVersion(): string
    {
        return self::SOURCE_SYSTEM_VERSION;
    }

    public function getAuthorName(): string
    {
        return self::AUTHOR_NAME;
    }

    public function getIconPath(): string
    {
        return self::ICON_PATH;
    }
}
```

The profile itself does not contain any logic and is used to bundle the executing classes. To use this profile, you have to register and tag it in the `service.xml` with `shopware.migration.profile`:

```html
<service id="SwagMigrationOwnProfileExample\Profile\OwnProfile\OwnProfile">
    <tag name="shopware.migration.profile"/>
</service>
```

## Creating a gateway

Next, you have to create a new gateway which supports your profile:

```php
<?php declare(strict_types=1);

namespace SwagMigrationOwnProfileExample\Profile\OwnProfile\Gateway;

use Shopware\Core\Framework\Context;
use SwagMigrationAssistant\Migration\EnvironmentInformation;
use SwagMigrationAssistant\Migration\Gateway\GatewayInterface;
use SwagMigrationAssistant\Migration\Gateway\Reader\ReaderRegistry;
use SwagMigrationAssistant\Migration\MigrationContextInterface;
use SwagMigrationAssistant\Migration\RequestStatusStruct;
use SwagMigrationAssistant\Profile\Shopware\Exception\DatabaseConnectionException;
use SwagMigrationAssistant\Profile\Shopware\Gateway\Connection\ConnectionFactoryInterface;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\OwnProfile;

class OwnLocaleGateway implements GatewayInterface
{
    public const GATEWAY_NAME = 'local';

    private ConnectionFactoryInterface $connectionFactory;

    private ReaderRegistry $readerRegistry;

    public function __construct(
        ReaderRegistry $readerRegistry,
        ConnectionFactoryInterface $connectionFactory
    ) {
        $this->readerRegistry = $readerRegistry;
        $this->connectionFactory = $connectionFactory;
    }

    public function getName(): string
    {
        return self::GATEWAY_NAME;
    }

    public function supports(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof OwnProfile;
    }

    public function getSnippetName(): string
    {
        return 'swag-migration.wizard.pages.connectionCreate.gateways.shopwareLocal';
    }

    /**
     * Reads the given entity type from via context from its connection and returns the data
     */
    public function read(MigrationContextInterface $migrationContext): array
    {
        // TODO: Implement read() method.
        return [];
    }

    public function readEnvironmentInformation(
        MigrationContextInterface $migrationContext,
        Context $context
    ): EnvironmentInformation {
        $connection = $this->connectionFactory->createDatabaseConnection($migrationContext);
        $profile = $migrationContext->getProfile();

        try {
            $connection->connect();
        } catch (\Exception $e) {
            $error = new DatabaseConnectionException();

            return new EnvironmentInformation(
                $profile->getSourceSystemName(),
                $profile->getVersion(),
                '-',
                [],
                [],
                new RequestStatusStruct($error->getErrorCode(), $error->getMessage())
            );
        }
        $connection->close();

        $totals = $this->readTotals($migrationContext, $context);

        return new EnvironmentInformation(
            $profile->getSourceSystemName(),
            $profile->getVersion(),
            'Example Host Name',
            $totals,
            [],
            new RequestStatusStruct(),
            false
        );
    }

    public function readTotals(MigrationContextInterface $migrationContext, Context $context): array
    {
        $readers = $this->readerRegistry->getReaderForTotal($migrationContext);

        $totals = [];
        foreach ($readers as $reader) {
            $total = $reader->readTotal($migrationContext);

            if ($total === null) {
                continue;
            }

            $totals[$total->getEntityName()] = $total;
        }

        return $totals;
    }
}
```

As you have seen above, the gateway uses the `ConnectionFactory` to test the connection to the source system. You can also implement your own way to check this, but using this factory is the simplest way for a gateway to connect to a local database. Like the profile, you have to register the new gateway in the `service.xml` and tag it with `shopware.migration.gateway`:

```html
<service id="SwagMigrationOwnProfileExample\Profile\OwnProfile\Gateway\OwnLocaleGateway">
    <argument type="service" id="SwagMigrationAssistant\Migration\Gateway\Reader\ReaderRegistry"/>
    <argument type="service" id="SwagMigrationAssistant\Profile\Shopware\Gateway\Connection\ConnectionFactory"/>
    <tag name="shopware.migration.gateway"/>
</service>
```

## Creating a credentials page

If you want to try your current progress in the Administration, you can select the profile and gateway in the migration wizard. If you try to go to the next page, there will be an error message because no credentials page was found. To create a new credentials page, you have to add an `index.js` for your new component into `Resources/app/administration/src/own-profile/profile`:

```javascript
import { Component } from 'src/core/shopware';
import template from './swag-migration-profile-ownProfile-local-credential-form.html.twig';

Component.register('swag-migration-profile-ownProfile-local-credential-form', {
    template,

    props: {
        credentials: {
            type: Object,
            default() {
                return {};
            }
        }
    },

    data() {
        return {
            inputCredentials: {
                dbHost: '',
                dbPort: '3306',
                dbUser: '',
                dbPassword: '',
                dbName: ''
            }
        };
    },

    watch: {
        credentials: {
            immediate: true,
            handler(newCredentials) {
                if (newCredentials === null) {
                    this.emitCredentials(this.inputCredentials);
                    return;
                }

                this.inputCredentials = newCredentials;
                this.emitOnChildRouteReadyChanged(
                    this.areCredentialsValid(this.inputCredentials)
                );
            }
        },

        inputCredentials: {
            deep: true,
            handler(newInputCredentials) {
                this.emitCredentials(newInputCredentials);
            }
        }
    },

    methods: {
        areCredentialsValid(newInputCredentials) {
            return (newInputCredentials.dbHost !== '' &&
                newInputCredentials.dbPort !== '' &&
                newInputCredentials.dbName !== '' &&
                newInputCredentials.dbUser !== '' &&
                newInputCredentials.dbPassword !== ''
            );
        },

        emitOnChildRouteReadyChanged(isReady) {
            this.$emit('onChildRouteReadyChanged', isReady);
        },

        emitCredentials(newInputCredentials) {
            this.$emit('onCredentialsChanged', newInputCredentials);
            this.emitOnChildRouteReadyChanged(
                this.areCredentialsValid(newInputCredentials)
            );
        },

        onKeyPressEnter() {
            this.$emit('onTriggerPrimaryClick');
        }
    }
});
```

As you can see above, currently, the template does not exist and you have to create this file: `swag-migration-profile-ownProfile-local-credential-form.html.twig`

```html
{% block own_profile_page_credentials %}
    <div class="swag-migration-wizard swag-migration-wizard-page-credentials"
         @keypress.enter="onKeyPressEnter">
        {% block own_profile_page_credentials_content %}
            <div class="swag-migration-wizard__content">
                {% block own_profile_page_credentials_information %}
                    <div class="swag-migration-wizard__content-information">
                        {% block own_profile_page_credentials_local_hint %}
                            {{ $tc('swag-migration.wizard.pages.credentials.shopware55.local.contentInformation') }}
                        {% endblock %}
                    </div>
                {% endblock %}

                {% block own_profile_page_credentials_credentials %}
                    <div class="swag-migration-wizard__form">
                        {% block own_profile_page_credentials_local_db_host_port_group %}
                            <sw-container columns="1fr 80px"
                                          gap="16px">
                                {% block own_profile_page_credentials_local_dbhost_field %}
                                    <sw-text-field v-autofocus
                                                   name="sw-field--dbHost"
                                                   :label="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbHostLabel')"
                                                   :placeholder="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbHostPlaceholder')"
                                                   v-model="inputCredentials.dbHost">
                                    </sw-text-field>
                                {% endblock %}

                                {% block own_profile_page_credentials_local_dbport_field %}
                                    <sw-field name="sw-field--dbPort"
                                              :label="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbPortLabel')"
                                              v-model="inputCredentials.dbPort">
                                    </sw-field>
                                {% endblock %}
                            </sw-container>
                        {% endblock %}

                        {% block own_profile_page_credentials_local_dbuser_field %}
                            <sw-field name="sw-field--dbUser"
                                      :label="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbUserLabel')"
                                      :placeholder="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbUserPlaceholder')"
                                      v-model="inputCredentials.dbUser">
                            </sw-field>
                        {% endblock %}

                        {% block own_profile_page_credentials_local_dbpassword_field %}
                            <sw-field name="sw-field--dbPassword"
                                      type="password"
                                      :label="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbPasswordLabel')"
                                      :placeholder="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbPasswordPlaceholder')"
                                      v-model="inputCredentials.dbPassword">
                            </sw-field>
                        {% endblock %}

                        {% block own_profile_page_credentials_local_dbname_field %}
                            <sw-field name="sw-field--dbName"
                                      :label="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbNameLabel')"
                                      :placeholder="$tc('swag-migration.wizard.pages.credentials.shopware55.local.dbNamePlaceholder')"
                                      v-model="inputCredentials.dbName">
                            </sw-field>
                        {% endblock %}
                    </div>
                {% endblock %}
            </div>
        {% endblock %}
    </div>
{% endblock %}
```

Note that the component name isn't random and consists of:

1. The prefix: `swag-migration-profile-`
2. The name of the profile
3. The name of the gateway
4. The suffix: `-credential-form`

To see your credentials page, you have to register this component in your `main.js`:

```javascript
import './own-profile/profile';
```

## Creating a dataSet and dataSelection

Now the credential page is loaded in the Administration and the connection check will succeed. But there is no data selection if you open the data selection table. To add an entry to this table, you have to create a `ProductDataSet` first:

```php
<?php declare(strict_types=1);

namespace SwagMigrationOwnProfileExample\Profile\OwnProfile\DataSelection\DataSet;

use SwagMigrationAssistant\Migration\DataSelection\DataSet\DataSet;
use SwagMigrationAssistant\Migration\MigrationContextInterface;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\OwnProfile;

class ProductDataSet extends DataSet
{
    /**
     * Returns the entity identifier of this DataSet
     */
    public static function getEntity(): string
    {
        return 'product';
    }

    /**
     * Supports only an OwnProfile
     */
    public function supports(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof OwnProfile;
    }
}
```

Now you have to use this `ProductDataSet` in the new `ProductDataSelection`:

```php
<?php declare(strict_types=1);

namespace SwagMigrationOwnProfileExample\Profile\OwnProfile\DataSelection;

use SwagMigrationAssistant\Migration\DataSelection\DataSelectionInterface;
use SwagMigrationAssistant\Migration\DataSelection\DataSelectionStruct;
use SwagMigrationAssistant\Migration\MigrationContextInterface;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\DataSelection\DataSet\ProductDataSet;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\OwnProfile;

class ProductDataSelection implements DataSelectionInterface
{
    /**
     * Identifier of this DataSelection
     */
    public const IDENTIFIER = 'products';

    /**
     * Supports only an OwnProfile
     */
    public function supports(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof OwnProfile;
    }

    public function getData(): DataSelectionStruct
    {
        return new DataSelectionStruct(
            self::IDENTIFIER,
            $this->getDataSets(),
            $this->getDataSetsRequiredForCount(),
            /*
             * Snippet of the original ProductDataSelection, if you
             * want to use your own title, you have to create a new snippet
             */
            'swag-migration.index.selectDataCard.dataSelection.products',
            100
        );
    }

    /**
     * Returns all DataSets, which should be migrated with this DataSelection
     */
    public function getDataSets(): array
    {
        return [
            new ProductDataSet()
        ];
    }

    public function getDataSetsRequiredForCount(): array
    {
        return $this->getDataSets();
    }
}
```

::: info
The order in the `getDataSets` array is important as it determines the order in which the entities are processed. Because of that, the manufacturers, for example, have to be positioned before the products so that the products can use those later on.
:::

To see the created `ProductDataSelection` in the Administration, you have to register it both in the `services.xml` and tag them with `shopware.migration.data_selection` and `shopware.migration.data_set`:

```html
<service id="SwagMigrationOwnProfileExample\Profile\OwnProfile\DataSelection\ProductDataSelection">
    <tag name="shopware.migration.data_selection"/>
</service>

<service id="SwagMigrationOwnProfileExample\Profile\OwnProfile\DataSelection\DataSet\ProductDataSet">
    <tag name="shopware.migration.data_set"/>
</service>
```

## Creating a product gateway reader

Currently, you can see the `DataSelection` in the Administration, but if you select it and start a migration, no product will be migrated. That is because the gateway `read` function isn't implemented yet. But before you can implement this function, you have to create a new `ProductReader` first:

```php
<?php declare(strict_types=1);

namespace SwagMigrationOwnProfileExample\Profile\OwnProfile\Gateway\Reader;

use Doctrine\DBAL\Driver\ResultStatement;
use SwagMigrationAssistant\Migration\MigrationContextInterface;
use SwagMigrationAssistant\Migration\TotalStruct;
use SwagMigrationAssistant\Profile\Shopware\Gateway\Local\Reader\AbstractReader;
use SwagMigrationAssistant\Profile\Shopware\Gateway\Local\ShopwareLocalGateway;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\DataSelection\DataSet\ProductDataSet;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\OwnProfile;

class ProductReader extends AbstractReader
{
    /**
     * Supports only an OwnProfile and the ProductDataSet
     */
    public function supports(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof OwnProfile
            && $migrationContext->getDataSet()::getEntity() === ProductDataSet::getEntity();
    }

    /**
     * Supports only an OwnProfile and the ProductDataSet for totals
     */
    public function supportsTotal(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof OwnProfile
            && $migrationContext->getGateway()->getName() === ShopwareLocalGateway::GATEWAY_NAME;
    }

    /**
     * Creates a database connection and sets the connection class variable
     */
    protected function setConnection(MigrationContextInterface $migrationContext): void
    {
        $this->connection = $this->connectionFactory->createDatabaseConnection($migrationContext);
    }

    public function readTotal(MigrationContextInterface $migrationContext): ?TotalStruct
    {
        $this->setConnection($migrationContext);

        $query = $this->connection->createQueryBuilder()
            ->select('COUNT(*)')
            ->from('product')
            ->execute();

        $total = 0;
        if ($query instanceof ResultStatement) {
            $total = (int) $query->fetchColumn();
        }

        return new TotalStruct(ProductDataSet::getEntity(), $total);
    }

    /**
     * Fetches all entities out of the product table with the given limit
     */
    public function read(MigrationContextInterface $migrationContext, array $params = []): array
    {
        $this->setConnection($migrationContext);

        $query = $this->connection->createQueryBuilder();
        $query->from('product');
        $query->addSelect('*');

        $query->setFirstResult($migrationContext->getOffset());
        $query->setMaxResults($migrationContext->getLimit());

        return $query->execute()->fetchAll(\PDO::FETCH_ASSOC);
    }
}
```

Then you have to register this in `services.xml` and tag it with `shopware.migration.reader`:

```html
<service id="SwagMigrationOwnProfileExample\Profile\OwnProfile\Gateway\Reader\ProductReader"
    parent="SwagMigrationAssistant\Profile\Shopware\Gateway\Local\Reader\AbstractReader">
    <argument type="service" id="SwagMigrationAssistant\Profile\Shopware\Gateway\Connection\ConnectionFactory"/>
    <tag name="shopware.migration.reader"/>
</service>
```

Once the `ProductReader` is created and registered, you can use it in the `read` method of the `OwnLocaleGateway`:

```php
<?php declare(strict_types=1);

namespace SwagMigrationOwnProfileExample\Profile\OwnProfile\Gateway;

use Shopware\Core\Framework\Context;
use SwagMigrationAssistant\Migration\EnvironmentInformation;
use SwagMigrationAssistant\Migration\Gateway\GatewayInterface;
use SwagMigrationAssistant\Migration\Gateway\Reader\ReaderRegistry;
use SwagMigrationAssistant\Migration\MigrationContextInterface;
use SwagMigrationAssistant\Migration\RequestStatusStruct;
use SwagMigrationAssistant\Profile\Shopware\Exception\DatabaseConnectionException;
use SwagMigrationAssistant\Profile\Shopware\Gateway\Connection\ConnectionFactoryInterface;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\OwnProfile;

class OwnLocaleGateway implements GatewayInterface
{
    public const GATEWAY_NAME = 'local';

    private ConnectionFactoryInterface $connectionFactory;

    private ReaderRegistry $readerRegistry;

    public function __construct(
        ReaderRegistry $readerRegistry,
        ConnectionFactoryInterface $connectionFactory
    ) {
        $this->readerRegistry = $readerRegistry;
        $this->connectionFactory = $connectionFactory;
    }

    public function getName(): string
    {
        return self::GATEWAY_NAME;
    }

    public function supports(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof OwnProfile;
    }

    public function getSnippetName(): string
    {
        return 'swag-migration.wizard.pages.connectionCreate.gateways.shopwareLocal';
    }

    public function read(MigrationContextInterface $migrationContext): array
    {
        $reader = $this->readerRegistry->getReader($migrationContext);

        return $reader->read($migrationContext);
    }

    public function readEnvironmentInformation(
        MigrationContextInterface $migrationContext,
        Context $context
    ): EnvironmentInformation {
        $connection = $this->connectionFactory->createDatabaseConnection($migrationContext);
        $profile = $migrationContext->getProfile();

        try {
            $connection->connect();
        } catch (\Exception $e) {
            $error = new DatabaseConnectionException();

            return new EnvironmentInformation(
                $profile->getSourceSystemName(),
                $profile->getVersion(),
                '-',
                [],
                [],
                new RequestStatusStruct($error->getErrorCode(), $error->getMessage())
            );
        }
        $connection->close();

        $totals = $this->readTotals($migrationContext, $context);

        return new EnvironmentInformation(
            $profile->getSourceSystemName(),
            $profile->getVersion(),
            'Example Host Name',
            $totals,
            [],
            new RequestStatusStruct(),
            false
        );
    }

    public function readTotals(MigrationContextInterface $migrationContext, Context $context): array
    {
        $readers = $this->readerRegistry->getReaderForTotal($migrationContext);

        $totals = [];
        foreach ($readers as $reader) {
            $total = $reader->readTotal($migrationContext);

            if ($total === null) {
                continue;
            }

            $totals[$total->getEntityName()] = $total;
        }

        return $totals;
    }
}
```

## Creating a converter

By using the gateway reader, you fetch all products but don't use this data yet. In this step, you implement the logic of the converter:

```php
<?php declare(strict_types=1);

namespace SwagMigrationOwnProfileExample\Profile\OwnProfile\Converter;

use Shopware\Core\Framework\Context;
use SwagMigrationAssistant\Migration\Converter\ConvertStruct;
use SwagMigrationAssistant\Migration\DataSelection\DefaultEntities;
use SwagMigrationAssistant\Migration\MigrationContextInterface;
use SwagMigrationAssistant\Profile\Shopware\Converter\ShopwareConverter;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\DataSelection\DataSet\ProductDataSet;
use SwagMigrationOwnProfileExample\Profile\OwnProfile\OwnProfile;

class ProductConverter extends ShopwareConverter
{
    private string $connectionId;

    private Context $context;

    public function getSourceIdentifier(array $data): string
    {
        return $data['id'];
    }

    /**
     * Supports only an OwnProfile and the ProductDataSet
     */
    public function supports(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof OwnProfile &&
            $migrationContext->getDataSet()::getEntity() === ProductDataSet::getEntity();
    }

    /**
     * Writes the created mapping
     */
    public function writeMapping(Context $context): void
    {
        $this->mappingService->writeMapping($context);
    }

    public function convert(array $data, Context $context, MigrationContextInterface $migrationContext): ConvertStruct
    {
        $this->generateChecksum($data);
        $this->connectionId = $migrationContext->getConnection()->getId();
        $this->context = $context;

        /**
         * Gets the product uuid out of the mapping table or creates a new one
         */
        $this->mainMapping = $this->mappingService->getOrCreateMapping(
            $migrationContext->getConnection()->getId(),
            ProductDataSet::getEntity(),
            $data['id'],
            $context,
            $this->checksum
        );

        $converted['id'] = $this->mainMapping['entityUuid'];
        $this->convertValue($converted, 'productNumber', $data, 'product_number');
        $this->convertValue($converted, 'name', $data, 'product_name');
        $this->convertValue($converted, 'stock', $data, 'stock', self::TYPE_INTEGER);

        if (isset($data['tax'])) {
            $converted['tax'] = $this->getTax($data);
            $converted['price'] = $this->getPrice($data, $converted['tax']['taxRate']);
        }

        unset(
          $data['id'],
          $data['product_number'],
          $data['product_name'],
          $data['stock'],
          $data['tax'],
          $data['price']
        );

        if (empty($data)) {
            $data = null;
        }
        $this->updateMainMapping($migrationContext, $context);

        return new ConvertStruct($converted, $data, $this->mainMapping['id']);
    }

    private function getTax(array $data): array
    {
        $taxRate = (float) $data['tax'];

        /**
         * Gets the tax uuid by the given tax rate
         */
        $taxUuid = $this->mappingService->getTaxUuid($this->connectionId, $taxRate, $this->context);

        /**
         * If no tax rate is found, create a new one
         */
        if ($taxUuid === null) {
            $mapping = $this->mappingService->createMapping(
                $this->connectionId,
                DefaultEntities::TAX,
                $data['id']
            );
            $taxUuid = $mapping['entityUuid'];
        }

        return [
            'id' => $taxUuid,
            'taxRate' => $taxRate,
            'name' => 'Own profile tax rate (' . $taxRate . ')',
        ];
    }

    private function getPrice(array $data, float $taxRate): array
    {
        $gross = (float) $data['price'] * (1 + $taxRate / 100);

        /**
         * Gets the currency uuid by the given iso code
         */
        $currencyUuid = $this->mappingService->getCurrencyUuid(
            $this->connectionId,
            'EUR',
            $this->context
        );

        if ($currencyUuid === null) {
            return [];
        }

        $price = [];
        $price[] = [
            'currencyId' => $currencyUuid,
            'gross' => $gross,
            'net' => (float) $data['price'],
            'linked' => true,
        ];

        return $price;
    }
}
```

If you don't know which properties or requirements your entity has in Shopware 6, you may check the corresponding `EntityDefinition`. For this example, look at the `ProductEntityDefinition` to know how to convert the data exactly.

To use this converter, you must register it in the `services.xml`:

```html
<service id="SwagMigrationOwnProfileExample\Profile\OwnProfile\Converter\ProductConverter">
    <argument type="service" id="SwagMigrationAssistant\Migration\Mapping\MappingService"/>
    <argument type="service" id="SwagMigrationAssistant\Migration\Logging\LoggingService"/>
    <tag name="shopware.migration.converter"/>
</service>
```

To write new entities, you have to create a new writer class, but for the product entity, you can use the `ProductWriter`:

```php
<?php declare(strict_types=1);

namespace SwagMigrationAssistant\Migration\Writer;

use SwagMigrationAssistant\Migration\DataSelection\DefaultEntities;

class ProductWriter extends AbstractWriter
{
    public function supports(): string
    {
        return DefaultEntities::PRODUCT;
    }
}
```

This writer will be called automatically as the `getEntityName` method of your `ProductDataSet` is compared with the return value of the `supports` method of the writer in the `WriterRegistry`. These values are identical, and so the writer will be used to write your product entities.

## Source

Check out this [GitHub repository](https://github.com/shopware/swag-docs-create-migration-profile) containing a full example source.

---

---
url: /docs/v6.6/products/sales-agent/users.md
---

# Creating a user and set restrictions

You can create a user by sending a `POST` request to the `/api/user` endpoint. The `x-api-key` header is required and can be set in the environment (`API_AUTH_SECRET_KEY`).

```bash
curl -XPOST -H 'x-api-key: <secret>' -H "Content-type: application/json" -d '{
    "name": <name>,
    "email": <email>,
    "id": <id>,
    "password": <password>
}' '<sales_agent_instance_url>/api/user'
```

To restrict a user to viewing only specific customers, you can send a `POST` request to the `/api/entity-restriction` endpoint.

```bash
curl -XPOST -H 'x-api-key: <secret>' -H "Content-type: application/json" -d '{
    "entity": "customer",
    "email": <user_email>,
    "criteria": {
      "filter": [{
        "field": "lastName",
        "type": "equals",
        "value": "Doe"
      }]
    }
}' '<sales_agent_instance_url>/api/entity-restriction'
```

In this example, the user with the email `<user_email>` will only be able to see customers with the last name "Doe".
The criteria object supports the same fields as the shopware API. You can find more information about the criteria object in the [documentation](https://developer.shopware.com/docs/guides/integrations-api/general-concepts/search-criteria.html).

Further documentation of the available endpoints can be found in the [API documentation](https://shopware.stoplight.io/docs/swag-sales-agent/).

---

---
url: /docs/guides/plugins/plugins/framework/extension/creating-custom-extension.md
---

# Creating Custom Extension Points

## Overview

While Shopware provides many built-in extension points, you may need to create custom extension points for your specific use cases. This guide will walk you through creating custom extension points that follow Shopware's extension system patterns.

## Extension Class Structure

### Basic Extension Class

All extension points must extend the base `Extension` class and define a typed result:

```php
<?php declare(strict_types=1);

namespace MyPlugin\Extension;

use Shopware\Core\Framework\Extensions\Extension;
use Shopware\Core\Framework\Log\Package;

/**
 * @extends Extension<MyResultType>
 */
#[Package('my-plugin')]
final class MyCustomExtension extends Extension
{
    public const NAME = 'my-plugin.custom-extension';

    public function __construct(
        /**
         * @public
         * @description Input data for processing
         */
        public readonly array $inputData,

        /**
         * @public
         * @description Context for the operation
         */
        public readonly Context $context
    ) {
    }
}
```

### Key Components

1. **Generic Type**: `@extends Extension<ResultType>` defines the return type
2. **NAME Constant**: Unique identifier for the extension
3. **Public Properties**: Input parameters marked with `@public` for API documentation
4. **Package Attribute**: Identifies the package/plugin

## Example: Custom Product Filter Extension

Let's create a custom extension point for filtering products based on custom business logic:

### 1. Define the Extension Class

```php
<?php declare(strict_types=1);

namespace MyPlugin\Extension;

use Shopware\Core\Content\Product\ProductCollection;
use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\Framework\DataAbstractionLayer\Search\EntitySearchResult;
use Shopware\Core\Framework\Extensions\Extension;
use Shopware\Core\Framework\Log\Package;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

/**
 * @extends Extension<EntitySearchResult<ProductCollection>>
 */
#[Package('my-plugin')]
final class CustomProductFilterExtension extends Extension
{
    public const NAME = 'my-plugin.product-filter';

    public function __construct(
        /**
         * @public
         * @description The search criteria for products
         */
        public readonly Criteria $criteria,

        /**
         * @public
         * @description The sales channel context
         */
        public readonly SalesChannelContext $context,

        /**
         * @public
         * @description Custom filter parameters
         */
        public readonly array $filterParams
    ) {
    }
}
```

### 2. Create the Service that Dispatches the Extension

```php
<?php declare(strict_types=1);

namespace MyPlugin\Service;

use MyPlugin\Extension\CustomProductFilterExtension;
use Shopware\Core\Content\Product\ProductCollection;
use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\DataAbstractionLayer\EntityRepository;
use Shopware\Core\Framework\DataAbstractionLayer\Search\Criteria;
use Shopware\Core\Framework\DataAbstractionLayer\Search\EntitySearchResult;
use Shopware\Core\Framework\Extensions\ExtensionDispatcher;
use Shopware\Core\Framework\Log\Package;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

#[Package('my-plugin')]
class CustomProductService
{
    public function __construct(
        private readonly ExtensionDispatcher $extensionDispatcher,
        private readonly EntityRepository $productRepository
    ) {
    }

    public function filterProducts(
        Criteria $criteria,
        SalesChannelContext $context,
        array $filterParams = []
    ): EntitySearchResult {
        $extension = new CustomProductFilterExtension(
            $criteria,
            $context,
            $filterParams
        );

        return $this->extensionDispatcher->publish(
            CustomProductFilterExtension::NAME,
            $extension,
            function() use ($criteria, $context) {
                // Default implementation
                return $this->productRepository->search($criteria, $context->getContext());
            }
        );
    }
}
```

### 3. Create an Event Subscriber

```php
<?php declare(strict_types=1);

namespace MyPlugin\Subscriber;

use MyPlugin\Extension\CustomProductFilterExtension;
use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class CustomProductFilterSubscriber implements EventSubscriberInterface
{
    public function __construct(
        private readonly ExternalApiService $apiService,
        private readonly ProductFilterService $filterService
    ) {
    }

    public static function getSubscribedEvents(): array
    {
        return [
            'my-plugin.product-filter.pre' => 'onProductFilter',
        ];
    }

    public function onProductFilter(CustomProductFilterExtension $event): void
    {
        // Check if we should apply custom filtering
        if (!$this->shouldApplyCustomFilter($event->filterParams)) {
            return;
        }

        // Get filtered product IDs from external API
        $filteredIds = $this->apiService->getFilteredProductIds(
            $event->criteria,
            $event->context,
            $event->filterParams
        );

        if (empty($filteredIds)) {
            // No products match the filter
            $event->result = new EntitySearchResult(
                'product',
                0,
                new ProductCollection(),
                null,
                $event->criteria,
                $event->context->getContext()
            );
            $event->stopPropagation();
            return;
        }

        // Create new criteria with filtered IDs
        $newCriteria = clone $event->criteria;
        $newCriteria->setIds($filteredIds);

        // Apply additional filtering
        $filteredProducts = $this->filterService->applyBusinessRules(
            $newCriteria,
            $event->context
        );

        $event->result = $filteredProducts;
        $event->stopPropagation();
    }

    private function shouldApplyCustomFilter(array $filterParams): bool
    {
        return isset($filterParams['custom_filter']) && $filterParams['custom_filter'] === true;
    }
}
```

### 4. Register Services

```php
// services.php
$services->set(MyPlugin\Service\CustomProductService::class)
    ->args([
        service(Shopware\Core\Framework\Extensions\ExtensionDispatcher::class),
        service('product.repository'),
    ]);

$services->set(MyPlugin\Subscriber\CustomProductFilterSubscriber::class)
    ->args([
        service(MyPlugin\Service\ExternalApiService::class),
        service(MyPlugin\Service\ProductFilterService::class),
    ])
    ->tag('kernel.event_subscriber');
```

## Advanced Extension Patterns

### 1. Conditional Extension Execution

```php
public function onExtension(MyExtension $event): void
{
    // Only execute under certain conditions
    if (!$this->shouldExecute($event)) {
        return;
    }

    $event->result = $this->customImplementation($event);
    $event->stopPropagation();
}

private function shouldExecute(MyExtension $event): bool
{
    return $event->context->getSalesChannelId() === 'special-sales-channel';
}
```

### 2. Extension with Error Handling

```php
public function onExtension(MyExtension $event): void
{
    try {
        $event->result = $this->riskyOperation($event);
        $event->stopPropagation();
    } catch (\Exception $e) {
        // Log the error but don't stop the extension
        $this->logger->error('Custom extension failed', [
            'error' => $e->getMessage(),
            'extension' => get_class($event)
        ]);

        // The extension system will handle the error
        // and potentially dispatch error events
    }
}
```

### 3. Extension with Data Enrichment

```php
public function onExtension(MyExtension $event): void
{
    // Don't replace the result, just enrich it
    if ($event->result !== null) {
        $enrichedResult = $this->enrichResult($event->result, $event);
        $event->result = $enrichedResult;
    }
}

private function enrichResult($result, MyExtension $event)
{
    // Add custom data to the result
    $result->addExtension('customData', new CustomStruct([
        'processedAt' => new \DateTime(),
        'context' => $event->context->getSalesChannelId()
    ]));

    return $result;
}
```

### 4. Multi-Phase Extension

```php
public static function getSubscribedEvents(): array
{
    return [
        'my-extension.pre' => 'onPrePhase',
        'my-extension.post' => 'onPostPhase',
        'my-extension.error' => 'onErrorPhase',
    ];
}

public function onPrePhase(MyExtension $event): void
{
    // Prepare data before default implementation
    $event->addExtension('preparedData', $this->prepareData($event));
}

public function onPostPhase(MyExtension $event): void
{
    // Process result after default implementation
    if ($event->result !== null) {
        $event->result = $this->postProcess($event->result, $event);
    }
}

public function onErrorPhase(MyExtension $event): void
{
    // Handle errors gracefully
    if ($event->exception !== null) {
        $event->result = $this->fallbackImplementation($event);
    }
}
```

## Extension Lifecycle Management

### Pre-Phase Extensions

Use `.pre` events to:

* Validate input data
* Modify criteria or parameters
* Replace default implementation entirely

### Post-Phase Extensions

Use `.post` events to:

* Enrich results
* Log completion
* Trigger follow-up actions

### Error-Phase Extensions

Use `.error` events to:

* Provide fallback implementations
* Log errors
* Recover from failures

## Best Practices

### 1. Naming Conventions

* Use descriptive, domain-specific names
* Follow the pattern: `{plugin}.{domain}.{action}`
* Use kebab-case for event names

### 2. Type Safety

* Always define generic types for extension points
* Use proper type hints for parameters
* Validate input data in constructors

### 3. Documentation

* Document all public properties with `@public` and `@description`
* Provide clear examples in docblocks
* Include usage examples in plugin documentation

### 4. Error Handling

* Use try-catch blocks for risky operations
* Provide meaningful error messages
* Consider fallback implementations

### 5. Performance

* Avoid expensive operations in Extensions
* Cache results when appropriate
* Use lazy loading for heavy dependencies

### 6. Testing

* Write unit tests for extension point classes
* Test event subscribers thoroughly
* Mock external dependencies

## Example: Complete Plugin with Custom Extension Point

Here's a complete example of a plugin that creates and uses a custom extension point:

```php
// 1. Extension class
final class ProductRecommendationExtension extends Extension
{
    public const NAME = 'my-plugin.product-recommendation';

    public function __construct(
        public readonly ProductEntity $product,
        public readonly SalesChannelContext $context,
        public readonly int $limit = 5
    ) {}
}

// 2. Service that uses the extension
class ProductRecommendationService
{
    public function getRecommendations(ProductEntity $product, SalesChannelContext $context): ProductCollection
    {
        $extension = new ProductRecommendationExtension($product, $context);

        return $this->extensionDispatcher->publish(
            ProductRecommendationExtension::NAME,
            $extension,
            function() use ($product, $context) {
                // Default recommendation logic
                return $this->getDefaultRecommendations($product, $context);
            }
        );
    }
}

// 3. Subscriber that provides custom logic
class ProductRecommendationSubscriber implements EventSubscriberInterface
{
    public static function getSubscribedEvents(): array
    {
        return [
            'my-plugin.product-recommendation.pre' => 'onGetRecommendations',
        ];
    }

    public function onGetRecommendations(ProductRecommendationExtension $event): void
    {
        // Custom AI-powered recommendations
        $recommendations = $this->aiService->getRecommendations(
            $event->product,
            $event->context,
            $event->limit
        );

        $event->result = $recommendations;
        $event->stopPropagation();
    }
}
```

This comprehensive guide should help you create custom extension points that integrate seamlessly with Shopware's extension system.

---

---
url: /docs/resources/references/adr/2020-11-06-creating-events.md
---

# Creating events in Shopware

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2020-11-06-creating-events.md)
:::

## Context

Events throughout Shopware are quite inconsistent.
It is not defined which data it must or can contain.
This mainly depends on the domain where the events are thrown.

## Decision

Developers should always have access to the right context of the current request,
at least the `Shopware\Core\Framework\Context` should be present as property in events.
If the event is thrown in a SalesChannel context,
the `Shopware\Core\System\SalesChannel\SalesChannelContext` should also be present as property.

## Consequences

From now on every new event must implement the `Shopware\Core\Framework\Event\ShopwareEvent` interface.
If a `Shopware\Core\System\SalesChannel\SalesChannelContext` is also available,
the `Shopware\Core\Framework\Event\ShopwareSalesChannelEvent` interface must be implemented instead.

---

---
url: /docs/v6.5/resources/references/adr/2020-11-06-creating-events.md
---

# Creating events in Shopware

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2020-11-06-creating-events.md)
:::

## Context

Events throughout Shopware are quite inconsistent.
It is not defined which data it must or can contain.
This mainly depends on the domain where the events are thrown.

## Decision

Developers should always have access to the right context of the current request,
at least the `Shopware\Core\Framework\Context` should be present as property in events.
If the event is thrown in a SalesChannel context,
the `Shopware\Core\System\SalesChannel\SalesChannelContext` should also be present as property.

## Consequences

From now on every new event must implement the `Shopware\Core\Framework\Event\ShopwareEvent` interface.
If a `Shopware\Core\System\SalesChannel\SalesChannelContext` is also available,
the `Shopware\Core\Framework\Event\ShopwareSalesChannelEvent` interface must be implemented instead.

---

---
url: /docs/v6.6/resources/references/adr/2020-11-06-creating-events.md
---

# Creating events in Shopware

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2020-11-06-creating-events.md)
:::

## Context

Events throughout Shopware are quite inconsistent.
It is not defined which data it must or can contain.
This mainly depends on the domain where the events are thrown.

## Decision

Developers should always have access to the right context of the current request,
at least the `Shopware\Core\Framework\Context` should be present as property in events.
If the event is thrown in a SalesChannel context,
the `Shopware\Core\System\SalesChannel\SalesChannelContext` should also be present as property.

## Consequences

From now on every new event must implement the `Shopware\Core\Framework\Event\ShopwareEvent` interface.
If a `Shopware\Core\System\SalesChannel\SalesChannelContext` is also available,
the `Shopware\Core\Framework\Event\ShopwareSalesChannelEvent` interface must be implemented instead.

---

---
url: >-
  /docs/products/extensions/b2b-components/employee-management/guides/creating-own-permissions-via-plugin.md
---

# Creating own permissions via plugin

This article explains how to create custom permissions using a plugin.

To create custom permissions, you will utilize the event subscriber concept in Symfony.
Create a new class called `PermissionCollectorSubscriber` that implements the `EventSubscriberInterface`:

```php
<?php declare(strict_types=1);

use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class PermissionCollectorSubscriber implements EventSubscriberInterface
{
    public const OWN_ENTITY_GROUP = 'own_entity';

    // Here you define your custom permissions as constants
    public const OWN_ENTITY_READ = 'own_entity.read';
    
    public const OWN_ENTITY_EDIT = 'own_entity.edit';
    
    public const OWN_ENTITY_CREATE = 'own_entity.create';
    
    public const OWN_ENTITY_DELETE = 'own_entity.delete';

    public static function getSubscribedEvents(): array
    {
        return [
            PermissionCollectorEvent::NAME => [ 'onAddOwnPermissions' , 1000 ]
        ];
    }

    // This method is called when the PermissionCollectorEvent is triggered
    public function onAddOwnPermissions(PermissionCollectorEvent $event): void
    {
        $collection = $event->getCollection();

        // Here you add your custom permissions to the permission collection
        $collection->addPermission(self::EMPLOYEE_READ, self::OWN_ENTITY_GROUP, []);
        $collection->addPermission(self::EMPLOYEE_EDIT, self::OWN_ENTITY_GROUP, [ self::EMPLOYEE_READ ]);
        $collection->addPermission(self::EMPLOYEE_CREATE, self::OWN_ENTITY_GROUP, [ self::EMPLOYEE_READ, self::EMPLOYEE_EDIT ]);
        $collection->addPermission(self::EMPLOYEE_DELETE, self::OWN_ENTITY_GROUP, [ self::EMPLOYEE_READ, self::EMPLOYEE_EDIT ]);
    }
}
```

The `PermissionCollector` collects the permissions of all subscribers and then passes them to the storefront, where they can be attached to the role by the user.
If you want to check in the template if the user has this permission, the Twig function `isB2bAllowed` can be used:

```twig
{% sw_extends '@Storefront/storefront/page/checkout/checkout-item.html.twig' %}

{{ parent() }}

{% if isB2bAllowed(constant('PermissionCollectorSubscriber::EMPLOYEE_READ')) %}
...
{% endif  %}
```

In controllers, the checking of permissions must happen via the employee's role:

```php
<?php declare(strict_types=1);
public function employeeList(Request $request, SalesChannelContext $context): Response
{
    if (!$context->getCustomer()->getEmployee()->getRole()->can(PermissionCollectorSubscriber::EMPLOYEE_READ)) {
        throw new PermissionDeniedException();
    }
...
}
```

---

---
url: >-
  /docs/v6.5/products/extensions/b2b-components/employee-management/guides/creating-own-permissions-via-plugin.md
---

# Creating own permissions via plugin

This article explains how to create custom permissions using a plugin.

To create custom permissions, you will utilize the event subscriber concept in Symfony.
Create a new class called `PermissionCollectorSubscriber` that implements the `EventSubscriberInterface`:

```php
<?php declare(strict_types=1);

use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class PermissionCollectorSubscriber implements EventSubscriberInterface
{
    public const OWN_ENTITY_GROUP = 'own_entity';

    // Here you define your custom permissions as constants
    public const OWN_ENTITY_READ = 'own_entity.read';
    
    public const OWN_ENTITY_EDIT = 'own_entity.edit';
    
    public const OWN_ENTITY_CREATE = 'own_entity.create';
    
    public const OWN_ENTITY_DELETE = 'own_entity.delete';

    public static function getSubscribedEvents(): array
    {
        return [
            PermissionCollectorEvent::NAME => [ 'onAddOwnPermissions' , 1000 ]
        ];
    }

    // This method is called when the PermissionCollectorEvent is triggered
    public function onAddOwnPermissions(PermissionCollectorEvent $event): void
    {
        $collection = $event->getCollection();

        // Here you add your custom permissions to the permission collection
        $collection->addPermission(self::EMPLOYEE_READ, self::OWN_ENTITY_GROUP, []);
        $collection->addPermission(self::EMPLOYEE_EDIT, self::OWN_ENTITY_GROUP, [ self::EMPLOYEE_READ ]);
        $collection->addPermission(self::EMPLOYEE_CREATE, self::OWN_ENTITY_GROUP, [ self::EMPLOYEE_READ, self::EMPLOYEE_EDIT ]);
        $collection->addPermission(self::EMPLOYEE_DELETE, self::OWN_ENTITY_GROUP, [ self::EMPLOYEE_READ, self::EMPLOYEE_EDIT ]);
    }
}
```

The `PermissionCollector` collects the permissions of all subscribers and then passes them to the storefront, where they can be attached to the role by the user.
If you want to check in the template if the user has this permission, the Twig function `isB2bAllowed` can be used:

```twig
{% sw_extends '@Storefront/storefront/page/checkout/checkout-item.html.twig' %}

{{ parent() }}

{% if isB2bAllowed(constant('PermissionCollectorSubscriber::EMPLOYEE_READ')) %}
...
{% endif  %}
```

In controllers, the checking of permissions must happen via the employee's role:

```php
<?php declare(strict_types=1);
public function employeeList(Request $request, SalesChannelContext $context): Response
{
    if (!$context->getCustomer()->getEmployee()->getRole()->can(PermissionCollectorSubscriber::EMPLOYEE_READ)) {
        throw new PermissionDeniedException();
    }
...
}
```

---

---
url: >-
  /docs/v6.6/products/extensions/b2b-components/employee-management/guides/creating-own-permissions-via-plugin.md
---

# Creating own permissions via plugin

This article explains how to create custom permissions using a plugin.

To create custom permissions, you will utilize the event subscriber concept in Symfony.
Create a new class called `PermissionCollectorSubscriber` that implements the `EventSubscriberInterface`:

```php
<?php declare(strict_types=1);

use Symfony\Component\EventDispatcher\EventSubscriberInterface;

class PermissionCollectorSubscriber implements EventSubscriberInterface
{
    public const OWN_ENTITY_GROUP = 'own_entity';

    // Here you define your custom permissions as constants
    public const OWN_ENTITY_READ = 'own_entity.read';
    
    public const OWN_ENTITY_EDIT = 'own_entity.edit';
    
    public const OWN_ENTITY_CREATE = 'own_entity.create';
    
    public const OWN_ENTITY_DELETE = 'own_entity.delete';

    public static function getSubscribedEvents(): array
    {
        return [
            PermissionCollectorEvent::NAME => [ 'onAddOwnPermissions' , 1000 ]
        ];
    }

    // This method is called when the PermissionCollectorEvent is triggered
    public function onAddOwnPermissions(PermissionCollectorEvent $event): void
    {
        $collection = $event->getCollection();

        // Here you add your custom permissions to the permission collection
        $collection->addPermission(self::EMPLOYEE_READ, self::OWN_ENTITY_GROUP, []);
        $collection->addPermission(self::EMPLOYEE_EDIT, self::OWN_ENTITY_GROUP, [ self::EMPLOYEE_READ ]);
        $collection->addPermission(self::EMPLOYEE_CREATE, self::OWN_ENTITY_GROUP, [ self::EMPLOYEE_READ, self::EMPLOYEE_EDIT ]);
        $collection->addPermission(self::EMPLOYEE_DELETE, self::OWN_ENTITY_GROUP, [ self::EMPLOYEE_READ, self::EMPLOYEE_EDIT ]);
    }
}
```

The `PermissionCollector` collects the permissions of all subscribers and then passes them to the storefront, where they can be attached to the role by the user.
If you want to check in the template if the user has this permission, the Twig function `isB2bAllowed` can be used:

```twig
{% sw_extends '@Storefront/storefront/page/checkout/checkout-item.html.twig' %}

{{ parent() }}

{% if isB2bAllowed(constant('PermissionCollectorSubscriber::EMPLOYEE_READ')) %}
...
{% endif  %}
```

In controllers, the checking of permissions must happen via the employee's role:

```php
<?php declare(strict_types=1);
public function employeeList(Request $request, SalesChannelContext $context): Response
{
    if (!$context->getCustomer()->getEmployee()->getRole()->can(PermissionCollectorSubscriber::EMPLOYEE_READ)) {
        throw new PermissionDeniedException();
    }
...
}
```

---

---
url: /docs/guides/plugins/plugins/creating-plugins.md
---

# Creating Plugins

This guide walks you through creating and scaffolding a basic Shopware plugin so it can be installed locally on your Shopware 6 instance.

## Prerequisites

You'll need:

* PHP knowledge
* A running Shopware 6 instance; refer to our [Install Shopware 6](../../installation/index.md) guide
* full file system and command line access

## 1. Choose a name

Use **UpperCamelCase**, which means that your plugin name must begin with a capital letter too. Whenever possible, begin it with a company prefix to avoid duplicate names (e.g., `SwagBasicExample`). Choose a name that describes your plugin as succinctly and clearly as possible.

::: info
A vendor prefix is required if you plan to publish your plugin in the [Shopware Community Store](https://store.shopware.com/en).
:::

## 2. Generate the plugin structure

Plugins are located in `<shopware project root>/custom/plugins` and managed via the Shopware Administration.

From your Shopware project's root directory, run:

```bash
bin/console plugin:create SwagBasicExample
```

::: tip Choose the workflow that fits your environment
Shopware's `bin/console plugin:create` command is the official, IDE-agnostic baseline
for repeatable plugin setup and automation. If you use PHPStorm, the [Shopware 6
Toolbox plugin](../../development/tooling/shopware-toolbox.md)
can generate an event subscriber, scheduled task, migration, Administration module,
or other component directly inside an existing plugin. AI coding tools can also help
you create or adapt these components, but always verify their namespaces, generated
paths, service registration, and Shopware-version compatibility against the linked
guides.
:::

The command asks for a plugin name and namespace (both UpperCamelCase) if you do not pass them as arguments, then asks whether it should scaffold optional files. It always generates the files an extension needs to be installable: `composer.json`, the plugin base class, `config.xml`, `.gitignore`, and the PHPUnit setup.

Use `--static` to create the plugin in `custom/static-plugins` instead of `custom/plugins`:

```bash
bin/console plugin:create SwagBasicExample --static
```

### Skipping optional scaffold files

Pass the `--no-scaffold` flag to skip all optional scaffold files and generate only the required plugin skeleton:

```bash
bin/console plugin:create SwagBasicExample 'Swag\BasicExample' --no-scaffold
```

The namespace is passed as a quoted argument because the backslash is part of the
namespace. The plugin name and namespace must use `UpperCamelCase`; do not enter a
human-readable name with spaces. The plugin name becomes the technical name used by
Shopware to identify the plugin.

When running the command interactively without the flag, you will be asked, "Would you like to scaffold optional plugin files?". Answering "no" has the same effect.

This is the recommended starting point when you already know what your plugin needs. The optional scaffolding generates example code across several directories, which is useful as a reference but leaves files behind that you have to read and delete.

To generate a specific example instead of all of them, pass its option. Each option can also be answered interactively:

| Option | Generates |
| --- | --- |
| `--create-storefront-controller` | Example Storefront controller, its template, and a `routes.php` entry |
| `--create-store-api-route` | Example Store API route with abstract class and response class |
| `--create-event-subscriber` | Example event subscriber |
| `--create-command` | Example console command |
| `--create-scheduled-task` | Example scheduled task |
| `--create-admin-module` | Example Administration module with snippets |
| `--create-javascript-plugin` | Example Storefront JavaScript plugin |
| `--create-custom-fieldset` | Example custom fieldset (`custom-fields.xml`) |
| `--entities=Example,Foo` | Entity definition, entity, collection, and migration per entity (UpperCamelCase, comma-separated) |

Every generator that needs a service definition also appends it to the plugin's service configuration in `src/Resources/config`.

The generated files are placed below the plugin root. For example, the optional
components use paths such as:

| Component | Typical generated location |
| --- | --- |
| Console command | `src/Command/` and `src/Resources/config/services.php` |
| Scheduled task | `src/ScheduledTask/` and `src/Resources/config/services.php` |
| Event subscriber | `src/Subscriber/` and `src/Resources/config/services.php` |
| Storefront controller | `src/Storefront/Controller/`, `src/Resources/views/`, and `src/Resources/config/routes.php` |
| Administration module | `src/Resources/app/administration/` |
| Storefront JavaScript plugin | `src/Resources/app/storefront/src/` |
| Custom field set | `src/Resources/config/custom-fields.xml` |

Treat generated examples as starting points. Selecting an option can create several
related files and service definitions; deleting only one file later can leave broken
references or an invalid service configuration. If you are unsure whether you need
an option, use `--no-scaffold` and add the feature from its focused guide instead.

::: info
Generated files are tied to the Shopware version you run the command on. When your plugin supports several Shopware versions, treat the output as a starting point and verify it against the version you target.
:::

Make sure to adjust the namespace in the generated files as per your needs.

### Generate components with the PHPStorm Toolbox

The [Shopware 6 Toolbox plugin](../../development/tooling/shopware-toolbox.md) for
PHPStorm creates plugins and individual components (including event subscribers,
scheduled tasks, migrations, Administration modules, and CMS blocks) from the editor.
Its generators are based on JetBrains file templates, so you can adapt the generated
files to your own conventions. This is especially useful for event subscribers,
because it creates the component in the context of the plugin you are working on.
After generating it, verify the [service registration](framework/event/listening-to-events.md#registering-your-subscriber-via-servicesphp)
required for Shopware to discover the subscriber.

::: info
After adding or changing service configuration, routes, or Twig templates, clear the cache with `bin/console cache:clear`. Stale caches are the most common reason a newly generated file appears to have no effect.
:::

### Structure for long-term maintainability

When building multiple custom features, consider grouping related functionality inside a single plugin or repository instead of creating many isolated plugins.

Keeping extensions in one repository with shared CI, shared static analysis rules, and unified coding standards makes future upgrades significantly easier to manage.

## 3. Plugin structure

Generated location:

```bash
custom/plugins/SwagBasicExample
```

Minimal structure:

```text
SwagBasicExample/
├── composer.json
└── src/
    └── SwagBasicExample.php
```

Basic plugin class:

```php
<?php declare(strict_types=1);

namespace Swag\BasicExample;

use Shopware\Core\Framework\Plugin;

class SwagBasicExample extends Plugin
{
}
```

## 4. composer.json essentials

To be installable, your plugin requires a `composer.json` file in its root directory: `custom/plugins/SwagBasicExample/composer.json`. Shopware uses this file to identify and register your plugin.

This file contains basic metadata that Shopware needs to know about your plugin, such as:

* The technical name
* The description
* The author
* The license
* The current plugin version
* The required dependencies
* and other configuration details.

The plugin's technical name is the identifier used by Shopware and must remain stable
after the plugin is distributed. Use the same name consistently in the plugin
directory, namespace, base class, and generated configuration. A change to the
technical name can prevent Shopware from matching an existing installation to the
plugin. For the related `technicalName` requirement introduced for payment and
shipping methods in Shopware 6.7, see the [Shopware 6.7 release notes](https://developer.shopware.com/release-notes/6.7/6.7.0.0.html#new-technicalname-property-for-payment-and-shipping-methods).

At a minimum, it must define:

* `"type": "shopware-platform-plugin"`, so that Shopware can safely recognize your plugin
* `require` field must include `shopware/core`, to check for compatibility
* `"extra.shopware-plugin-class"` pointing to your plugin base class
* [PSR-4](https://www.php-fig.org/psr/psr-4/) autoload configuration

The `extra.shopware-plugin-class` value must reference your plugin’s base PHP class (e.g. `Swag\\BasicExample\\SwagBasicExample`).

`shopware-platform-plugin` is the only Composer type Shopware treats as a plugin. A package with any other type — `library`, `project`, or the `shopware-app` type used for apps — is not picked up as a plugin and never appears in the Administration, even if everything else is set up correctly. Shopware also rejects a plugin whose `extra.shopware-plugin-class` or `extra.label` is missing.

The `autoload.psr-4` namespace must match your directory structure. If you change the path (for example, not using `src/`), your folders must reflect that configuration.

This file can also be read by [Composer](https://getcomposer.org/).

Here's an example `composer.json` you can refer to:

`<plugin root>/composer.json`:

```json
{
    "name": "swag/basic-example",
    "description": "Description for the plugin SwagBasicExample",
    "version": "1.0.0",
    "type": "shopware-platform-plugin",
    "license": "MIT",
    "authors": [
        {
            "name": "Shopware"
        }
    ],
    "require": {
        "shopware/core": "~6.7.0"
    },
    "extra": {
        "shopware-plugin-class": "Swag\\BasicExample\\SwagBasicExample",
        "label": {
            "de-DE": "Der angezeigte lesbare Name für das Plugin",
            "en-GB": "The displayed readable name for the plugin"
        },
        "description": {
            "de-DE": "Beschreibung in der Administration für das Plugin",
            "en-GB": "Description in the Administration for this plugin"
        }
    },
    "autoload": {
        "psr-4": {
            "Swag\\BasicExample\\": "src/"
        }
    }
}
```

::: info
Set up [CI](../../development/testing/ci.md) early. Run static analysis, tests, and `shopware-cli extension build` in CI so your plugin ZIP is reproducible and safe to promote across environments.
:::

### Depending on other plugins

If your plugin requires another plugin to be installed, declare it in the `require` section of your `composer.json` using the other plugin's Composer name and version (here, an example plugin named `swag/other-plugin`):

```json
"require": {
    "shopware/core": "~6.7.0",
    "swag/other-plugin": "^1.0"
}
```

Shopware will then enforce that the required plugin is installed and activated first. For version constraints, dev setups, and store considerations, see [Add Plugin Dependencies](./dependencies/add-plugin-dependencies.md).

## Add Shopware Packagist (optional)

Shopware's Packagist instance enables management of Shopware Store plugins directly in the `composer.json`. To add the repository to your project, run:

```bash
composer config repositories.shopware composer https://packages.shopware.com
```

Authentication via API token is required. Refer to [Extension Management](../../hosting/installation-updates/extension-management.md) for how to obtain the token and set up `auth.json`.

## Manual creation (optional)

In most cases, use `bin/console plugin:create`. Manual creation is only useful if you need full control over the structure or are working in a custom setup.

Create a directory in `custom/plugins` using your plugin’s technical name, following the minimal structure shown above. Use a namespace that combines your manufacturer prefix and technical name. The `src/` directory is recommended but not required, provided that the directory structure matches the PSR-4 autoload configuration in `composer.json`.

The plugin’s base class must extend `Shopware\Core\Framework\Plugin`.

## Next steps

[Install and activate](./install-activate-plugin.md) your plugin.

---

---
url: /docs/products/extensions/advanced-search/Cross-search.md
---

# Cross Search

@Refer: `\Shopware\Commercial\AdvancedSearch\Domain\CrossSearch\CrossSearchLogic`

At times, the need arises to search for categories using product names. To enable Elasticsearch with this capability, it becomes essential to index associated data across different indexes. However, it's important to note that this operation leads to a notable increase in the overall size of the index.

To solve this problem, an **experimental** feature called Cross Search has been introduced. You can configure which associations could be cross-searched:

```yaml
# config/packages/advanced_search.yaml
advanced_search:
    # When searching for `manufacturer.product.name`, if `product_manufacturer.product` cross_search is enabled, the `product` index will be used for search field `name`
    cross_search:
        product.product_manufacturer: false
        product.category: false
        category.product: true
        product_manufacturer.product: true
```

By default, only `category - product` and `product_manufacturer - product` associations are enabled, but you can change this behavior in the parameter. This way, we don't need to index product's data inside category and manufacturer indexes.

You can add your own Cross Search mapping to the parameter. If the mapping is not defined or is false, you need to index the associated data accordingly.

Be aware that this comes with a downside: when Cross Search is enabled, we need an extra aggregated Elasticsearch query to accomplish the desired search behavior.

---

---
url: /docs/v6.5/products/extensions/advanced-search/Cross-search.md
---

# Cross Search

@Refer: `\Shopware\Commercial\AdvancedSearch\Domain\CrossSearch\CrossSearchLogic`

At times, the need arises to search for categories using product names. To enable Elasticsearch with this capability, it becomes essential to index associated data across different indexes. However, it's important to note that this operation leads to a notable increase in the overall size of the index.

To solve this problem, an **experimental** feature called Cross Search has been introduced. You can configure which associations could be cross-searched:

```yaml
# config/packages/advanced_search.yaml
advanced_search:
    # When searching for `manufacturer.product.name`, if `product_manufacturer.product` cross_search is enabled, the `product` index will be used for search field `name`
    cross_search:
        product.product_manufacturer: false
        product.category: false
        category.product: true
        product_manufacturer.product: true
```

By default, only `category - product` and `product_manufacturer - product` associations are enabled, but you can change this behavior in the parameter. This way, we don't need to index product's data inside category and manufacturer indexes.

You can add your own Cross Search mapping to the parameter. If the mapping is not defined or is false, you need to index the associated data accordingly.

Be aware that this comes with a downside: when Cross Search is enabled, we need an extra aggregated Elasticsearch query to accomplish the desired search behavior.

---

---
url: /docs/v6.6/products/extensions/advanced-search/Cross-search.md
---

# Cross Search

@Refer: `\Shopware\Commercial\AdvancedSearch\Domain\CrossSearch\CrossSearchLogic`

At times, the need arises to search for categories using product names. To enable Elasticsearch with this capability, it becomes essential to index associated data across different indexes. However, it's important to note that this operation leads to a notable increase in the overall size of the index.

To solve this problem, an **experimental** feature called Cross Search has been introduced. You can configure which associations could be cross-searched:

```yaml
# config/packages/advanced_search.yaml
advanced_search:
    # When searching for `manufacturer.product.name`, if `product_manufacturer.product` cross_search is enabled, the `product` index will be used for search field `name`
    cross_search:
        product.product_manufacturer: false
        product.category: false
        category.product: true
        product_manufacturer.product: true
```

By default, only `category - product` and `product_manufacturer - product` associations are enabled, but you can change this behavior in the parameter. This way, we don't need to index product's data inside category and manufacturer indexes.

You can add your own Cross Search mapping to the parameter. If the mapping is not defined or is false, you need to index the associated data accordingly.

Be aware that this comes with a downside: when Cross Search is enabled, we need an extra aggregated Elasticsearch query to accomplish the desired search behavior.

---

---
url: /docs/products/extensions/b2b-suite/guides/core/crud-service.md
---

# CRUD Service

[Download](../example-plugins/B2bAcl.zip) a plugin showcasing the topic.

## Pattern

A repeating pattern used throughout the B2B Suite is the CRUD service.
The B2B Suite ships with its own entities and therefore provides the means to create, update and delete them.
Although these entities may have special requirements, an exclusively used naming convention and pattern are used to implement all CRUD operations.

The diagram below shows the usually implemented objects with their outside dependencies:

![image](../../../../../assets/b2bSuite-core-crudServicePattern.svg)

## Entity

There always is an entity representing the data that has to be written.
Entities are uniquely identifiable storage objects with public properties and only a few convenience functions.
An example entity looks like this:

```php
<?php declare(strict_types=1);

namespace Shopware\B2B\Role\Framework;

use Shopware\B2B\Common\CrudEntity;
use Shopware\B2B\Common\IdValue;
use function get_object_vars;
use function property_exists;

class RoleEntity implements CrudEntity
{
    public IdValue $id;

    public string $name;

    public IdValue $contextOwnerId;

    public int $left;

    public int $right;

    public int $level;

    public bool $hasChildren;

    public array $children = [];

    public function __construct()
    {
        $this->id = IdValue::null();
        $this->contextOwnerId = IdValue::null();
    }

    public function isNew(): bool
    {
        return $this->id instanceof NullIdValue;
    }

    public function toDatabaseArray(): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'context_owner_id' => $this->contextOwnerId->getStorageValue(),
        ];
    }

    public function fromDatabaseArray(array $roleData): CrudEntity
    {
        $this->id = IdValue::create($roleData['id']);
        $this->name = (string) $roleData['name'];
        $this->contextOwnerId = IdValue::create($roleData['context_owner_id']);
        $this->left = (int) $roleData['left'];
        $this->right = (int) $roleData['right'];
        $this->level = (int) $roleData['level'];
        $this->hasChildren = (bool) $roleData['hasChildren'];

        return $this;
    }

    public function setData(array $data)
    {
        foreach ($data as $key => $value) {
            if (!property_exists($this, $key)) {
                continue;
            }

            $this->{$key} = $value;
        }
    }

    public function toArray(): array
    {
        $vars = get_object_vars($this);
        
        foreach ($vars as $key => $var) {
            if ($var instanceof IdValue) {
                $vars[$key] = $var->getValue();
            }
        }

        return $vars;
    }

    public function jsonSerialize(): array
    {
        return $this->toArray();
    }
}
```

The convenience interface `Shopware\B2B\Common\CrudEntity` is not required to assign context to the object.
Furthermore, the definition of whether an entity can be stored or retrieved from storage can only securely be determined if corresponding repository methods exist.

## Repository

There always is a repository that handles all storage and retrieval functionality.
Contrary to Shopware default repositories, they do not use the ORM and do not expose queries.
A sample repository might look like this:

```php
<?php declare(strict_types=1);

namespace Shopware\B2B\Role\Framework;

use Doctrine\DBAL\Connection;
use Shopware\B2B\Acl\Framework\AclReadHelper;
use Shopware\B2B\Common\Controller\GridRepository;
use Shopware\B2B\Common\IdValue;
use Shopware\B2B\Common\Repository\CanNotInsertExistingRecordException;
use Shopware\B2B\Common\Repository\CanNotRemoveExistingRecordException;
use Shopware\B2B\Common\Repository\CanNotUpdateExistingRecordException;

class RoleRepository
{
    private Connection $connection;

    public function __construct(Connection $connection)
    {
        $this->connection = $connection;
    }

    /**
     * @throws NotFoundException
     */
    public function fetchOneById(int $id): CrudEntity
    {
        [...]
    }

    /**
     * @throws CanNotInsertExistingRecordException
     */
    public function addRole(RoleEntity $role): RoleEntity
    {
        [...]
    }

    /**
     * @throws CanNotUpdateExistingRecordException
     */
    public function updateRole(RoleEntity $role): RoleEntity
    {
        [...]
    }

    /**
     * @throws CanNotRemoveExistingRecordException
     */
    public function removeRole(RoleEntity $roleEntity): RoleEntity
    {
        [...]
    }
}
```

Since it seems to be a sufficient workload for a single object to interact with the storage layer, there is no additional validation. Everything that is solvable in PHP only is not part of this object.
Notice that the exceptions are all typed and can be caught easily by the implementation code.

## Validation service

Every entity has a corresponding `ValidationService`

```php
<?php declare(strict_types=1);

namespace Shopware\B2B\Role\Framework;

use Shopware\B2B\Common\Validator\ValidationBuilder;
use Shopware\B2B\Common\Validator\Validator;
use Symfony\Component\Validator\Validator\ValidatorInterface;

class RoleValidationService
{
    private ValidationBuilder $validationBuilder;

    private ValidatorInterface $validator;

    public function __construct(
        ValidationBuilder $validationBuilder,
        ValidatorInterface $validator
    ) {
        $this->validationBuilder = $validationBuilder;
        $this->validator = $validator;
    }

    public function createInsertValidation(RoleEntity $role): Validator
    {

        [...]

    }

    public function createUpdateValidation(RoleEntity $role): Validator
    {

        [...]

    }
```

It provides assertions that can be evaluated by a controller and printed to the user.

## CRUD service

Services are the real entry point to an entity. They are reusable and not dependent on any specific I/O mechanism.

They are not allowed to depend on HTTP implementations directly,
and therefore provide their own request classes that contain the source independent required raw data.
Notice that they are also used to initially filter a possibly larger request,
and they allow just the right data points to enter the service,
although the contents are validated by the `ValidationService`.

```php
<?php declare(strict_types=1);

namespace Shopware\B2B\Role\Framework;

use Shopware\B2B\Common\Service\AbstractCrudService;
use Shopware\B2B\Common\Service\CrudServiceRequest;

class RoleCrudService extends AbstractCrudService
{
    [...]

    public function createNewRecordRequest(array $data): CrudServiceRequest
    {
        return new CrudServiceRequest(
            $data,
            [
                'name',
                'contextOwnerId',
                'parentId',
            ]
        );
    }

    public function createExistingRecordRequest(array $data): CrudServiceRequest
    {
        return new CrudServiceRequest(
            $data,
            [
                'id',
                'name',
                'contextOwnerId',
            ]
        );
    }

    [...]
}
```

With a filled `CrudServiceRequest` you then call the actual action you want the service to perform.
Keep in mind that there may be other parameters required. For example, an `Identity` determines if the currently logged-in user may access the requested data.

```php
<?php declare(strict_types=1);

namespace Shopware\B2B\Role\Framework;

use Shopware\B2B\Common\Service\AbstractCrudService;
use Shopware\B2B\Common\Service\CrudServiceRequest;
use Shopware\B2B\Common\Validator\ValidationException

class RoleCrudService extends AbstractCrudService
{
    [...]

    /**
     * @throws ValidationException
     */
    public function create(CrudServiceRequest $request, OwnershipContext $ownershipContext): RoleEntity
    {
        [...]
    }

    /**
     * @throws ValidationException
     */
    public function update(CrudServiceRequest $request, OwnershipContext $ownershipContext): RoleEntity
    {
        [...]
    }

    public function remove(CrudServiceRequest $request, OwnershipContext $ownershipContext): RoleEntity
    {
        [...]
    }
    
    public function move(CrudServiceRequest $request, OwnershipContext $ownershipContext): RoleEntity
    {
        [...]
    }
}
```

---

---
url: /docs/v6.5/products/extensions/b2b-suite/guides/core/crud-service.md
---

# CRUD Service

[Download](../example-plugins/B2bAcl.zip) a plugin showcasing the topic.

## Pattern

A repeating pattern used throughout the B2B Suite is the CRUD service.
The B2B Suite ships with its own entities and therefore provides the means to create, update and delete them.
Although these entities may have special requirements, an exclusively used naming convention and pattern are used to implement all CRUD operations.

The diagram below shows the usually implemented objects with their outside dependencies:

![image](../../../../../assets/b2bSuite-core-crudServicePattern.svg)

## Entity

There always is an entity representing the data that has to be written.
Entities are uniquely identifiable storage objects with public properties and only a few convenience functions.
An example entity looks like this:

```php
<?php declare(strict_types=1);

namespace Shopware\B2B\Role\Framework;

use Shopware\B2B\Common\CrudEntity;
use Shopware\B2B\Common\IdValue;
use function get_object_vars;
use function property_exists;

class RoleEntity implements CrudEntity
{
    public IdValue $id;

    public string $name;

    public IdValue $contextOwnerId;

    public int $left;

    public int $right;

    public int $level;

    public bool $hasChildren;

    public array $children = [];

    public function __construct()
    {
        $this->id = IdValue::null();
        $this->contextOwnerId = IdValue::null();
    }

    public function isNew(): bool
    {
        return $this->id instanceof NullIdValue;
    }

    public function toDatabaseArray(): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'context_owner_id' => $this->contextOwnerId->getStorageValue(),
        ];
    }

    public function fromDatabaseArray(array $roleData): CrudEntity
    {
        $this->id = IdValue::create($roleData['id']);
        $this->name = (string) $roleData['name'];
        $this->contextOwnerId = IdValue::create($roleData['context_owner_id']);
        $this->left = (int) $roleData['left'];
        $this->right = (int) $roleData['right'];
        $this->level = (int) $roleData['level'];
        $this->hasChildren = (bool) $roleData['hasChildren'];

        return $this;
    }

    public function setData(array $data)
    {
        foreach ($data as $key => $value) {
            if (!property_exists($this, $key)) {
                continue;
            }

            $this->{$key} = $value;
        }
    }

    public function toArray(): array
    {
        $vars = get_object_vars($this);
        
        foreach ($vars as $key => $var) {
            if ($var instanceof IdValue) {
                $vars[$key] = $var->getValue();
            }
        }

        return $vars;
    }

    public function jsonSerialize(): array
    {
        return $this->toArray();
    }
}
```

The convenience interface `Shopware\B2B\Common\CrudEntity` is not required to assign context to the object.
Furthermore, the definition of whether an entity can be stored or retrieved from storage can only securely be determined if corresponding repository methods exist.

## Repository

There always is a repository that handles all storage and retrieval functionality.
Contrary to Shopware default repositories, they do not use the ORM and do not expose queries.
A sample repository might look like this:

```php
<?php declare(strict_types=1);

namespace Shopware\B2B\Role\Framework;

use Doctrine\DBAL\Connection;
use Shopware\B2B\Acl\Framework\AclReadHelper;
use Shopware\B2B\Common\Controller\GridRepository;
use Shopware\B2B\Common\IdValue;
use Shopware\B2B\Common\Repository\CanNotInsertExistingRecordException;
use Shopware\B2B\Common\Repository\CanNotRemoveExistingRecordException;
use Shopware\B2B\Common\Repository\CanNotUpdateExistingRecordException;

class RoleRepository
{
    private Connection $connection;

    public function __construct(Connection $connection)
    {
        $this->connection = $connection;
    }

    /**
     * @throws NotFoundException
     */
    public function fetchOneById(int $id): CrudEntity
    {
        [...]
    }

    /**
     * @throws CanNotInsertExistingRecordException
     */
    public function addRole(RoleEntity $role): RoleEntity
    {
        [...]
    }

    /**
     * @throws CanNotUpdateExistingRecordException
     */
    public function updateRole(RoleEntity $role): RoleEntity
    {
        [...]
    }

    /**
     * @throws CanNotRemoveExistingRecordException
     */
    public function removeRole(RoleEntity $roleEntity): RoleEntity
    {
        [...]
    }
}
```

Since it seems to be a sufficient workload for a single object to interact with the storage layer, there is no additional validation. Everything that is solvable in PHP only is not part of this object.
Notice that the exceptions are all typed and can be caught easily by the implementation code.

## Validation service

Every entity has a corresponding `ValidationService`

```php
<?php declare(strict_types=1);

namespace Shopware\B2B\Role\Framework;

use Shopware\B2B\Common\Validator\ValidationBuilder;
use Shopware\B2B\Common\Validator\Validator;
use Symfony\Component\Validator\Validator\ValidatorInterface;

class RoleValidationService
{
    private ValidationBuilder $validationBuilder;

    private ValidatorInterface $validator;

    public function __construct(
        ValidationBuilder $validationBuilder,
        ValidatorInterface $validator
    ) {
        $this->validationBuilder = $validationBuilder;
        $this->validator = $validator;
    }

    public function createInsertValidation(RoleEntity $role): Validator
    {

        [...]

    }

    public function createUpdateValidation(RoleEntity $role): Validator
    {

        [...]

    }
```

It provides assertions that can be evaluated by a controller and printed to the user.

## CRUD service

Services are the real entry point to an entity. They are reusable and not dependent on any specific I/O mechanism.

They are not allowed to depend on HTTP implementations directly,
and therefore provide their own request classes that contain the source independent required raw data.
Notice that they are also used to initially filter a possibly larger request,
and they allow just the right data points to enter the service,
although the contents are validated by the `ValidationService`.

```php
<?php declare(strict_types=1);

namespace Shopware\B2B\Role\Framework;

use Shopware\B2B\Common\Service\AbstractCrudService;
use Shopware\B2B\Common\Service\CrudServiceRequest;

class RoleCrudService extends AbstractCrudService
{
    [...]

    public function createNewRecordRequest(array $data): CrudServiceRequest
    {
        return new CrudServiceRequest(
            $data,
            [
                'name',
                'contextOwnerId',
                'parentId',
            ]
        );
    }

    public function createExistingRecordRequest(array $data): CrudServiceRequest
    {
        return new CrudServiceRequest(
            $data,
            [
                'id',
                'name',
                'contextOwnerId',
            ]
        );
    }

    [...]
}
```

With a filled `CrudServiceRequest` you then call the actual action you want the service to perform.
Keep in mind that there may be other parameters required. For example, an `Identity` determines if the currently logged-in user may access the requested data.

```php
<?php declare(strict_types=1);

namespace Shopware\B2B\Role\Framework;

use Shopware\B2B\Common\Service\AbstractCrudService;
use Shopware\B2B\Common\Service\CrudServiceRequest;
use Shopware\B2B\Common\Validator\ValidationException

class RoleCrudService extends AbstractCrudService
{
    [...]

    /**
     * @throws ValidationException
     */
    public function create(CrudServiceRequest $request, OwnershipContext $ownershipContext): RoleEntity
    {
        [...]
    }

    /**
     * @throws ValidationException
     */
    public function update(CrudServiceRequest $request, OwnershipContext $ownershipContext): RoleEntity
    {
        [...]
    }

    public function remove(CrudServiceRequest $request, OwnershipContext $ownershipContext): RoleEntity
    {
        [...]
    }
    
    public function move(CrudServiceRequest $request, OwnershipContext $ownershipContext): RoleEntity
    {
        [...]
    }
}
```

---

---
url: /docs/v6.6/products/extensions/b2b-suite/guides/core/crud-service.md
---

# CRUD Service

[Download](../example-plugins/B2bAcl.zip) a plugin showcasing the topic.

## Pattern

A repeating pattern used throughout the B2B Suite is the CRUD service.
The B2B Suite ships with its own entities and therefore provides the means to create, update and delete them.
Although these entities may have special requirements, an exclusively used naming convention and pattern are used to implement all CRUD operations.

The diagram below shows the usually implemented objects with their outside dependencies:

![image](../../../../../assets/b2bSuite-core-crudServicePattern.svg)

## Entity

There always is an entity representing the data that has to be written.
Entities are uniquely identifiable storage objects with public properties and only a few convenience functions.
An example entity looks like this:

```php
<?php declare(strict_types=1);

namespace Shopware\B2B\Role\Framework;

use Shopware\B2B\Common\CrudEntity;
use Shopware\B2B\Common\IdValue;
use function get_object_vars;
use function property_exists;

class RoleEntity implements CrudEntity
{
    public IdValue $id;

    public string $name;

    public IdValue $contextOwnerId;

    public int $left;

    public int $right;

    public int $level;

    public bool $hasChildren;

    public array $children = [];

    public function __construct()
    {
        $this->id = IdValue::null();
        $this->contextOwnerId = IdValue::null();
    }

    public function isNew(): bool
    {
        return $this->id instanceof NullIdValue;
    }

    public function toDatabaseArray(): array
    {
        return [
            'id' => $this->id,
            'name' => $this->name,
            'context_owner_id' => $this->contextOwnerId->getStorageValue(),
        ];
    }

    public function fromDatabaseArray(array $roleData): CrudEntity
    {
        $this->id = IdValue::create($roleData['id']);
        $this->name = (string) $roleData['name'];
        $this->contextOwnerId = IdValue::create($roleData['context_owner_id']);
        $this->left = (int) $roleData['left'];
        $this->right = (int) $roleData['right'];
        $this->level = (int) $roleData['level'];
        $this->hasChildren = (bool) $roleData['hasChildren'];

        return $this;
    }

    public function setData(array $data)
    {
        foreach ($data as $key => $value) {
            if (!property_exists($this, $key)) {
                continue;
            }

            $this->{$key} = $value;
        }
    }

    public function toArray(): array
    {
        $vars = get_object_vars($this);
        
        foreach ($vars as $key => $var) {
            if ($var instanceof IdValue) {
                $vars[$key] = $var->getValue();
            }
        }

        return $vars;
    }

    public function jsonSerialize(): array
    {
        return $this->toArray();
    }
}
```

The convenience interface `Shopware\B2B\Common\CrudEntity` is not required to assign context to the object.
Furthermore, the definition of whether an entity can be stored or retrieved from storage can only securely be determined if corresponding repository methods exist.

## Repository

There always is a repository that handles all storage and retrieval functionality.
Contrary to Shopware default repositories, they do not use the ORM and do not expose queries.
A sample repository might look like this:

```php
<?php declare(strict_types=1);

namespace Shopware\B2B\Role\Framework;

use Doctrine\DBAL\Connection;
use Shopware\B2B\Acl\Framework\AclReadHelper;
use Shopware\B2B\Common\Controller\GridRepository;
use Shopware\B2B\Common\IdValue;
use Shopware\B2B\Common\Repository\CanNotInsertExistingRecordException;
use Shopware\B2B\Common\Repository\CanNotRemoveExistingRecordException;
use Shopware\B2B\Common\Repository\CanNotUpdateExistingRecordException;

class RoleRepository
{
    private Connection $connection;

    public function __construct(Connection $connection)
    {
        $this->connection = $connection;
    }

    /**
     * @throws NotFoundException
     */
    public function fetchOneById(int $id): CrudEntity
    {
        [...]
    }

    /**
     * @throws CanNotInsertExistingRecordException
     */
    public function addRole(RoleEntity $role): RoleEntity
    {
        [...]
    }

    /**
     * @throws CanNotUpdateExistingRecordException
     */
    public function updateRole(RoleEntity $role): RoleEntity
    {
        [...]
    }

    /**
     * @throws CanNotRemoveExistingRecordException
     */
    public function removeRole(RoleEntity $roleEntity): RoleEntity
    {
        [...]
    }
}
```

Since it seems to be a sufficient workload for a single object to interact with the storage layer, there is no additional validation. Everything that is solvable in PHP only is not part of this object.
Notice that the exceptions are all typed and can be caught easily by the implementation code.

## Validation service

Every entity has a corresponding `ValidationService`

```php
<?php declare(strict_types=1);

namespace Shopware\B2B\Role\Framework;

use Shopware\B2B\Common\Validator\ValidationBuilder;
use Shopware\B2B\Common\Validator\Validator;
use Symfony\Component\Validator\Validator\ValidatorInterface;

class RoleValidationService
{
    private ValidationBuilder $validationBuilder;

    private ValidatorInterface $validator;

    public function __construct(
        ValidationBuilder $validationBuilder,
        ValidatorInterface $validator
    ) {
        $this->validationBuilder = $validationBuilder;
        $this->validator = $validator;
    }

    public function createInsertValidation(RoleEntity $role): Validator
    {

        [...]

    }

    public function createUpdateValidation(RoleEntity $role): Validator
    {

        [...]

    }
```

It provides assertions that can be evaluated by a controller and printed to the user.

## CRUD service

Services are the real entry point to an entity. They are reusable and not dependent on any specific I/O mechanism.

They are not allowed to depend on HTTP implementations directly,
and therefore provide their own request classes that contain the source independent required raw data.
Notice that they are also used to initially filter a possibly larger request,
and they allow just the right data points to enter the service,
although the contents are validated by the `ValidationService`.

```php
<?php declare(strict_types=1);

namespace Shopware\B2B\Role\Framework;

use Shopware\B2B\Common\Service\AbstractCrudService;
use Shopware\B2B\Common\Service\CrudServiceRequest;

class RoleCrudService extends AbstractCrudService
{
    [...]

    public function createNewRecordRequest(array $data): CrudServiceRequest
    {
        return new CrudServiceRequest(
            $data,
            [
                'name',
                'contextOwnerId',
                'parentId',
            ]
        );
    }

    public function createExistingRecordRequest(array $data): CrudServiceRequest
    {
        return new CrudServiceRequest(
            $data,
            [
                'id',
                'name',
                'contextOwnerId',
            ]
        );
    }

    [...]
}
```

With a filled `CrudServiceRequest` you then call the actual action you want the service to perform.
Keep in mind that there may be other parameters required. For example, an `Identity` determines if the currently logged-in user may access the requested data.

```php
<?php declare(strict_types=1);

namespace Shopware\B2B\Role\Framework;

use Shopware\B2B\Common\Service\AbstractCrudService;
use Shopware\B2B\Common\Service\CrudServiceRequest;
use Shopware\B2B\Common\Validator\ValidationException

class RoleCrudService extends AbstractCrudService
{
    [...]

    /**
     * @throws ValidationException
     */
    public function create(CrudServiceRequest $request, OwnershipContext $ownershipContext): RoleEntity
    {
        [...]
    }

    /**
     * @throws ValidationException
     */
    public function update(CrudServiceRequest $request, OwnershipContext $ownershipContext): RoleEntity
    {
        [...]
    }

    public function remove(CrudServiceRequest $request, OwnershipContext $ownershipContext): RoleEntity
    {
        [...]
    }
    
    public function move(CrudServiceRequest $request, OwnershipContext $ownershipContext): RoleEntity
    {
        [...]
    }
}
```

---

---
url: /docs/products/extensions/b2b-suite/guides/core/currency.md
---

# Currency

## Introduction

The Currency component provides the means for currency calculation in the B2B Suite. The following graph shows components depending on this component:

![image](../../../../../assets/b2bSuite-core-currencyComponent.svg)

| Icon                                      |Description|
|---------------------------------------------|------------|
|  | Represents component |
|  | Represent context objects that contain the component specific information |
|  | Represents child components |

## Context

The Currency component provides an additional Context object (`Shopware\B2B\Currency\Framework\CurrencyContext`) containing a currency factor.
You can retrieve the default Context, which always contains the currently selected currency factor through the `Shopware\B2B\Currency\Framework\CurrencyService`.

```php
<?php declare(strict_types=1);

use Shopware\B2B\Currency\Framework\CurrencyContext;
use Shopware\B2B\Currency\Framework\CurrencyService;

class TestController
{
    private CurrencyService $currencyService;

    public function __construct(
        CurrencyService $currencyService
    ) {
        $this->currencyService = $currencyService;
    }

    public function testAction(): array
    {
        return [
            'currencyContext' => $this->currencyService->createCurrencyContext(),
        ];
    }
```

This way, you can either store the currency factor with a newly provided amount or retrieve recalculated data from your repository.

## Entity

All recalculable entities must implement the interface `Shopware\B2B\Currency\Framework\CurrencyAware`, which provides the means to access the currency data.

```php
use Shopware\B2B\Currency\Framework\CurrencyAware;

class MyEntity implements CurrencyAware
{
    public float $amount1;

    public float $amount2;

    private float $factor;

    public function getCurrencyFactor(): float
    {
        return $this->factor;
    }

    public function setCurrencyFactor(float $factor)
    {
        $this->factor = $factor;
    }

    /**
     * @return string[]
     */
    public function getAmountPropertyNames(): array
    {
        return [
            'amount1',
            'amount2',
        ];
    }
}
```

## Repository

The repository has to guarantee that every entity retrieved from storage has valid and, if necessary, recalculated money values.
The Currency component provides `Shopware\B2B\Currency\Framework\CurrencyCalculator` to help with this promise.
So a typical repository looks like this:

```php
<?php declare(strict_types=1);

use Shopware\B2B\Currency\Framework\CurrencyCalculator;

class Repository
{
    private CurrencyCalculator $currencyCalculator;

    public function __construct(
        CurrencyCalculator $currencyCalculator
    ) {
        $this->currencyCalculator = $currencyCalculator;
    }
}
```

### Calculating in PHP (preferred)

To recalculate an entity amount, the calculator provides two convenient functions.

* `recalculateAmount` for a single entity:

```php
    public function fetchOneById(int $id, CurrencyContext $currencyContext): CurrencyAware
    {
        [...] // load entity from Database

        $this->currencyCalculator->recalculateAmount($entity, $currencyContext);

        return $entity;
    }
```

* `recalculateAmounts` to recalculate an array of entities:

```php
    public function fetchList([...], CurrencyContext $currencyContext): array
    {
        [...] // load entities from Database

        //recalculate with the current amount
        $this->>currencyCalculator->recalculateAmounts($entities, $currencyContext);

        return $entities;
    }
```

### Calculating in SQL

Although calculation in PHP is the preferred way, it may sometimes be necessary to recalculate the amounts in SQL.
This is the case if you, for example, use a `GROUP BY` statement and try to create a sum.
For this case, the Currency component creates a SQL calculation snippet.

So if your original snippet looked like this:

```php
    public function fetchAmount(int $budgetId): float
    {
        return (float) $this-connection->fetchColumn(
            'SELECT SUM(amount) AS sum_amount FROM b2b_budget_transaction WHERE budget_id=:budgetId',
            ['budgetId' => $budgetId]
        )
    }
```

But it should actually look like this:

```php
    public function fetchAmount(int $budgetId, CurrencyContext $currencyContext): float
    {
        $transactionSnippet = $this->currencyCalculator
            ->getSqlCalculationPart('amount', 'currency_factor', $currencyContext);

        return (float) $this-connection->fetchColumn(
            'SELECT SUM(' . $transactionSnippet . ') AS sum_amount FROM b2b_budget_transaction WHERE budget_id=:budgetId',
            ['budgetId' => $budgetId]
        )
    }
```

---

---
url: /docs/v6.5/products/extensions/b2b-suite/guides/core/currency.md
---

# Currency

## Introduction

The Currency component provides the means for currency calculation in the B2B Suite. The following graph shows components depending on this component:

![image](../../../../../assets/b2bSuite-core-currencyComponent.svg)

| Icon                                      |Description|
|---------------------------------------------|------------|
|  | Represents component |
|  | Represent context objects that contain the component specific information |
|  | Represents child components |

## Context

The Currency component provides an additional Context object (`Shopware\B2B\Currency\Framework\CurrencyContext`) containing a currency factor.
You can retrieve the default Context, which always contains the currently selected currency factor through the `Shopware\B2B\Currency\Framework\CurrencyService`.

```php
<?php declare(strict_types=1);

use Shopware\B2B\Currency\Framework\CurrencyContext;
use Shopware\B2B\Currency\Framework\CurrencyService;

class TestController
{
    private CurrencyService $currencyService;

    public function __construct(
        CurrencyService $currencyService
    ) {
        $this->currencyService = $currencyService;
    }

    public function testAction(): array
    {
        return [
            'currencyContext' => $this->currencyService->createCurrencyContext(),
        ];
    }
```

This way, you can either store the currency factor with a newly provided amount or retrieve recalculated data from your repository.

## Entity

All recalculable entities must implement the interface `Shopware\B2B\Currency\Framework\CurrencyAware`, which provides the means to access the currency data.

```php
use Shopware\B2B\Currency\Framework\CurrencyAware;

class MyEntity implements CurrencyAware
{
    public float $amount1;

    public float $amount2;

    private float $factor;

    public function getCurrencyFactor(): float
    {
        return $this->factor;
    }

    public function setCurrencyFactor(float $factor)
    {
        $this->factor = $factor;
    }

    /**
     * @return string[]
     */
    public function getAmountPropertyNames(): array
    {
        return [
            'amount1',
            'amount2',
        ];
    }
}
```

## Repository

The repository has to guarantee that every entity retrieved from storage has valid and, if necessary, recalculated money values.
The Currency component provides `Shopware\B2B\Currency\Framework\CurrencyCalculator` to help with this promise.
So a typical repository looks like this:

```php
<?php declare(strict_types=1);

use Shopware\B2B\Currency\Framework\CurrencyCalculator;

class Repository
{
    private CurrencyCalculator $currencyCalculator;

    public function __construct(
        CurrencyCalculator $currencyCalculator
    ) {
        $this->currencyCalculator = $currencyCalculator;
    }
}
```

### Calculating in PHP (preferred)

To recalculate an entity amount, the calculator provides two convenient functions.

* `recalculateAmount` for a single entity:

```php
    public function fetchOneById(int $id, CurrencyContext $currencyContext): CurrencyAware
    {
        [...] // load entity from Database

        $this->currencyCalculator->recalculateAmount($entity, $currencyContext);

        return $entity;
    }
```

* `recalculateAmounts` to recalculate an array of entities:

```php
    public function fetchList([...], CurrencyContext $currencyContext): array
    {
        [...] // load entities from Database

        //recalculate with the current amount
        $this->>currencyCalculator->recalculateAmounts($entities, $currencyContext);

        return $entities;
    }
```

### Calculating in SQL

Although calculation in PHP is the preferred way, it may sometimes be necessary to recalculate the amounts in SQL.
This is the case if you, for example, use a `GROUP BY` statement and try to create a sum.
For this case, the Currency component creates a SQL calculation snippet.

So if your original snippet looked like this:

```php
    public function fetchAmount(int $budgetId): float
    {
        return (float) $this-connection->fetchColumn(
            'SELECT SUM(amount) AS sum_amount FROM b2b_budget_transaction WHERE budget_id=:budgetId',
            ['budgetId' => $budgetId]
        )
    }
```

But it should actually look like this:

```php
    public function fetchAmount(int $budgetId, CurrencyContext $currencyContext): float
    {
        $transactionSnippet = $this->currencyCalculator
            ->getSqlCalculationPart('amount', 'currency_factor', $currencyContext);

        return (float) $this-connection->fetchColumn(
            'SELECT SUM(' . $transactionSnippet . ') AS sum_amount FROM b2b_budget_transaction WHERE budget_id=:budgetId',
            ['budgetId' => $budgetId]
        )
    }
```

---

---
url: /docs/v6.6/products/extensions/b2b-suite/guides/core/currency.md
---

# Currency

## Introduction

The Currency component provides the means for currency calculation in the B2B Suite. The following graph shows components depending on this component:

![image](../../../../../assets/b2bSuite-core-currencyComponent.svg)

| Icon                                      |Description|
|---------------------------------------------|------------|
|  | Represents component |
|  | Represent context objects that contain the component specific information |
|  | Represents child components |

## Context

The Currency component provides an additional Context object (`Shopware\B2B\Currency\Framework\CurrencyContext`) containing a currency factor.
You can retrieve the default Context, which always contains the currently selected currency factor through the `Shopware\B2B\Currency\Framework\CurrencyService`.

```php
<?php declare(strict_types=1);

use Shopware\B2B\Currency\Framework\CurrencyContext;
use Shopware\B2B\Currency\Framework\CurrencyService;

class TestController
{
    private CurrencyService $currencyService;

    public function __construct(
        CurrencyService $currencyService
    ) {
        $this->currencyService = $currencyService;
    }

    public function testAction(): array
    {
        return [
            'currencyContext' => $this->currencyService->createCurrencyContext(),
        ];
    }
```

This way, you can either store the currency factor with a newly provided amount or retrieve recalculated data from your repository.

## Entity

All recalculable entities must implement the interface `Shopware\B2B\Currency\Framework\CurrencyAware`, which provides the means to access the currency data.

```php
use Shopware\B2B\Currency\Framework\CurrencyAware;

class MyEntity implements CurrencyAware
{
    public float $amount1;

    public float $amount2;

    private float $factor;

    public function getCurrencyFactor(): float
    {
        return $this->factor;
    }

    public function setCurrencyFactor(float $factor)
    {
        $this->factor = $factor;
    }

    /**
     * @return string[]
     */
    public function getAmountPropertyNames(): array
    {
        return [
            'amount1',
            'amount2',
        ];
    }
}
```

## Repository

The repository has to guarantee that every entity retrieved from storage has valid and, if necessary, recalculated money values.
The Currency component provides `Shopware\B2B\Currency\Framework\CurrencyCalculator` to help with this promise.
So a typical repository looks like this:

```php
<?php declare(strict_types=1);

use Shopware\B2B\Currency\Framework\CurrencyCalculator;

class Repository
{
    private CurrencyCalculator $currencyCalculator;

    public function __construct(
        CurrencyCalculator $currencyCalculator
    ) {
        $this->currencyCalculator = $currencyCalculator;
    }
}
```

### Calculating in PHP (preferred)

To recalculate an entity amount, the calculator provides two convenient functions.

* `recalculateAmount` for a single entity:

```php
    public function fetchOneById(int $id, CurrencyContext $currencyContext): CurrencyAware
    {
        [...] // load entity from Database

        $this->currencyCalculator->recalculateAmount($entity, $currencyContext);

        return $entity;
    }
```

* `recalculateAmounts` to recalculate an array of entities:

```php
    public function fetchList([...], CurrencyContext $currencyContext): array
    {
        [...] // load entities from Database

        //recalculate with the current amount
        $this->>currencyCalculator->recalculateAmounts($entities, $currencyContext);

        return $entities;
    }
```

### Calculating in SQL

Although calculation in PHP is the preferred way, it may sometimes be necessary to recalculate the amounts in SQL.
This is the case if you, for example, use a `GROUP BY` statement and try to create a sum.
For this case, the Currency component creates a SQL calculation snippet.

So if your original snippet looked like this:

```php
    public function fetchAmount(int $budgetId): float
    {
        return (float) $this-connection->fetchColumn(
            'SELECT SUM(amount) AS sum_amount FROM b2b_budget_transaction WHERE budget_id=:budgetId',
            ['budgetId' => $budgetId]
        )
    }
```

But it should actually look like this:

```php
    public function fetchAmount(int $budgetId, CurrencyContext $currencyContext): float
    {
        $transactionSnippet = $this->currencyCalculator
            ->getSqlCalculationPart('amount', 'currency_factor', $currencyContext);

        return (float) $this-connection->fetchColumn(
            'SELECT SUM(' . $transactionSnippet . ') AS sum_amount FROM b2b_budget_transaction WHERE budget_id=:budgetId',
            ['budgetId' => $budgetId]
        )
    }
```

---

---
url: /docs/v6.5/guides/hosting/performance/custom-cache-invalidation.md
---

# Custom cache invalidation

The current cache system of Shopware is based on a multi-layer system, in which the individual layers build on each other and whose tags are passed on to the upper layer for later invalidation.

Thus, an HTTP cache entry for a product detail page is built with all cache tags that are loaded or set during the rendering of the page for the individual routes or other cache entries in the system.

These tags are determined by the Shopware core system when writing data via API and invalidated via the configured cache pool.

In the current state, almost all invalidations happen in class `Shopware\Core\Framework\Adapter\Cache\CacheInvalidationSubscriber`. This is an event listener which listens for various events in the system and determines the corresponding cache tags and sends them via `Shopware\Core\Framework\Adapter\Cache\CacheInvalidator` to the cache pool for invalidation.

However, currently, the subscriber adheres to a highly precise invalidation concept, where any data written to the product results in the invalidation of cache tags for that specific product, even if the data is not utilized in the corresponding pages. This approach is not ideal for Shopware, being a standard product, as it becomes challenging to determine precisely when and which cache entries should be deleted. Moreover, due to project-specific variations, it is not feasible to generalize the process.

Therefore, we have solved all configurations via the service definition of this subscriber, so that all events, on which the subscriber listens, can be manipulated via compiler passes.

```xml
// src/Core/Framework/DependencyInjection/cache.xml
<service id="Shopware\Core\Framework\Adapter\Cache\CacheInvalidationSubscriber">
    <tag name="kernel.event_listener" event="Shopware\Core\Content\Category\Event\CategoryIndexerEvent" method="invalidateCategoryRouteByCategoryIds" priority="2000" />

    <tag name="kernel.event_listener" event="Shopware\Core\Content\Category\Event\CategoryIndexerEvent" method="invalidateListingRouteByCategoryIds" priority="2001" />

    <tag name="kernel.event_listener" event="Shopware\Core\Content\LandingPage\Event\LandingPageIndexerEvent" method="invalidateIndexedLandingPages" priority="2000" />
    
    <!-- ... -->
</service>
```

For example, if you want to disable all cache invalidation in a project, you can simply remove the `kernel.event_listener` tag of the service definition via compiler pass and implement your own cache invalidation.

```php
<?php

namespace MyProject;

use Shopware\Core\Content\Product\Events\ProductIndexerEvent;
use Shopware\Core\Content\Product\Events\ProductNoLongerAvailableEvent;
use Shopware\Core\Framework\DependencyInjection\CompilerPass\RemoveEventListener;
use Shopware\Core\Framework\Adapter\Cache\CacheInvalidationSubscriber;

class TweakCacheInvalidation implements CompilerPassInterface
{
    public function process(ContainerBuilder $container): void
    {
        $container
            ->getDefinition(CacheInvalidationSubscriber::class)
            ->clearTag('kernel.event_listener')
    }

}
```

However, suppose only certain parts of the cache invalidation are to be adjusted, finer adjustments to the class can be made using `Shopware\Core\Framework\DependencyInjection\CompilerPass\RemoveEventListener`, in which it is possible to define which event listeners of the service are to be removed.

```php
<?php

namespace MyProject;

use Shopware\Core\Content\Product\Events\ProductIndexerEvent;
use Shopware\Core\Content\Product\Events\ProductNoLongerAvailableEvent;
use Shopware\Core\Framework\DependencyInjection\CompilerPass\RemoveEventListener;
use Shopware\Core\Framework\Adapter\Cache\CacheInvalidationSubscriber;

class TweakCacheInvalidation implements CompilerPassInterface
{
    public function process(ContainerBuilder $container): void
    {
        RemoveEventListener::remove(
            $container,
            CacheInvalidationSubscriber::class,
            [
                [ProductIndexerEvent::class, 'invalidateListings'],
                [ProductNoLongerAvailableEvent::class, 'invalidateListings'],
            ]
        );
    }
} 
```

---

---
url: /docs/v6.6/guides/hosting/performance/custom-cache-invalidation.md
---

# Custom cache invalidation

The current cache system of Shopware is based on a multi-layer system, in which the individual layers build on each other and whose tags are passed on to the upper layer for later invalidation.

Thus, an HTTP cache entry for a product detail page is built with all cache tags that are loaded or set during the rendering of the page for the individual routes or other cache entries in the system.

These tags are determined by the Shopware core system when writing data via API and invalidated via the configured cache pool.

In the current state, almost all invalidations happen in class `Shopware\Core\Framework\Adapter\Cache\CacheInvalidationSubscriber`. This is an event listener which listens for various events in the system and determines the corresponding cache tags and sends them via `Shopware\Core\Framework\Adapter\Cache\CacheInvalidator` to the cache pool for invalidation.

However, currently, the subscriber adheres to a highly precise invalidation concept, where any data written to the product results in the invalidation of cache tags for that specific product, even if the data is not utilized in the corresponding pages. This approach is not ideal for Shopware, being a standard product, as it becomes challenging to determine precisely when and which cache entries should be deleted. Moreover, due to project-specific variations, it is not feasible to generalize the process.

Therefore, we have solved all configurations via the service definition of this subscriber, so that all events, on which the subscriber listens, can be manipulated via compiler passes.

```xml
// src/Core/Framework/DependencyInjection/cache.xml
<service id="Shopware\Core\Framework\Adapter\Cache\CacheInvalidationSubscriber">
    <tag name="kernel.event_listener" event="Shopware\Core\Content\Category\Event\CategoryIndexerEvent" method="invalidateCategoryRouteByCategoryIds" priority="2000" />

    <tag name="kernel.event_listener" event="Shopware\Core\Content\Category\Event\CategoryIndexerEvent" method="invalidateListingRouteByCategoryIds" priority="2001" />

    <tag name="kernel.event_listener" event="Shopware\Core\Content\LandingPage\Event\LandingPageIndexerEvent" method="invalidateIndexedLandingPages" priority="2000" />
    
    <!-- ... -->
</service>
```

For example, if you want to disable all cache invalidation in a project, you can simply remove the `kernel.event_listener` tag of the service definition via compiler pass and implement your own cache invalidation.

```php
<?php

namespace MyProject;

use Shopware\Core\Content\Product\Events\ProductIndexerEvent;
use Shopware\Core\Content\Product\Events\ProductNoLongerAvailableEvent;
use Shopware\Core\Framework\DependencyInjection\CompilerPass\RemoveEventListener;
use Shopware\Core\Framework\Adapter\Cache\CacheInvalidationSubscriber;

class TweakCacheInvalidation implements CompilerPassInterface
{
    public function process(ContainerBuilder $container): void
    {
        $container
            ->getDefinition(CacheInvalidationSubscriber::class)
            ->clearTag('kernel.event_listener')
    }

}
```

However, suppose only certain parts of the cache invalidation are to be adjusted, finer adjustments to the class can be made using `Shopware\Core\Framework\DependencyInjection\CompilerPass\RemoveEventListener`, in which it is possible to define which event listeners of the service are to be removed.

```php
<?php

namespace MyProject;

use Shopware\Core\Content\Product\Events\ProductIndexerEvent;
use Shopware\Core\Content\Product\Events\ProductNoLongerAvailableEvent;
use Shopware\Core\Framework\DependencyInjection\CompilerPass\RemoveEventListener;
use Shopware\Core\Framework\Adapter\Cache\CacheInvalidationSubscriber;

class TweakCacheInvalidation implements CompilerPassInterface
{
    public function process(ContainerBuilder $container): void
    {
        RemoveEventListener::remove(
            $container,
            CacheInvalidationSubscriber::class,
            [
                [ProductIndexerEvent::class, 'invalidateListings'],
                [ProductNoLongerAvailableEvent::class, 'invalidateListings'],
            ]
        );
    }
} 
```

---

---
url: /docs/guides/plugins/apps/custom-data.md
---

# Custom data

You are able to store custom data in Shopware which you can use for your apps. You can store simple data types like strings, numbers, booleans, arrays and objects directly in core tables via [custom fields](custom-fields) or define complete new entities with own associations and lifecycle via [custom entities](custom-entities).

---

---
url: /docs/v6.5/guides/plugins/apps/custom-data.md
---

# Custom data

You are able to store custom data in Shopware which you can use for your apps. You can store simple data types like strings, numbers, booleans, arrays and objects directly in core tables via [custom fields](custom-fields) or define complete new entities with own associations and lifecycle via [custom entities](custom-entities).

---

---
url: /docs/v6.6/guides/plugins/apps/custom-data.md
---

# Custom data

You are able to store custom data in Shopware which you can use for your apps. You can store simple data types like strings, numbers, booleans, arrays and objects directly in core tables via [custom fields](custom-fields) or define complete new entities with own associations and lifecycle via [custom entities](custom-entities).

---

---
url: /docs/v6.5/guides/plugins/apps/custom-data/custom-fields.md
---

# Custom Data

You can add custom fields to Shopware and thus add your own fields to extending data records. The user is able to modify this fields from within the Shopware Administration.\
To make use of the custom fields, register your custom field sets in your manifest file:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        ...
    </meta>
    <custom-fields>
        <custom-field-set>
            <name>swag_example_set</name>
            <label>Example Set</label>
            <label lang="de-DE">Beispiel-Set</label>
            <related-entities>
                <order/>
            </related-entities>
            <fields>
                <text name="swag_code">
                    <position>1</position>
                    <label>Example field</label>
                </text>
            </fields>
        </custom-field-set>
    </custom-fields>
</manifest>

```

For a complete reference of the structure of the manifest file, take a look at the [Manifest reference](../../../../resources/references/app-reference/manifest-reference).

For the data needed, please refer to the custom fields in general: At first, you need a custom field set, as [custom fields](../../plugins/framework/custom-field/) in Shopware are organised in sets. Here you need to consider some important fields:

* `name`: A technical name for your set
* `label`: This element provides the label of the text and can be used for defining translations of the label as well.
* `related-entities`: With this element set the entities the custom field set is used in
* `fields`: Finally, the fields are configured in this section.

::: warning
The names of the custom fields are global and therefore should always contain a vendor prefix, like "swag" for "shopware ag", to keep them unique. This holds true for the name of the custom field set, as well as each name of the fields itself.
:::

When defining custom fields in the `<fields>` element, you can configure additional properties of the fields. For example a `placeholder`, `min`, `max` and `step` size of a float field:

```html
<float name="swag_test_float_field">
    <label>Test float field</label>
    <label lang="de-DE">Test-Kommazahlenfeld</label>
    <help-text>This is an float field.</help-text>
    <position>2</position>
    <placeholder>Enter an float...</placeholder>
    <min>0.5</min>
    <max>1.6</max>
    <steps>0.2</steps>
</float>
```

Refer to the [custom field](../../plugins/framework/custom-field/) documentation for further details.

---

---
url: /docs/v6.6/guides/plugins/apps/custom-data/custom-fields.md
---

# Custom Data

You can add custom fields to Shopware and thus add your own fields to extending data records. The user is able to modify this fields from within the Shopware Administration.\
To make use of the custom fields, register your custom field sets in your manifest file:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        ...
    </meta>
    <custom-fields>
        <custom-field-set>
            <name>swag_example_set</name>
            <label>Example Set</label>
            <label lang="de-DE">Beispiel-Set</label>
            <related-entities>
                <order/>
            </related-entities>
            <fields>
                <text name="swag_code">
                    <position>1</position>
                    <label>Example field</label>
                </text>
            </fields>
        </custom-field-set>
    </custom-fields>
</manifest>

```

For a complete reference of the structure of the manifest file, take a look at the [Manifest reference](../../../../resources/references/app-reference/manifest-reference).

For the data needed, please refer to the custom fields in general: At first, you need a custom field set, as [custom fields](../../plugins/framework/custom-field/) in Shopware are organised in sets. Here you need to consider some important fields:

* `name`: A technical name for your set
* `label`: This element provides the label of the text and can be used for defining translations of the label as well.
* `related-entities`: With this element set the entities the custom field set is used in
* `fields`: Finally, the fields are configured in this section.

::: warning
The names of the custom fields are global and therefore should always contain a vendor prefix, like "swag" for "shopware ag", to keep them unique. This holds true for the name of the custom field set, as well as each name of the fields itself.
:::

When defining custom fields in the `<fields>` element, you can configure additional properties of the fields. For example a `placeholder`, `min`, `max` and `step` size of a float field:

```html
<float name="swag_test_float_field">
    <label>Test float field</label>
    <label lang="de-DE">Test-Kommazahlenfeld</label>
    <help-text>This is an float field.</help-text>
    <position>2</position>
    <placeholder>Enter an float...</placeholder>
    <min>0.5</min>
    <max>1.6</max>
    <steps>0.2</steps>
</float>
```

Refer to the [custom field](../../plugins/framework/custom-field/) documentation for further details.

---

---
url: /docs/guides/plugins/apps/custom-data/custom-fields.md
---

# Custom Data Fields

## Overview

You can add custom fields to Shopware and thus add your own fields to extending data records. The user is able to modify this fields from within the Shopware Administration.

To make use of the custom fields, register your custom field sets in your manifest file:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        ...
    </meta>
    <custom-fields>
        <custom-field-set>
            <name>swag_example_set</name>
            <label>Example Set</label>
            <label lang="de-DE">Beispiel-Set</label>
            <related-entities>
                <order/>
            </related-entities>
            <fields>
                <text name="swag_code">
                    <position>1</position>
                    <label>Example field</label>
                </text>
            </fields>
        </custom-field-set>
    </custom-fields>
</manifest>

```

For a complete reference of the structure of the manifest file, take a look at the [Manifest reference](../../../../resources/references/app-reference/manifest-reference.md).

::: warning
Defining custom fields inline in `manifest.xml` via the `<custom-fields>` element is deprecated since Shopware 6.7.13.0 and will be removed in Shopware 6.8.0.0. Define your custom fields in a separate `Resources/config/custom-fields.xml` file instead (see below).
:::

## Defining custom fields in `Resources/config/custom-fields.xml`

::: info
Available starting with Shopware 6.7.13.0.
:::

Instead of the inline `<custom-fields>` section in `manifest.xml`, you can define your custom field sets in a dedicated `Resources/config/custom-fields.xml` file at the root of your app. The format inside `<custom-fields>` is identical to the inline manifest definition:

```xml
<?xml version="1.0" encoding="UTF-8"?>
<custom-fields xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
               xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/CustomField/Schema/custom-fields-1.0.xsd">
    <!-- register each custom field set you may want to add -->
    <custom-field-set>
        <!-- the technical name of the custom field set, needs to be unique, therefore use your vendor prefix -->
        <name>swag_example_set</name>
        <!-- Translatable, the label of the field set -->
        <label>Example Set</label>
        <label lang="de-DE">Beispiel-Set</label>
        <!-- define the entities to which your field set should be assigned -->
        <related-entities>
            <product/>
        </related-entities>
        <!-- define the fields in your set -->
        <fields>
            <!-- the element type defines the type of the field -->
            <!-- the name needs to be unique, therefore use your vendor prefix -->
            <int name="swag_example_weight">
                <!-- Translatable, the label of the field -->
                <label>Weight</label>
                <!-- Optional, Default = 1, order your fields by specifying the position -->
                <position>1</position>
            </int>
            <text name="swag_example_code">
                <label>Example field</label>
                <position>2</position>
                <!-- Optional, Default = false, mark a field as required -->
                <required>false</required>
                <!-- Optional, Translatable, the help text for the field -->
                <help-text>Example field</help-text>
            </text>
        </fields>
    </custom-field-set>
</custom-fields>

```

When both a `Resources/config/custom-fields.xml` file and an inline `<custom-fields>` section in `manifest.xml` are present, the separate file takes priority. If only the inline definition exists, a deprecation warning is triggered. The same file format is also available for [plugins](../../plugins/framework/custom-field/add-custom-field.md#declarative-custom-fields-via-resources-config-custom-fields-xml).

For the data needed, please refer to the custom fields in general: At first, you need a custom field set, as [custom fields](../../plugins/framework/custom-field/index.md) in Shopware are organised in sets. Here you need to consider some important fields:

* `name`: A technical name for your set
* `label`: This element provides the label of the text and can be used for defining translations of the label as well.
* `related-entities`: With this element set the entities the custom field set is used in
* `fields`: Finally, the fields are configured in this section.

::: warning
The names of the custom fields are global and therefore should always contain a vendor prefix, like "swag" for "shopware ag", to keep them unique. This holds true for the name of the custom field set, as well as each name of the fields itself.
:::

When defining custom fields in the `<fields>` element, you can configure additional properties of the fields. For example a `placeholder`, `min`, `max` and `step` size of a float field:

```html
<float name="swag_test_float_field">
    <label>Test float field</label>
    <label lang="de-DE">Test-Kommazahlenfeld</label>
    <help-text>This is an float field.</help-text>
    <position>2</position>
    <placeholder>Enter an float...</placeholder>
    <min>0.5</min>
    <max>1.6</max>
    <steps>0.2</steps>
</float>
```

Refer to the [custom field](../../plugins/framework/custom-field/index.md) documentation for further details.

---

---
url: /docs/resources/references/testing-reference/e2e-custom-commands.md
---

# Custom E2E Commands

## General commands

| Command | Parameter | Description |
| :--- | :--- | :--- |
| setLocaleToEnGb | - | Switches administration UI locale to EN\_GB |
| login | `(userType)` | Logs in to the Administration manually |
| typeAndCheck | `(textToType)` | Types in an input element and checks if the content was correctly typed |
| clearTypeAndCheck | `(textToType)` | Clears field, types in an input element and checks if the content was correctly typed |
| typeMultiSelectAndCheck | `(textToType, { searchTerm: searchTerm })` | Types in a sw-select field and checks if the content was correctly typed (multi select) |
| typeSingleSelect | `(textToType, selector)` | Types in an sw-select field (single select) |
| typeSingleSelectAndCheck | `(textToType, selector)` | Types in an sw-select field and checks if the content was correctly typed (single select) |
| typeLegacySelectAndCheck | `(textToType, { searchTerm: searchTerm })` | Types in an legacy swSelect field and checks if the content was correctly typed |
| typeAndCheckSearchField | `(searchTerm)` | Types in the global search field and verify search terms in url |
| awaitAndCheckNotification | `(message)` | Wait for a notification to appear and check its message |
| clickContextMenuItem | `(actionInMenuSelector, openMenuSelector, scope = '')` | Click context menu in order to cause a desired action |
| clickMainMenuItem | `({ targetPath, mainMenuId, subMenuId })` | Navigate to module by clicking the corresponding main menu item |
| openUserActionMenu | `({ targetPath, mainMenuId, subMenuId })` | Click user menu to open it up |
| dragTo | `(target)` | Drags the previous subject element to a target, performing a drag and drop operation |
| onlyOnFeature | `(feature)` | Only run the test (skip otherwise) if the feature is activated |
| skipOnFeature | `(feature)` | Skip the test if the feature is activated |

## Storefront-related / Sales Channel API commands

| Command | Parameter | Description |
| :--- | :--- | :--- |
| getSalesChannelId | - | Get the sales channel Id via Admin API |
| storefrontApiRequest | `(method, endpoint, header = {}, body = {})` | Performs Storefront API Requests |
| getRandomProductInformationForCheckout | - | Returns random product with id, name and url to view product |

## System Commands

| Command | Parameter | Description |
| :--- | :--- | :--- |
| activateShopwareTheme | - | Activates Shopware theme for Cypress test runner |
| cleanUpPreviousState | - | Cleans up any previous state by restoring database and clearing caches |
| openInitialPage | - | Opens up the administration initially and waits for the "me" call to be successful |

## API commands

| Command | Parameter | Description |
| :--- | :--- | :--- |
| authenticate | - | Authenticate towards the Shopware API |
| loginViaApi | - | Logs in silently using Shopware API |
| searchViaAdminApi | `(data)` | Search for an existing entity using Shopware API at the given endpoint |
| requestAdminApi | `(method, url, requestData)` | Handling API requests |
| updateViaAdminApi | `(endpoint, id, data)` | Updates an existing entity using Shopware API at the given endpoint |

## Fixture commands

| Command | Parameter | Description |
| :--- | :--- | :--- |
| setToInitialState | - | Sets Shopware back to its initial state if using platform E2E backup routine |
| createDefaultFixture | `(endpoint, data = {}, jsonPath)` | Create entity using Shopware API via given endpoint |
| createProductFixture | `(userData = {})` | Create product fixture using Shopware API via given endpoint |
| createCategoryFixture | `(userData = {})` | Create category fixture using Shopware API via given endpoint |
| createSalesChannelFixture | `(userData = {}` | Create sales channel fixture using Shopware API via given endpoint |
| setSalesChannelDomain | `(salesChannelName = 'Storefront')` | Create sales channel domain using Shopware API at the given endpoint |
| createCustomerFixture | `(userData = {})` | Create customer fixture using Shopware API via given endpoint |
| createCmsFixture | `(userData = {})` | Create cms fixture using Shopware API at the given endpoint |
| createPropertyFixture | `(options, userData)` | Create property fixture using Shopware API at the given endpoint |
| createLanguageFixture | - | Create language fixture using Shopware API at the given endpoint |
| createShippingFixture | `(userData)` | Create shipping fixture using Shopware API at the given endpoint |
| createSnippetFixture | - | Create snippet fixture using Shopware API at the given endpoint |
| createGuestOrder | `productId, userData)` | Create guest order fixture |
| setProductFixtureVisibility | `(productName, categoryName)` | Sets category and visibility for a product in order to set it visible in the Storefront |

---

---
url: /docs/v6.5/resources/references/testing-reference/e2e-custom-commands.md
---

# Custom E2E Commands

## General commands

| Command | Parameter | Description |
| :--- | :--- | :--- |
| setLocaleToEnGb | - | Switches administration UI locale to EN\_GB |
| login | `(userType)` | Logs in to the Administration manually |
| typeAndCheck | `(textToType)` | Types in an input element and checks if the content was correctly typed |
| clearTypeAndCheck | `(textToType)` | Clears field, types in an input element and checks if the content was correctly typed |
| typeMultiSelectAndCheck | `(textToType, { searchTerm: searchTerm })` | Types in a sw-select field and checks if the content was correctly typed (multi select) |
| typeSingleSelect | `(textToType, selector)` | Types in an sw-select field (single select) |
| typeSingleSelectAndCheck | `(textToType, selector)` | Types in an sw-select field and checks if the content was correctly typed (single select) |
| typeLegacySelectAndCheck | `(textToType, { searchTerm: searchTerm })` | Types in an legacy swSelect field and checks if the content was correctly typed |
| typeAndCheckSearchField | `(searchTerm)` | Types in the global search field and verify search terms in url |
| awaitAndCheckNotification | `(message)` | Wait for a notification to appear and check its message |
| clickContextMenuItem | `(actionInMenuSelector, openMenuSelector, scope = '')` | Click context menu in order to cause a desired action |
| clickMainMenuItem | `({ targetPath, mainMenuId, subMenuId })` | Navigate to module by clicking the corresponding main menu item |
| openUserActionMenu | `({ targetPath, mainMenuId, subMenuId })` | Click user menu to open it up |
| dragTo | `(target)` | Drags the previous subject element to a target, performing a drag and drop operation |
| onlyOnFeature | `(feature)` | Only run the test (skip otherwise) if the feature is activated |
| skipOnFeature | `(feature)` | Skip the test if the feature is activated |

## Storefront-related / Sales Channel API commands

| Command | Parameter | Description |
| :--- | :--- | :--- |
| getSalesChannelId | - | Get the sales channel Id via Admin API |
| storefrontApiRequest | `(method, endpoint, header = {}, body = {})` | Performs Storefront API Requests |
| getRandomProductInformationForCheckout | - | Returns random product with id, name and url to view product |

## System Commands

| Command | Parameter | Description |
| :--- | :--- | :--- |
| activateShopwareTheme | - | Activates Shopware theme for Cypress test runner |
| cleanUpPreviousState | - | Cleans up any previous state by restoring database and clearing caches |
| openInitialPage | - | Opens up the administration initially and waits for the "me" call to be successful |

## API commands

| Command | Parameter | Description |
| :--- | :--- | :--- |
| authenticate | - | Authenticate towards the Shopware API |
| loginViaApi | - | Logs in silently using Shopware API |
| searchViaAdminApi | `(data)` | Search for an existing entity using Shopware API at the given endpoint |
| requestAdminApi | `(method, url, requestData)` | Handling API requests |
| updateViaAdminApi | `(endpoint, id, data)` | Updates an existing entity using Shopware API at the given endpoint |

## Fixture commands

| Command | Parameter | Description |
| :--- | :--- | :--- |
| setToInitialState | - | Sets Shopware back to its initial state if using platform E2E backup routine |
| createDefaultFixture | `(endpoint, data = {}, jsonPath)` | Create entity using Shopware API via given endpoint |
| createProductFixture | `(userData = {})` | Create product fixture using Shopware API via given endpoint |
| createCategoryFixture | `(userData = {})` | Create category fixture using Shopware API via given endpoint |
| createSalesChannelFixture | `(userData = {}` | Create sales channel fixture using Shopware API via given endpoint |
| setSalesChannelDomain | `(salesChannelName = 'Storefront')` | Create sales channel domain using Shopware API at the given endpoint |
| createCustomerFixture | `(userData = {})` | Create customer fixture using Shopware API via given endpoint |
| createCmsFixture | `(userData = {})` | Create cms fixture using Shopware API at the given endpoint |
| createPropertyFixture | `(options, userData)` | Create property fixture using Shopware API at the given endpoint |
| createLanguageFixture | - | Create language fixture using Shopware API at the given endpoint |
| createShippingFixture | `(userData)` | Create shipping fixture using Shopware API at the given endpoint |
| createSnippetFixture | - | Create snippet fixture using Shopware API at the given endpoint |
| createGuestOrder | `productId, userData)` | Create guest order fixture |
| setProductFixtureVisibility | `(productName, categoryName)` | Sets category and visibility for a product in order to set it visible in the Storefront |

---

---
url: /docs/v6.6/resources/references/testing-reference/e2e-custom-commands.md
---

# Custom E2E Commands

## General commands

| Command | Parameter | Description |
| :--- | :--- | :--- |
| setLocaleToEnGb | - | Switches administration UI locale to EN\_GB |
| login | `(userType)` | Logs in to the Administration manually |
| typeAndCheck | `(textToType)` | Types in an input element and checks if the content was correctly typed |
| clearTypeAndCheck | `(textToType)` | Clears field, types in an input element and checks if the content was correctly typed |
| typeMultiSelectAndCheck | `(textToType, { searchTerm: searchTerm })` | Types in a sw-select field and checks if the content was correctly typed (multi select) |
| typeSingleSelect | `(textToType, selector)` | Types in an sw-select field (single select) |
| typeSingleSelectAndCheck | `(textToType, selector)` | Types in an sw-select field and checks if the content was correctly typed (single select) |
| typeLegacySelectAndCheck | `(textToType, { searchTerm: searchTerm })` | Types in an legacy swSelect field and checks if the content was correctly typed |
| typeAndCheckSearchField | `(searchTerm)` | Types in the global search field and verify search terms in url |
| awaitAndCheckNotification | `(message)` | Wait for a notification to appear and check its message |
| clickContextMenuItem | `(actionInMenuSelector, openMenuSelector, scope = '')` | Click context menu in order to cause a desired action |
| clickMainMenuItem | `({ targetPath, mainMenuId, subMenuId })` | Navigate to module by clicking the corresponding main menu item |
| openUserActionMenu | `({ targetPath, mainMenuId, subMenuId })` | Click user menu to open it up |
| dragTo | `(target)` | Drags the previous subject element to a target, performing a drag and drop operation |
| onlyOnFeature | `(feature)` | Only run the test (skip otherwise) if the feature is activated |
| skipOnFeature | `(feature)` | Skip the test if the feature is activated |

## Storefront-related / Sales Channel API commands

| Command | Parameter | Description |
| :--- | :--- | :--- |
| getSalesChannelId | - | Get the sales channel Id via Admin API |
| storefrontApiRequest | `(method, endpoint, header = {}, body = {})` | Performs Storefront API Requests |
| getRandomProductInformationForCheckout | - | Returns random product with id, name and url to view product |

## System Commands

| Command | Parameter | Description |
| :--- | :--- | :--- |
| activateShopwareTheme | - | Activates Shopware theme for Cypress test runner |
| cleanUpPreviousState | - | Cleans up any previous state by restoring database and clearing caches |
| openInitialPage | - | Opens up the administration initially and waits for the "me" call to be successful |

## API commands

| Command | Parameter | Description |
| :--- | :--- | :--- |
| authenticate | - | Authenticate towards the Shopware API |
| loginViaApi | - | Logs in silently using Shopware API |
| searchViaAdminApi | `(data)` | Search for an existing entity using Shopware API at the given endpoint |
| requestAdminApi | `(method, url, requestData)` | Handling API requests |
| updateViaAdminApi | `(endpoint, id, data)` | Updates an existing entity using Shopware API at the given endpoint |

## Fixture commands

| Command | Parameter | Description |
| :--- | :--- | :--- |
| setToInitialState | - | Sets Shopware back to its initial state if using platform E2E backup routine |
| createDefaultFixture | `(endpoint, data = {}, jsonPath)` | Create entity using Shopware API via given endpoint |
| createProductFixture | `(userData = {})` | Create product fixture using Shopware API via given endpoint |
| createCategoryFixture | `(userData = {})` | Create category fixture using Shopware API via given endpoint |
| createSalesChannelFixture | `(userData = {}` | Create sales channel fixture using Shopware API via given endpoint |
| setSalesChannelDomain | `(salesChannelName = 'Storefront')` | Create sales channel domain using Shopware API at the given endpoint |
| createCustomerFixture | `(userData = {})` | Create customer fixture using Shopware API via given endpoint |
| createCmsFixture | `(userData = {})` | Create cms fixture using Shopware API at the given endpoint |
| createPropertyFixture | `(options, userData)` | Create property fixture using Shopware API at the given endpoint |
| createLanguageFixture | - | Create language fixture using Shopware API at the given endpoint |
| createShippingFixture | `(userData)` | Create shipping fixture using Shopware API at the given endpoint |
| createSnippetFixture | - | Create snippet fixture using Shopware API at the given endpoint |
| createGuestOrder | `productId, userData)` | Create guest order fixture |
| setProductFixtureVisibility | `(productName, categoryName)` | Sets category and visibility for a product in order to set it visible in the Storefront |

---

---
url: /frontends/guides/cms/custom-elements.md
---

# Custom Elements (CMS)

:::warning
This tutorial is a continuation of example from the backend part. That can be found [here](https://developer.shopware.com/docs/guides/plugins/plugins/content/cms/add-cms-element.html)
:::

All custom CMS elements created in the backend require corresponding implementations in the frontend application.

The CMS package utilizes the [resolveComponent](https://vuejs.org/api/render-function#resolvecomponent) method from Vue to identify the component returned by the backend API.
Therefore, the only requirement is to globally register the component with the appropriate name.

## Registration

### Demo store

Templates register `app/components/cms/` as a Nuxt **global** component directory so Vue `resolveComponent` can find CMS blocks and elements. Put custom CMS components there (not only under a non-global `components/` path).

### Vue apps

[Global registration](https://vuejs.org/guide/components/registration#global-registration) in Vue apps

```ts
import CmsBlockCustomBlock from "./components/cms/CmsElementDailymotion.vue";

app.component("CmsElementDailymotion", CmsBlockCustomBlock);
```

## Naming

The component is searched in the global component register by its name.

[Resolving component in CMS package](https://github.com/shopware/frontends/blob/main/packages/composables/src/index.ts#L74)

```js
const componentNameToResolve = pascalCase(`Cms-${type}-${componentName}`);
const resolvedComponent = resolveComponent(componentNameToResolve);
```

Component name must be the same as it was registered in the backed.

```ts{3}
Shopware.Service('cmsService').registerCmsElement({
    ...
    name: 'dailymotion',
    ...
});
```

Lets create new component `components/cms/element/CmsElementDailymotion.vue`

```vue
// components/cms/element/CmsElementDailymotion.vue
<script setup lang="ts">
import type { Schemas } from "#showpare";

type CmsElementDailymotion = Schemas["CmsSlot"] & {
  type: "dailymotion" | typeof String;
  slot: typeof String;
  config: CmsElementDailymotionConfig;
  translated: {
    config: CmsElementDailymotionConfig;
  };
};

type CmsElementDailymotionConfig = {
  dailyUrl: {
    value: string;
    source: "static";
  };
};
const props = defineProps<{
  content: CmsElementDailymotion;
}>();
</script>

<template>
  <div>
    <h2>Element!</h2>
    <div class="sw-cms-el-dailymotion">
      <div class="sw-cms-el-dailymotion-iframe-wrapper">
        <iframe
          frameborder="0"
          type="text/html"
          width="100%"
          height="100%"
          :src="props.content.config.dailyUrl.value"
        >
        </iframe>
      </div>
    </div>
  </div>
</template>
```

### Reading config

Component settings are passed via props. The declared `defaultConfig` can be accessed through the `props.content.config` property.

The following is an example of how to convert the backend registration config to a TypeScript type.

```ts{4-9}
Shopware.Service('cmsService').registerCmsElement({
  ...
    name: 'dailymotion',
    defaultConfig: {
        dailyUrl: {
            source: 'static',
            value: ''
        }
    }
  ...
});
```

```ts
type CmsElementDailymotionConfig = {
  dailyUrl: {
    value: string;
    source: "static";
  };
};
```

---

---
url: >-
  /docs/resources/references/app-reference/script-reference/custom-endpoint-script-services-reference.md
---

# Custom Endpoint script services reference

## [services.cache (`Shopware\Core\Framework\Adapter\Cache\Script\Facade\CacheInvalidatorFacade`)](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/Adapter/Cache/Script/Facade/CacheInvalidatorFacade.php) {#cacheinvalidatorfacade}

The `cache` service allows you to invalidate the cache if some entity is updated.

### invalidate()

* `invalidate()` allows you to invalidate all cache entries with the given tag.

* **Arguments:**
  * *`array`* **tags**: The tags for which all cache entries should be invalidated as array.

* **Examples:**
  * Invalidate a hard coded tag.

    ```twig
    {% do services.cache.invalidate(['my-tag']) %}
    ```
  * Build tags based on written entities and invalidate those tags.

    ```twig
    {% set ids = hook.event.getIds('product_manufacturer') %}

    {% if ids.empty %}
        {% return %}
    {% endif %}

    {% set tags = [] %}
    {% for id in ids %}
        {% set tags = tags|merge(['my-manufacturer-' ~ id]) %}
    {% endfor %}

    {% do services.cache.invalidate(tags) %}
    ```
  * Build tags if products with a specific property is created and invalidate those tags.

    ```twig
    {% set ids = hook.event.getIds('product') %}

    {% set ids = ids.only('insert').with('description', 'parentId') %}
    {% if ids.empty %}
        {% return %}
    {% endif %}

    {% set tags = [] %}
    {% for id in ids %}
        {% set tags = tags|merge(['my-product-' ~ id]) %}
    {% endfor %}

    {% do services.cache.invalidate(tags) %}
    ```

***

## [services.writer (`Shopware\Core\Framework\DataAbstractionLayer\Facade\RepositoryWriterFacade`)](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Facade/RepositoryWriterFacade.php) {#repositorywriterfacade}

The `writer` service allows you to write data, that is stored inside shopware.
Keep in mind that your app needs to have the correct permissions for the data it writes through this service.

### delete()

* The `delete()` method allows you to delete entities from the database.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Event\EntityWrittenContainerEvent`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Event/EntityWrittenContainerEvent.php)

  The WriteEvents that were generated by executing the `delete()`.

* **Arguments:**
  * *`string`* **entityName**: The name of the entity you want to delete, e.g. `product` or `media`.
  * *`array`* **payload**: The primary keys of the entities you want to delete, as a list of associative arrays, associative array represents the primary keys for one entity.

* **Examples:**
  * Delete an entity.

    ```twig
    {% do services.writer.delete('product', [
        { 'id':  hook.productId }
    ]) %}
    ```

### sync()

* The `sync()` method allows you to execute updates and deletes to multiple entities in one method call.

* **Returns** [`Shopware\Core\Framework\Api\Sync\SyncResult`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/Api/Sync/SyncResult.php)

  The result of the `sync()`.

* **Arguments:**
  * *`array`* **payload**: All operations that should be executed.

* **Examples:**
  * Update an entity and delete another one with one `sync()` call.

    ```twig
    {% set payload = [
        {
            'entity': 'product',
            'action': 'upsert',
            'payload': [
                { 'id':  hook.updateProductId, 'active': true }
            ]
        },
        {
            'entity': 'product',
            'action': 'delete',
            'payload': [
            { 'id':  hook.deleteProductId }
        ]
        },
    ] %}

    {% do services.writer.sync(payload) %}
    ```

### upsert()

* The `upsert()` method allows you to create or update entities inside the database.

  If you pass an `id` in the payload it will do an update if an entity with that `id` already exists, otherwise it will be a create.
* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Event\EntityWrittenContainerEvent`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Event/EntityWrittenContainerEvent.php)

  The WriteEvents that were generated by executing the `upsert()`.
* **Arguments:**
  * *`string`* **entityName**: The name of the entity you want to upsert, e.g. `product` or `media`.
  * *`array`* **payload**: The payload you want to upsert, as a list of associative arrays, where each associative array represents the payload for one entity.
* **Examples:**
  * Create a new entity.

    ```twig
    {% do services.writer.upsert('tax', [
        { 'name': 'new Tax', 'taxRate': 99.9 }
    ]) %}
    ```
  * Update an existing entity.

    ```twig
    {% do services.writer.upsert('product', [
        { 'id':  hook.productId, 'active': true }
    ]) %}
    ```

***

## [services.response (`Shopware\Core\Framework\Script\Api\ScriptResponseFactoryFacade`)](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/Script/Api/ScriptResponseFactoryFacade.php) {#scriptresponsefactoryfacade}

The `response` service allows you to create HTTP-Responses.

### json()

* The `json()` method allows you to create a JSON-Response.

* **Returns** [`Shopware\Core\Framework\Script\Api\ScriptResponse`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/Script/Api/ScriptResponse.php)

  The created response object, remember to assign it to the hook with `hook.setResponse()`.

* **Arguments:**
  * *`array`* **data**: The data that should be sent in the response as array.
  * *`int`* **code**: The HTTP-Status-Code of the response, defaults to 200.

    Default: `200`

* **Examples:**
  * Return hard coded values as JsonResponse.

    ```twig
    {% set response = services.response.json({ 'foo': 'bar' }) %}
    {% do hook.setResponse(response) %}
    ```
  * Search for products and return them in a JsonResponse.

    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}
    {% set products = services.repository.search('product', hook.request) %}

    {% set response = services.response.json({ 'products': products }) %}
    {% do hook.setResponse(response) %}
    ```
  * Provide a response to a ActionButtons request from the administration.

    ```twig
    {% set ids = hook.request.ids %}

    {% set response = services.response.json({
        "actionType": "notification",
        "payload": {
            "status": "success",
            "message": "You selected " ~ ids|length ~ " products."
        }
    }) %}

    {% do hook.setResponse(response) %}
    ```

### redirect()

* The `redirect()` method allows you to create a RedirectResponse.

* **Returns** [`Shopware\Core\Framework\Script\Api\ScriptResponse`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/Script/Api/ScriptResponse.php)

  The created response object, remember to assign it to the hook with `hook.setResponse()`.

* **Arguments:**
  * *`string`* **route**: The name of the route that should be redirected to.
  * *`array`* **parameters**: The parameters needing to generate the URL of the route as an associative array.
  * *`int`* **code**: he HTTP-Status-Code of the response, defaults to 302.

    Default: `302`

* **Examples:**
  * Redirect to an Admin-API route.

    ```twig
    {% set response = services.response.redirect('api.product.detail', { 'path': productId }) %}
    {% do hook.setResponse(response) %}
    ```
  * Redirect to a storefront page.

    ```twig
    {% set response = services.response.redirect('frontend.detail.page', { 'productId': productId }) %}
    {% do hook.setResponse(response) %}
    ```

### render()

**Deprecated:** tag:v6.8.0 - Rendering Storefront templates through the core response service is deprecated. Type the response service as `Shopware\Storefront\Framework\Script\Api\StorefrontScriptResponseFactoryFacade` in Storefront script hooks and use this core facade without `render()` in admin-api/store-api hooks.

* The `render()` method allows you to render a twig view with the parameters you provide and create a StorefrontResponse.

  Note that the `render()` method will throw an exception if it is called from outside a `SalesChannelContext` (e.g. from an `/api` route)
  or if the Storefront-bundle is not installed.
* **Returns** [`Shopware\Core\Framework\Script\Api\ScriptResponse`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/Script/Api/ScriptResponse.php)

  The created response object with the rendered template as content, remember to assign it to the hook with `hook.setResponse()`.
* **Arguments:**
  * *`string`* **view**: The name of the twig template you want to render e.g. `@Storefront/storefront/page/content/detail.html.twig`
  * *`array`* **parameters**: The parameters you want to pass to the template, ensure that you pass the `page` parameter from the hook to the templates.

    Default: `array (
    )`
* **Examples:**
  * Fetch a product, add it to the page and return a rendered response.

    ```twig
    {% set product = services.store.search('product', { 'ids': [productId]}).getEntities().first %}

    {% do hook.page.addExtension('myProduct', product) %}

    {% set response = services.response.render('@MyApp/storefront/page/custom-page/index.html.twig', { 'page': hook.page }) %}
    {% do response.setHeader("Content-Type", "text/plain") %}

    {% do hook.setResponse(response) %}
    ```

***

---

---
url: >-
  /docs/v6.5/resources/references/app-reference/script-reference/custom-endpoint-script-services-reference.md
---

# Custom Endpoint script services reference

## [services.cache (`Shopware\Core\Framework\Adapter\Cache\Script\Facade\CacheInvalidatorFacade`)](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/Adapter/Cache/Script/Facade/CacheInvalidatorFacade.php) {#cacheinvalidatorfacade}

The `cache` service allows you to invalidate the cache if some entity is updated.

### invalidate()

* `invalidate()` allows you to invalidate all cache entries with the given tag.

* **Arguments:**
  * *`array`* **tags**: The tags for which all cache entries should be invalidated as array.

* **Examples:**
  * Invalidate a hard coded tag.

    ```twig
    {% do services.cache.invalidate(['my-tag']) %}
    ```

  * Build tags based on written entities and invalidate those tags.

    ```twig
    {% set ids = hook.event.getIds('product_manufacturer') %}

    {% if ids.empty %}
        {% return %}
    {% endif %}

    {% set tags = [] %}
    {% for id in ids %}
        {% set tags = tags|merge(['my-manufacturer-' ~ id]) %}
    {% endfor %}

    {% do services.cache.invalidate(tags) %}
    ```

  * Build tags if products with a specific property is created and invalidate those tags.

    ```twig
    {% set ids = hook.event.getIds('product') %}

    {% set ids = ids.only('insert').with('description', 'parentId') %}
    {% if ids.empty %}
        {% return %}
    {% endif %}

    {% set tags = [] %}
    {% for id in ids %}
        {% set tags = tags|merge(['my-product-' ~ id]) %}
    {% endfor %}

    {% do services.cache.invalidate(tags) %}
    ```

***

## [services.writer (`Shopware\Core\Framework\DataAbstractionLayer\Facade\RepositoryWriterFacade`)](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Facade/RepositoryWriterFacade.php) {#repositorywriterfacade}

The `writer` service allows you to write data, that is stored inside shopware.
Keep in mind that your app needs to have the correct permissions for the data it writes through this service.

### upsert()

* The `upsert()` method allows you to create or update entities inside the database.

  If you pass an `id` in the payload it will do an update if an entity with that `id` already exists, otherwise it will be a create.
* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Event\EntityWrittenContainerEvent`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Event/EntityWrittenContainerEvent.php)

  The WriteEvents that were generated by executing the `upsert()`.
* **Arguments:**
  * *`string`* **entityName**: The name of the entity you want to upsert, e.g. `product` or `media`.
  * *`array`* **payload**: The payload you want to upsert, as a list of associative arrays, where each associative array represents the payload for one entity.
* **Examples:**
  * Create a new entity.

    ```twig
    {% do services.writer.upsert('tax', [
        { 'name': 'new Tax', 'taxRate': 99.9 }
    ]) %}
    ```

  * Update an existing entity.

    ```twig
    {% do services.writer.upsert('product', [
        { 'id':  hook.productId, 'active': true }
    ]) %}
    ```

### delete()

* The `delete()` method allows you to delete entities from the database.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Event\EntityWrittenContainerEvent`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Event/EntityWrittenContainerEvent.php)

  The WriteEvents that were generated by executing the `delete()`.

* **Arguments:**
  * *`string`* **entityName**: The name of the entity you want to delete, e.g. `product` or `media`.
  * *`array`* **payload**: The primary keys of the entities you want to delete, as a list of associative arrays, associative array represents the primary keys for one entity.

* **Examples:**
  * Delete an entity.

    ```twig
    {% do services.writer.delete('product', [
        { 'id':  hook.productId }
    ]) %}
    ```

### sync()

* The `sync()` method allows you to execute updates and deletes to multiple entities in one method call.

* **Returns** [`Shopware\Core\Framework\Api\Sync\SyncResult`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/Api/Sync/SyncResult.php)

  The result of the `sync()`.

* **Arguments:**
  * *`array`* **payload**: All operations that should be executed.

* **Examples:**
  * Update an entity and delete another one with one `sync()` call.

    ```twig
    {% set payload = [
        {
            'entity': 'product',
            'action': 'upsert',
            'payload': [
                { 'id':  hook.updateProductId, 'active': true }
            ]
        },
        {
            'entity': 'product',
            'action': 'delete',
            'payload': [
            { 'id':  hook.deleteProductId }
        ]
        },
    ] %}

    {% do services.writer.sync(payload) %}
    ```

***

## [services.response (`Shopware\Core\Framework\Script\Api\ScriptResponseFactoryFacade`)](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/Script/Api/ScriptResponseFactoryFacade.php) {#scriptresponsefactoryfacade}

The `response` service allows you to create HTTP-Responses.

### json()

* The `json()` method allows you to create a JSON-Response.

* **Returns** [`Shopware\Core\Framework\Script\Api\ScriptResponse`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/Script/Api/ScriptResponse.php)

  The created response object, remember to assign it to the hook with `hook.setResponse()`.

* **Arguments:**
  * *`array`* **data**: The data that should be sent in the response as array.
  * *`int`* **code**: The HTTP-Status-Code of the response, defaults to 200.

    Default: `200`

* **Examples:**
  * Return hard coded values as JsonResponse.

    ```twig
    {% set response = services.response.json({ 'foo': 'bar' }) %}
    {% do hook.setResponse(response) %}
    ```

  * Search for products and return them in a JsonResponse.

    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}
    {% set products = services.repository.search('product', hook.request) %}

    {% set response = services.response.json({ 'products': products }) %}
    {% do hook.setResponse(response) %}
    ```

  * Provide a response to a ActionButtons request from the administration.

    ```twig
    {% set ids = hook.request.ids %}

    {% set response = services.response.json({
        "actionType": "notification",
        "payload": {
            "status": "success",
            "message": "You selected " ~ ids|length ~ " products."
        }
    }) %}

    {% do hook.setResponse(response) %}
    ```

### redirect()

* The `redirect()` method allows you to create a RedirectResponse.

* **Returns** [`Shopware\Core\Framework\Script\Api\ScriptResponse`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/Script/Api/ScriptResponse.php)

  The created response object, remember to assign it to the hook with `hook.setResponse()`.

* **Arguments:**
  * *`string`* **route**: The name of the route that should be redirected to.
  * *`array`* **parameters**: The parameters needing to generate the URL of the route as an associative array.
  * *`int`* **code**: he HTTP-Status-Code of the response, defaults to 302.

    Default: `302`

* **Examples:**
  * Redirect to an Admin-API route.

    ```twig
    {% set response = services.response.redirect('api.product.detail', { 'path': productId }) %}
    {% do hook.setResponse(response) %}
    ```

  * Redirect to a storefront page.

    ```twig
    {% set response = services.response.redirect('frontend.detail.page', { 'productId': productId }) %}
    {% do hook.setResponse(response) %}
    ```

### render()

* The `render()` method allows you to render a twig view with the parameters you provide and create a StorefrontResponse.

  Note that the `render()` method will throw an exception if it is called from outside a `SalesChannelContext` (e.g. from an `/api` route)
  or if the Storefront-bundle is not installed.
* **Returns** [`Shopware\Core\Framework\Script\Api\ScriptResponse`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/Script/Api/ScriptResponse.php)

  The created response object with the rendered template as content, remember to assign it to the hook with `hook.setResponse()`.
* **Arguments:**
  * *`string`* **view**: The name of the twig template you want to render e.g. `@Storefront/storefront/page/content/detail.html.twig`
  * *`array`* **parameters**: The parameters you want to pass to the template, ensure that you pass the `page` parameter from the hook to the templates.

    Default: `array (
    )`
* **Examples:**
  * Fetch a product, add it to the page and return a rendered response.

    ```twig
    {% set product = services.store.search('product', { 'ids': [productId]}).first %}

    {% do hook.page.addExtension('myProduct', product) %}

    {% do hook.setResponse(
        services.response.render('@MyApp/storefront/page/custom-page/index.html.twig', { 'page': hook.page })
    ) %}
    ```

***

---

---
url: >-
  /docs/v6.6/resources/references/app-reference/script-reference/custom-endpoint-script-services-reference.md
---

# Custom Endpoint script services reference

## [services.cache (`Shopware\Core\Framework\Adapter\Cache\Script\Facade\CacheInvalidatorFacade`)](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/Adapter/Cache/Script/Facade/CacheInvalidatorFacade.php) {#cacheinvalidatorfacade}

The `cache` service allows you to invalidate the cache if some entity is updated.

### invalidate()

* `invalidate()` allows you to invalidate all cache entries with the given tag.

* **Arguments:**
  * *`array`* **tags**: The tags for which all cache entries should be invalidated as array.

* **Examples:**
  * Invalidate a hard coded tag.

    ```twig
    {% do services.cache.invalidate(['my-tag']) %}
    ```

  * Build tags based on written entities and invalidate those tags.

    ```twig
    {% set ids = hook.event.getIds('product_manufacturer') %}

    {% if ids.empty %}
        {% return %}
    {% endif %}

    {% set tags = [] %}
    {% for id in ids %}
        {% set tags = tags|merge(['my-manufacturer-' ~ id]) %}
    {% endfor %}

    {% do services.cache.invalidate(tags) %}
    ```

  * Build tags if products with a specific property is created and invalidate those tags.

    ```twig
    {% set ids = hook.event.getIds('product') %}

    {% set ids = ids.only('insert').with('description', 'parentId') %}
    {% if ids.empty %}
        {% return %}
    {% endif %}

    {% set tags = [] %}
    {% for id in ids %}
        {% set tags = tags|merge(['my-product-' ~ id]) %}
    {% endfor %}

    {% do services.cache.invalidate(tags) %}
    ```

***

## [services.writer (`Shopware\Core\Framework\DataAbstractionLayer\Facade\RepositoryWriterFacade`)](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Facade/RepositoryWriterFacade.php) {#repositorywriterfacade}

The `writer` service allows you to write data, that is stored inside shopware.
Keep in mind that your app needs to have the correct permissions for the data it writes through this service.

### upsert()

* The `upsert()` method allows you to create or update entities inside the database.

  If you pass an `id` in the payload it will do an update if an entity with that `id` already exists, otherwise it will be a create.
* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Event\EntityWrittenContainerEvent`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Event/EntityWrittenContainerEvent.php)

  The WriteEvents that were generated by executing the `upsert()`.
* **Arguments:**
  * *`string`* **entityName**: The name of the entity you want to upsert, e.g. `product` or `media`.
  * *`array`* **payload**: The payload you want to upsert, as a list of associative arrays, where each associative array represents the payload for one entity.
* **Examples:**
  * Create a new entity.

    ```twig
    {% do services.writer.upsert('tax', [
        { 'name': 'new Tax', 'taxRate': 99.9 }
    ]) %}
    ```

  * Update an existing entity.

    ```twig
    {% do services.writer.upsert('product', [
        { 'id':  hook.productId, 'active': true }
    ]) %}
    ```

### delete()

* The `delete()` method allows you to delete entities from the database.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Event\EntityWrittenContainerEvent`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Event/EntityWrittenContainerEvent.php)

  The WriteEvents that were generated by executing the `delete()`.

* **Arguments:**
  * *`string`* **entityName**: The name of the entity you want to delete, e.g. `product` or `media`.
  * *`array`* **payload**: The primary keys of the entities you want to delete, as a list of associative arrays, associative array represents the primary keys for one entity.

* **Examples:**
  * Delete an entity.

    ```twig
    {% do services.writer.delete('product', [
        { 'id':  hook.productId }
    ]) %}
    ```

### sync()

* The `sync()` method allows you to execute updates and deletes to multiple entities in one method call.

* **Returns** [`Shopware\Core\Framework\Api\Sync\SyncResult`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/Api/Sync/SyncResult.php)

  The result of the `sync()`.

* **Arguments:**
  * *`array`* **payload**: All operations that should be executed.

* **Examples:**
  * Update an entity and delete another one with one `sync()` call.

    ```twig
    {% set payload = [
        {
            'entity': 'product',
            'action': 'upsert',
            'payload': [
                { 'id':  hook.updateProductId, 'active': true }
            ]
        },
        {
            'entity': 'product',
            'action': 'delete',
            'payload': [
            { 'id':  hook.deleteProductId }
        ]
        },
    ] %}

    {% do services.writer.sync(payload) %}
    ```

***

## [services.response (`Shopware\Core\Framework\Script\Api\ScriptResponseFactoryFacade`)](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/Script/Api/ScriptResponseFactoryFacade.php) {#scriptresponsefactoryfacade}

The `response` service allows you to create HTTP-Responses.

### json()

* The `json()` method allows you to create a JSON-Response.

* **Returns** [`Shopware\Core\Framework\Script\Api\ScriptResponse`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/Script/Api/ScriptResponse.php)

  The created response object, remember to assign it to the hook with `hook.setResponse()`.

* **Arguments:**
  * *`array`* **data**: The data that should be sent in the response as array.
  * *`int`* **code**: The HTTP-Status-Code of the response, defaults to 200.

    Default: `200`

* **Examples:**
  * Return hard coded values as JsonResponse.

    ```twig
    {% set response = services.response.json({ 'foo': 'bar' }) %}
    {% do hook.setResponse(response) %}
    ```

  * Search for products and return them in a JsonResponse.

    ```twig
    {# @var services \Shopware\Core\Framework\Script\ServiceStubs #}
    {% set products = services.repository.search('product', hook.request) %}

    {% set response = services.response.json({ 'products': products }) %}
    {% do hook.setResponse(response) %}
    ```

  * Provide a response to a ActionButtons request from the administration.

    ```twig
    {% set ids = hook.request.ids %}

    {% set response = services.response.json({
        "actionType": "notification",
        "payload": {
            "status": "success",
            "message": "You selected " ~ ids|length ~ " products."
        }
    }) %}

    {% do hook.setResponse(response) %}
    ```

### redirect()

* The `redirect()` method allows you to create a RedirectResponse.

* **Returns** [`Shopware\Core\Framework\Script\Api\ScriptResponse`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/Script/Api/ScriptResponse.php)

  The created response object, remember to assign it to the hook with `hook.setResponse()`.

* **Arguments:**
  * *`string`* **route**: The name of the route that should be redirected to.
  * *`array`* **parameters**: The parameters needing to generate the URL of the route as an associative array.
  * *`int`* **code**: he HTTP-Status-Code of the response, defaults to 302.

    Default: `302`

* **Examples:**
  * Redirect to an Admin-API route.

    ```twig
    {% set response = services.response.redirect('api.product.detail', { 'path': productId }) %}
    {% do hook.setResponse(response) %}
    ```

  * Redirect to a storefront page.

    ```twig
    {% set response = services.response.redirect('frontend.detail.page', { 'productId': productId }) %}
    {% do hook.setResponse(response) %}
    ```

### render()

* The `render()` method allows you to render a twig view with the parameters you provide and create a StorefrontResponse.

  Note that the `render()` method will throw an exception if it is called from outside a `SalesChannelContext` (e.g. from an `/api` route)
  or if the Storefront-bundle is not installed.
* **Returns** [`Shopware\Core\Framework\Script\Api\ScriptResponse`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/Script/Api/ScriptResponse.php)

  The created response object with the rendered template as content, remember to assign it to the hook with `hook.setResponse()`.
* **Arguments:**
  * *`string`* **view**: The name of the twig template you want to render e.g. `@Storefront/storefront/page/content/detail.html.twig`
  * *`array`* **parameters**: The parameters you want to pass to the template, ensure that you pass the `page` parameter from the hook to the templates.

    Default: `array (
    )`
* **Examples:**
  * Fetch a product, add it to the page and return a rendered response.

    ```twig
    {% set product = services.store.search('product', { 'ids': [productId]}).first %}

    {% do hook.page.addExtension('myProduct', product) %}

    {% do hook.setResponse(
        services.response.render('@MyApp/storefront/page/custom-page/index.html.twig', { 'page': hook.page })
    ) %}
    ```

***

---

---
url: /docs/guides/plugins/apps/app-scripts/custom-endpoints.md
---

# Custom Endpoints with App Scripts

## Overview

If you want to execute custom logic in Shopware in response to an HTTP request, or expose specific data through the API, you can define custom API endpoints in your app. These endpoints allow you to run a script whenever a request is sent to them.

## Custom Endpoints

There are specialized script-execution endpoints for the `api`, `store-api` and `storefront` scopes.
Refer to the [API docs](../../../development/integrations-api/index.md) for more information on the distinction of those APIs.
Those endpoints allow you to trigger the execution of your scripts with an HTTP request against those endpoints.

Custom endpoint scripts need to be located in a folder that is prefixed with the name of the api scope (one of `api-`, `store-api-` or `storefront`).
The remaining part of the folder name is the hook name.
You can specify which script should be executed by using the correct hook name in the URL of the HTTP request.

This means to execute the scripts under `Resources/scripts/api-test-script` you need to call the `/api/script/test-script` endpoint.
Note that all further slashes (`/`) in the route will be replaced by dashes (`-`). To execute the `Resources/scripts/api-test-script` scripts you could also call the `/api/script/test/script` endpoint.

::: warning
To prevent name collisions with other apps, you should always include your vendor prefix or app name as part of the hook name.
The best practice is to add your app name after the API scope prefix and then use it as a REST style resource identifier, e.g., `/api/script/swagMyApp/test-script`.
:::

In your custom endpoint scripts, you get access to the JSON payload of the request (and the query parameters for GET-requests) and have access to the read & write functionality of the [Data Abstraction Layer](../../../../concepts/framework/data-abstraction-layer.md).
For a complete overview of the available data and service, refer to the [hook reference documentation](../../../../resources/references/app-reference/script-reference/script-hooks-reference.md#api-hook).

By default, a `204 No Content` response will be sent after your script was executed.
To provide a custom response, you can use the [`response`-service](../../../../resources/references/app-reference/script-reference/custom-endpoint-script-services-reference.md#scriptresponsefactoryfacade) to create a response and set it as the `response` of the hook:

```twig
// Resources/scripts/api-custom-endpoint/my-example-script.twig
{% set response = services.response.json({ 'foo': 'bar' }) %}
{% do hook.setResponse(response) %}
```

You can execute multiple scripts for the same HTTP request by storing multiple scripts in the same order.
Those scripts will be executed in alphabetical order. Remember that later scripts may override the response set by prior scripts.
If you want to prevent the execution of further scripts, you can do so by calling `hook.stopPropagation`:

```twig
// Resources/scripts/api-custom-endpoint/my-example-script.twig
{% do hook.stopPropagation() %}
```

### Admin API endpoints

Scripts available over the Admin API should be stored in a folder prefixed with `api-`, so the folder name would be `api-{hook-name}`.
The execution of those scripts is possible over the `/api/script/{hook-name}` endpoint.

This endpoint only allows `POST` requests.

Caching of responses is not supported for Admin API responses.

For a complete overview of the available data and services, refer to the [reference documentation](../../../../resources/references/app-reference/script-reference/script-hooks-reference.md#api-hook).

### Store API endpoints

Scripts that should be available over the Store API should be stored in a folder prefixed with `store-api-`, so the folder name would be `store-api-{hook-name}`.
The execution of those scripts is possible over the `/store-api/script/{hook-name}` endpoint.

This endpoint allows `POST` and `GET` requests.

This hook is an [Interface Hook](../app-scripts/index.md#interface-hooks). The execution of your logic should be implemented in the `response` block of your script.

```twig
// Resources/scripts/store-api-custom-endpoint/my-example-script.twig
{% block response %}
    {% set response = services.response.json({ 'foo': 'bar' }) %}
    {% do hook.setResponse(response) %}
{% endblock %}
```

Caching of responses to `GET` requests is supported, but you need to implement the `cache_key` function in your script to provide a cache key for each response.
The cache key you generate should take every permutation of the request, which would lead to a different response into account and should return a unique key for each permutation.
A simple cache key generation would be to generate an `md5`-hash of all the incoming request parameters, as well as your hook's name:

```twig
// Resources/scripts/store-api-custom-endpoint/my-example-script.twig
{% block cache_key %}
    {% set cachePayload = hook.query %}
    {% set cachePayload = cachePayload|merge({'script': 'custom-endpoint'}) %}

    {% do hook.setCacheKey(cachePayload|md5) %}
{% endblock %}
```

For a complete overview of the available data and services, refer to the [reference documentation](../../../../resources/references/app-reference/script-reference/script-hooks-reference.md#store-api-hook).

### Storefront endpoints

Scripts available for the Storefront should be stored in a folder prefixed with `storefront-`, so the folder name would be `storefront-{hook-name}`.
The execution of those scripts is possible over the `/storefront/script/{hook-name}` endpoint.
Custom Storefront endpoints can be called by a normal browser request or from JavaScript via ajax.

This endpoint allows `POST` and `GET` requests.

Caching is supported and enabled by default for `GET` requests.

In addition to providing `JsonResponses` you can also render your own templates:

```twig
// Resources/scripts/storefront-custom-endpoint/my-example-script.twig
{% set product = services.store.search('product', { 'ids': [productId]}).first %}

{% do hook.page.addExtension('myProduct', product) %}

{% do hook.setResponse(
    services.response.render('@MyApp/storefront/page/custom-page/index.html.twig', { 'page': hook.page })
) %}
```

Additionally, it is also possible to redirect to an existing route:

```twig
// Resources/scripts/storefront-custom-endpoint/my-example-script.twig
{% set productId = hook.query['product-id'] %}

{% set response = services.response.redirect('frontend.detail.page', { 'productId': productId }) %}
{% do hook.setResponse(response) %}
```

For a complete overview of the available data and services, refer to the [reference documentation](../../../../resources/references/app-reference/script-reference/script-hooks-reference.md#storefront-hook).

## Manipulate HTTP-headers to API responses

::: info
Note that the `response` hook was added in v6.6.10.4 and is not available in earlier versions.
:::

There is a specific `response` script hook, that allows you to manipulate the HTTP-headers of the response via app scripts.
This is especially useful to adjust the security headers to your needs.

To add a custom header to every response, you can do the following:

```twig
// Resources/scripts/response/response.twig
{% do hook.setHeader('X-Frame-Options', 'SAMEORIGIN') %}
```

Additionally, you can check the current value of a given header and adjust it accordingly:

```twig
// Resources/scripts/response/response.twig
{% if hook.getHeader('X-Frame-Options') == 'DENY' %}
    {% do hook.setHeader('X-Frame-Options', 'SAMEORIGIN') %}
{% endif %}
```

You also have access to the route name of the current request and to the route scopes to control the headers for specific routes:

```twig
// Resources/scripts/response/response.twig
{% if hook.routeName == 'frontend.detail.page' and hook.isInRouteScope('store-api') %}
    {% do hook.setHeader('X-Frame-Options', 'SAMEORIGIN') %}
{% endif %}
```

The possible route scopes are `storefront`, `store-api`, `api` and `administration`.

## Caching

To improve the end-user experience and provide a scalable system, the customer-facing APIs (i.e., `store-api` and `storefront`) offer a caching mechanism to cache the response to specific requests and return the response from the cache on further requests instead of computing it again and again on each request.

By default, caching is enabled for custom endpoints, but for `store-api` endpoints you have to generate the cache key in the script.
For `storefront` requests, however, shopware takes care of it so that responses get automatically cached (if the [HTTP-Cache](../../../../concepts/framework/http_cache.md) is enabled).

### Cache Config

You can configure the caching behavior for each response on the `response`-object in your scripts.

#### Add custom tags to the cache item

To allow fine-grained [cache invalidation](#cache-invalidation) you can tag the response with custom tags and then invalidate certain tags in a `cache-invalidation` script.

```twig
{% set response = services.response.json({ 'foo': 'bar' }) %}
{% do response.cache.tag('my-custom-tag') %}

{% do hook.setResponse(response) %}
```

#### Disable caching

You can opt out of the caching by calling `cache.disable()`. This means that the response won't be cached.

```twig
{% set response = services.response.json({ 'foo': 'bar' }) %}
{% do response.cache.disable() %}

{% do hook.setResponse(response) %}
```

#### Set the max-age of the cache item

You can specify for how long a response should be cached by calling the `cache.maxAge()` method and passing the number of seconds after which the cache item should expire.

> **Note:** `cache.maxAge()` is deprecated and will be removed in v6.8.0.0. Starting with v6.7.6.0, you can use `sharedMaxAge()` (corresponds to `s-maxage` in the `Cache-Control` header).
> When the `CACHE_REWORK` feature flag is enabled, you can also use `clientMaxAge()` (corresponds to `max-age` in the `Cache-Control` header).

```twig
{% set response = services.response.json({ 'foo': 'bar' }) %}
{% do response.cache.sharedMaxAge(120) %}

{% do hook.setResponse(response) %}
```

#### Invalidate cache items for specific states

> **Note:** The cache states feature is deprecated and will be removed in v6.8.0.0. It also does not work when the `CACHE_REWORK` feature flag is enabled.

You can specify that the cached response is not valid if one of the given states is present.
For more detailed information on the invalidation states, refer to the [HTTP-cache docs](../../../../concepts/framework/http_cache.md#sw-states).

```twig
{% set response = services.response.json({ 'foo': 'bar' }) %}
{% do response.cache.invalidationState('logged-in') %}

{% do hook.setResponse(response) %}
```

### Cache invalidation

To prevent serving stale cache items, the cache needs to be invalidated if the underlying data changes. Therefore, you can add `cache-invalidation` scripts, where you can inspect each write operation in the system and invalidate specific cache items by tag.

In your `cache-invalidation` scripts, you can get the `ids` that were written for a specific entity, e.g., `product_manufacturer`.

```twig
// Resources/scripts/cache-invalidation/my-invalidation-script.twig
{% set ids = hook.event.getIds('product_manufacturer') %}

{% if ids.empty %}
    {% return %}
{% endif %}
```

To allow even more fine-grained invalidation, you can filter down the list of written entities by filtering for specific actions that were performed on that entity (e.g., `insert`, `update`, `delete`) and filter by which properties were changed.

```twig
// Resources/scripts/cache-invalidation/my-invalidation-script.twig
{% set ids = hook.event.getIds('product') %}

{% set ids = ids.only('insert') %} // filter by action = insert
{% set ids = ids.with('description', 'parentId') %} // filter all entities were 'description` OR `parentId` was changed
{% if ids.empty %}
    {% return %}
{% endif %}
```

Note that you can also chain the filter operations:

```twig
// Resources/scripts/cache-invalidation/my-invalidation-script.twig
{% set ids = hook.event.getIds('product') %}

{% set ids = ids.only('insert').with('description', 'parentId') %}
{% if ids.empty %}
    {% return %}
{% endif %}
```

You can then use the filtered-down list of ids to invalidate entity-specific tags:

```twig
{% set tags = [] %}
{% for id in ids %}
    {% set tags = tags|merge(['my-product-' ~ id]) %}
{% endfor %}

{% do services.cache.invalidate(tags) %}
```

For a complete overview of what data and services are available, refer to the [cache-invalidation hook reference documentation](../../../../resources/references/app-reference/script-reference/script-hooks-reference.md#cache-invalidation).

---

---
url: /docs/v6.5/guides/plugins/apps/app-scripts/custom-endpoints.md
---

# Custom Endpoints with App Scripts

If you want to execute some logic in Shopware and trigger the execution over an HTTP request or need some special data from Shopware over the API, you can create custom API endpoints in your app that allow you to execute a script when a request to that endpoint is made.

::: info
Note that custom endpoints with app scripts were introduced in Shopware 6.4.9.0 and are not supported in previous versions.
:::

## Custom Endpoints

There are specialized script-execution endpoints for the `api`, `store-api` and `storefront` scopes.
Refer to the [API docs](../../../integrations-api/) for more information on the distinction of those APIs.
Those endpoints allow you to trigger the execution of your scripts with an HTTP request against those endpoints.

Custom endpoint scripts need to be located in a folder that is prefixed with the name of the api scope (one of `api-`, `store-api-` or `storefront`).
The remaining part of the folder name is the hook name.
You can specify which script should be executed by using the correct hook name in the URL of the HTTP request.

This means to execute the scripts under `Resources/scripts/api-test-script` you need to call the `/api/script/test-script` endpoint.
Note that all further slashes (`/`) in the route will be replaced by dashes (`-`). To execute the `Resources/scripts/api-test-script` scripts you could also call the `/api/script/test/script` endpoint.

::: warning
To prevent name collisions with other apps, you should always include your vendor prefix or app name as part of the hook name.
The best practice is to add your app name after the API scope prefix and then use it as a REST style resource identifier, e.g., `/api/script/swagMyApp/test-script`.
:::

In your custom endpoint scripts, you get access to the JSON payload of the request (and the query parameters for GET-requests) and have access to the read & write functionality of the [Data Abstraction Layer](../../../../concepts/framework/data-abstraction-layer).
For a complete overview of the available data and service, refer to the [hook reference documentation](../../../../resources/references/app-reference/script-reference/script-hooks-reference#api-hook).

By default, a `204 No Content` response will be sent after your script was executed.
To provide a custom response, you can use the [`response`-service](../../../../resources/references/app-reference/script-reference/custom-endpoint-script-services-reference#scriptresponsefactoryfacade) to create a response and set it as the `response` of the hook:

```twig
// Resources/scripts/api-custom-endpoint/my-example-script.twig
{% set response = services.response.json({ 'foo': 'bar' }) %}
{% do hook.setResponse(response) %}
```

You can execute multiple scripts for the same HTTP request by storing multiple scripts in the same order.
Those scripts will be executed in alphabetical order. Remember that later scripts may override the response set by prior scripts.
If you want to prevent the execution of further scripts, you can do so by calling `hook.stopPropagation`:

```twig
// Resources/scripts/api-custom-endpoint/my-example-script.twig
{% do hook.stopPropagation() %}
```

### Admin API endpoints

Scripts available over the Admin API should be stored in a folder prefixed with `api-`, so the folder name would be `api-{hook-name}`.
The execution of those scripts is possible over the `/api/script/{hook-name}` endpoint.

This endpoint only allows `POST` requests.

Caching of responses is not supported for Admin API responses.

For a complete overview of the available data and services, refer to the [reference documentation](../../../../resources/references/app-reference/script-reference/script-hooks-reference#api-hook).

### Store API endpoints

Scripts that should be available over the Store API should be stored in a folder prefixed with `store-api-`, so the folder name would be `store-api-{hook-name}`.
The execution of those scripts is possible over the `/store-api/script/{hook-name}` endpoint.

This endpoint allows `POST` and `GET` requests.

This hook is an [Interface Hook](./#interface-hooks). The execution of your logic should be implemented in the `response` block of your script.

```twig
// Resources/scripts/store-api-custom-endpoint/my-example-script.twig
{% block response %}
    {% set response = services.response.json({ 'foo': 'bar' }) %}
    {% do hook.setResponse(response) %}
{% endblock %}
```

Caching of responses to `GET` requests is supported, but you need to implement the `cache_key` function in your script to provide a cache key for each response.
The cache key you generate should take every permutation of the request, which would lead to a different response into account and should return a unique key for each permutation.
A simple cache key generation would be to generate an `md5`-hash of all the incoming request parameters, as well as your hook's name:

```twig
// Resources/scripts/store-api-custom-endpoint/my-example-script.twig
{% block cache_key %}
    {% set cachePayload = hook.query %}
    {% set cachePayload = cachePayload|merge({'script': 'custom-endpoint'}) %}

    {% do hook.setCacheKey(cachePayload|md5) %}
{% endblock %}
```

For a complete overview of the available data and services, refer to the [reference documentation](../../../../resources/references/app-reference/script-reference/script-hooks-reference#store-api-hook).

### Storefront endpoints

Scripts available for the Storefront should be stored in a folder prefixed with `storefront-`, so the folder name would be `storefront-{hook-name}`.
The execution of those scripts is possible over the `/storefront/script/{hook-name}` endpoint.
Custom Storefront endpoints can be called by a normal browser request or from javascript via ajax.

This endpoint allows `POST` and `GET` requests.

Caching is supported and enabled by default for `GET` requests.

In addition to providing `JsonResponses` you can also render your own templates:

```twig
// Resources/scripts/storefront-custom-endpoint/my-example-script.twig
{% set product = services.store.search('product', { 'ids': [productId]}).first %}

{% do hook.page.addExtension('myProduct', product) %}

{% do hook.setResponse(
    services.response.render('@MyApp/storefront/page/custom-page/index.html.twig', { 'page': hook.page })
) %}
```

Additionally, it is also possible to redirect to an existing route:

```twig
// Resources/scripts/storefront-custom-endpoint/my-example-script.twig
{% set productId = hook.query['product-id'] %}

{% set response = services.response.redirect('frontend.detail.page', { 'productId': productId }) %}
{% do hook.setResponse(response) %}
```

For a complete overview of the available data and services, refer to the [reference documentation](../../../../resources/references/app-reference/script-reference/script-hooks-reference#storefront-hook).

## Caching

To improve the end-user experience and provide a scalable system, the customer-facing APIs (i.e., `store-api` and `storefront`) offer caching mechanism to cache the response to specific requests and return the response from the cache on further requests instead of computing it again and again on each request.

By default, caching is enabled for custom endpoints, but for `store-api` endpoints you have to generate the cache key in the script.
For `storefront` requests, however, shopware takes care of it so that responses get automatically cached (if the [HTTP-Cache](../../../../concepts/framework/http_cache) is enabled).

### Cache Config

You can configure the caching behavior for each response on the `response`-object in your scripts.

#### Add custom tags to the cache item

To allow fine-grained [cache invalidation](#cache-invalidation) you can tag the response with custom tags and then invalidate certain tags in a `cache-invalidation` script.

```twig
{% set response = services.response.json({ 'foo': 'bar' }) %}
{% do response.cache.tag('my-custom-tag') %}

{% do hook.setResponse(response) %}
```

#### Disable caching

You can opt out of the caching by calling `cache.disable()`. This means that the response won't be cached.

```twig
{% set response = services.response.json({ 'foo': 'bar' }) %}
{% do response.cache.disable() %}

{% do hook.setResponse(response) %}
```

#### Set the max-age of the cache item

You can specify for how long a response should be cached by calling the `cache.maxAge()` method and passing the number of seconds after which the cache item should expire.

```twig
{% set response = services.response.json({ 'foo': 'bar' }) %}
{% do response.cache.maxAge(120) %}

{% do hook.setResponse(response) %}
```

#### Invalidate cache items for specific states

You can specify that the cached response is not valid if one of the given states is present.
For more detailed information on the invalidation states, refer to the [HTTP-cache docs](../../../../concepts/framework/http_cache#sw-states).

```twig
{% set response = services.response.json({ 'foo': 'bar' }) %}
{% do response.cache.invalidationState('logged-in') %}

{% do hook.setResponse(response) %}
```

### Cache invalidation

To prevent serving stale cache items, the cache needs to be invalidated if the underlying data changes. Therefore, you can add `cache-invalidation` scripts, where you can inspect each write operation in the system and invalidate specific cache items by tag.

In your `cache-invalidation` scripts, you can get the `ids` that were written for a specific entity, e.g., `product_manufacturer`.

```twig
// Resources/scripts/cache-invalidation/my-invalidation-script.twig
{% set ids = hook.event.getIds('product_manufacturer') %}

{% if ids.empty %}
    {% return %}
{% endif %}
```

To allow even more fine-grained invalidation, you can filter down the list of written entities by filtering for specific actions that were performed on that entity (e.g., `insert`, `update`, `delete`) and filter by which properties were changed.

```twig
// Resources/scripts/cache-invalidation/my-invalidation-script.twig
{% set ids = hook.event.getIds('product') %}

{% set ids = ids.only('insert') %} // filter by action = insert
{% set ids = ids.with('description', 'parentId') %} // filter all entities were 'description` OR `parentId` was changed
{% if ids.empty %}
    {% return %}
{% endif %}
```

Note that you can also chain the filter operations:

```twig
// Resources/scripts/cache-invalidation/my-invalidation-script.twig
{% set ids = hook.event.getIds('product') %}

{% set ids = ids.only('insert').with('description', 'parentId') %}
{% if ids.empty %}
    {% return %}
{% endif %}
```

You can then use the filtered down list of ids to invalidate entity specific tags:

```twig
{% set tags = [] %}
{% for id in ids %}
    {% set tags = tags|merge(['my-product-' ~ id]) %}
{% endfor %}

{% do services.cache.invalidate(tags) %}
```

For a complete overview of what data and services are available, refer to the [cache-invalidation hook reference documentation](../../../../resources/references/app-reference/script-reference/script-hooks-reference#cache-invalidation).

---

---
url: /docs/v6.6/guides/plugins/apps/app-scripts/custom-endpoints.md
---

# Custom Endpoints with App Scripts

If you want to execute some logic in Shopware and trigger the execution over an HTTP request or need some special data from Shopware over the API, you can create custom API endpoints in your app that allow you to execute a script when a request to that endpoint is made.

## Manipulate HTTP-headers to API responses

::: info
Note that the `response` hook was added in v6.6.10.4 and is not available in earlier versions.
:::

There is a specific `response` script hook, that allows you to manipulate the HTTP-headers of the response via app scripts.
This is especially useful to adjust the security headers to your needs.

To add a custom header to every response, you can do the following:

```twig
// Resources/scripts/response/response.twig
{% do hook.setHeader('X-Frame-Options', 'SAMEORIGIN') %}
```

Additionally, you can check the current value of a given header and adjust it accordingly:

```twig
// Resources/scripts/response/response.twig
{% if hook.getHeader('X-Frame-Options') == 'DENY' %}
    {% do hook.setHeader('X-Frame-Options', 'SAMEORIGIN') %}
{% endif %}
```

You also have access to the route name of the current request and to the route scopes to control the headers for specific routes:

```twig
// Resources/scripts/response/response.twig
{% if hook.routeName == 'frontend.detail.page' and hook.isInRouteScope('store-api') %}
    {% do hook.setHeader('X-Frame-Options', 'SAMEORIGIN') %}
{% endif %}
```

The possible route scopes are `storefront`, `store-api`, `api` and `administration`.

## Custom Endpoints

There are specialized script-execution endpoints for the `api`, `store-api` and `storefront` scopes.
Refer to the [API docs](../../../integrations-api/) for more information on the distinction of those APIs.
Those endpoints allow you to trigger the execution of your scripts with an HTTP request against those endpoints.

Custom endpoint scripts need to be located in a folder that is prefixed with the name of the api scope (one of `api-`, `store-api-` or `storefront`).
The remaining part of the folder name is the hook name.
You can specify which script should be executed by using the correct hook name in the URL of the HTTP request.

This means to execute the scripts under `Resources/scripts/api-test-script` you need to call the `/api/script/test-script` endpoint.
Note that all further slashes (`/`) in the route will be replaced by dashes (`-`). To execute the `Resources/scripts/api-test-script` scripts you could also call the `/api/script/test/script` endpoint.

::: warning
To prevent name collisions with other apps, you should always include your vendor prefix or app name as part of the hook name.
The best practice is to add your app name after the API scope prefix and then use it as a REST style resource identifier, e.g., `/api/script/swagMyApp/test-script`.
:::

In your custom endpoint scripts, you get access to the JSON payload of the request (and the query parameters for GET-requests) and have access to the read & write functionality of the [Data Abstraction Layer](../../../../concepts/framework/data-abstraction-layer).
For a complete overview of the available data and service, refer to the [hook reference documentation](../../../../resources/references/app-reference/script-reference/script-hooks-reference#api-hook).

By default, a `204 No Content` response will be sent after your script was executed.
To provide a custom response, you can use the [`response`-service](../../../../resources/references/app-reference/script-reference/custom-endpoint-script-services-reference#scriptresponsefactoryfacade) to create a response and set it as the `response` of the hook:

```twig
// Resources/scripts/api-custom-endpoint/my-example-script.twig
{% set response = services.response.json({ 'foo': 'bar' }) %}
{% do hook.setResponse(response) %}
```

You can execute multiple scripts for the same HTTP request by storing multiple scripts in the same order.
Those scripts will be executed in alphabetical order. Remember that later scripts may override the response set by prior scripts.
If you want to prevent the execution of further scripts, you can do so by calling `hook.stopPropagation`:

```twig
// Resources/scripts/api-custom-endpoint/my-example-script.twig
{% do hook.stopPropagation() %}
```

### Admin API endpoints

Scripts available over the Admin API should be stored in a folder prefixed with `api-`, so the folder name would be `api-{hook-name}`.
The execution of those scripts is possible over the `/api/script/{hook-name}` endpoint.

This endpoint only allows `POST` requests.

Caching of responses is not supported for Admin API responses.

For a complete overview of the available data and services, refer to the [reference documentation](../../../../resources/references/app-reference/script-reference/script-hooks-reference#api-hook).

### Store API endpoints

Scripts that should be available over the Store API should be stored in a folder prefixed with `store-api-`, so the folder name would be `store-api-{hook-name}`.
The execution of those scripts is possible over the `/store-api/script/{hook-name}` endpoint.

This endpoint allows `POST` and `GET` requests.

This hook is an [Interface Hook](./#interface-hooks). The execution of your logic should be implemented in the `response` block of your script.

```twig
// Resources/scripts/store-api-custom-endpoint/my-example-script.twig
{% block response %}
    {% set response = services.response.json({ 'foo': 'bar' }) %}
    {% do hook.setResponse(response) %}
{% endblock %}
```

Caching of responses to `GET` requests is supported, but you need to implement the `cache_key` function in your script to provide a cache key for each response.
The cache key you generate should take every permutation of the request, which would lead to a different response into account and should return a unique key for each permutation.
A simple cache key generation would be to generate an `md5`-hash of all the incoming request parameters, as well as your hook's name:

```twig
// Resources/scripts/store-api-custom-endpoint/my-example-script.twig
{% block cache_key %}
    {% set cachePayload = hook.query %}
    {% set cachePayload = cachePayload|merge({'script': 'custom-endpoint'}) %}

    {% do hook.setCacheKey(cachePayload|md5) %}
{% endblock %}
```

For a complete overview of the available data and services, refer to the [reference documentation](../../../../resources/references/app-reference/script-reference/script-hooks-reference#store-api-hook).

### Storefront endpoints

Scripts available for the Storefront should be stored in a folder prefixed with `storefront-`, so the folder name would be `storefront-{hook-name}`.
The execution of those scripts is possible over the `/storefront/script/{hook-name}` endpoint.
Custom Storefront endpoints can be called by a normal browser request or from javascript via ajax.

This endpoint allows `POST` and `GET` requests.

Caching is supported and enabled by default for `GET` requests.

In addition to providing `JsonResponses` you can also render your own templates:

```twig
// Resources/scripts/storefront-custom-endpoint/my-example-script.twig
{% set product = services.store.search('product', { 'ids': [productId]}).first %}

{% do hook.page.addExtension('myProduct', product) %}

{% do hook.setResponse(
    services.response.render('@MyApp/storefront/page/custom-page/index.html.twig', { 'page': hook.page })
) %}
```

Additionally, it is also possible to redirect to an existing route:

```twig
// Resources/scripts/storefront-custom-endpoint/my-example-script.twig
{% set productId = hook.query['product-id'] %}

{% set response = services.response.redirect('frontend.detail.page', { 'productId': productId }) %}
{% do hook.setResponse(response) %}
```

For a complete overview of the available data and services, refer to the [reference documentation](../../../../resources/references/app-reference/script-reference/script-hooks-reference#storefront-hook).

## Caching

To improve the end-user experience and provide a scalable system, the customer-facing APIs (i.e., `store-api` and `storefront`) offer caching mechanism to cache the response to specific requests and return the response from the cache on further requests instead of computing it again and again on each request.

By default, caching is enabled for custom endpoints, but for `store-api` endpoints you have to generate the cache key in the script.
For `storefront` requests, however, shopware takes care of it so that responses get automatically cached (if the [HTTP-Cache](../../../../concepts/framework/http_cache) is enabled).

### Cache Config

You can configure the caching behavior for each response on the `response`-object in your scripts.

#### Add custom tags to the cache item

To allow fine-grained [cache invalidation](#cache-invalidation) you can tag the response with custom tags and then invalidate certain tags in a `cache-invalidation` script.

```twig
{% set response = services.response.json({ 'foo': 'bar' }) %}
{% do response.cache.tag('my-custom-tag') %}

{% do hook.setResponse(response) %}
```

#### Disable caching

You can opt out of the caching by calling `cache.disable()`. This means that the response won't be cached.

```twig
{% set response = services.response.json({ 'foo': 'bar' }) %}
{% do response.cache.disable() %}

{% do hook.setResponse(response) %}
```

#### Set the max-age of the cache item

You can specify for how long a response should be cached by calling the `cache.maxAge()` method and passing the number of seconds after which the cache item should expire.

```twig
{% set response = services.response.json({ 'foo': 'bar' }) %}
{% do response.cache.maxAge(120) %}

{% do hook.setResponse(response) %}
```

#### Invalidate cache items for specific states

You can specify that the cached response is not valid if one of the given states is present.
For more detailed information on the invalidation states, refer to the [HTTP-cache docs](../../../../concepts/framework/http_cache#sw-states).

```twig
{% set response = services.response.json({ 'foo': 'bar' }) %}
{% do response.cache.invalidationState('logged-in') %}

{% do hook.setResponse(response) %}
```

### Cache invalidation

To prevent serving stale cache items, the cache needs to be invalidated if the underlying data changes. Therefore, you can add `cache-invalidation` scripts, where you can inspect each write operation in the system and invalidate specific cache items by tag.

In your `cache-invalidation` scripts, you can get the `ids` that were written for a specific entity, e.g., `product_manufacturer`.

```twig
// Resources/scripts/cache-invalidation/my-invalidation-script.twig
{% set ids = hook.event.getIds('product_manufacturer') %}

{% if ids.empty %}
    {% return %}
{% endif %}
```

To allow even more fine-grained invalidation, you can filter down the list of written entities by filtering for specific actions that were performed on that entity (e.g., `insert`, `update`, `delete`) and filter by which properties were changed.

```twig
// Resources/scripts/cache-invalidation/my-invalidation-script.twig
{% set ids = hook.event.getIds('product') %}

{% set ids = ids.only('insert') %} // filter by action = insert
{% set ids = ids.with('description', 'parentId') %} // filter all entities were 'description` OR `parentId` was changed
{% if ids.empty %}
    {% return %}
{% endif %}
```

Note that you can also chain the filter operations:

```twig
// Resources/scripts/cache-invalidation/my-invalidation-script.twig
{% set ids = hook.event.getIds('product') %}

{% set ids = ids.only('insert').with('description', 'parentId') %}
{% if ids.empty %}
    {% return %}
{% endif %}
```

You can then use the filtered down list of ids to invalidate entity specific tags:

```twig
{% set tags = [] %}
{% for id in ids %}
    {% set tags = tags|merge(['my-product-' ~ id]) %}
{% endfor %}

{% do services.cache.invalidate(tags) %}
```

For a complete overview of what data and services are available, refer to the [cache-invalidation hook reference documentation](../../../../resources/references/app-reference/script-reference/script-hooks-reference#cache-invalidation).

---

---
url: /docs/v6.5/guides/plugins/apps/custom-data/custom-entities.md
---

# Custom entities

In addition to [Custom fields](custom-fields), you can create completely own entities in the system, named custom entities.
Unlike [Custom fields](custom-fields), you can generate completely custom data structures with custom relations, which can then be maintained by the admin.
To make use of the custom entities register your entities in your `entities.xml` file, which is located in the `Resources` directory of your app.

```xml
// <app root>/Resources/entities.xml
<?xml version="1.0" encoding="utf-8" ?>
<entities xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/CustomEntity/Xml/entity-1.0.xsd">
    <entity name="custom_entity_bundle">
        <fields>
            <string name="name" required="true" translatable="true" store-api-aware="true" />
            <price name="discount" required="true" store-api-aware="true"/>
            <many-to-many name="products" reference="product" store-api-aware="true" />
        </fields>
    </entity>
</entities>
```

For a complete reference of the structure of the entities file take a look at the [Custom entity xml reference](../../../../resources/references/app-reference/entities-reference).

## Functionality

All registered entities will get an automatically registered repository. It is also available in the [App scripts](../app-scripts/) section, in case you are allowed to access the repository service inside the hook.

```twig
{% set blogs = services.repository.search('custom_entity_blog', criteria) %}
```

Additionally, to the repository you can also access your custom entities via [Admin api](../../../../concepts/api/admin-api).

```bash
POST /api/search/custom-entity-blog
```

## Using Custom Entities with Custom Fields

::: info
The ability to use custom entities with custom fields is available since Shopware 6.5.1.0.
:::

By default, it is not possible to create a custom field of type "Entity Select", which references a custom entity. However, you can opt in to this behavior. You will need to add the `custom-fields-aware` & `label-property` attributes to your entity definition:

```xml
// Resources/entities.xml
<?xml version="1.0" encoding="utf-8" ?>
<entities xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/CustomEntity/Xml/entity-1.0.xsd">
    <entity name="custom_entity_bundle" custom-fields-aware="true" label-property="name">
        <fields>
            <string name="name" required="true" translatable="true" store-api-aware="true" />
            <price name="discount" required="true" store-api-aware="true"/>
            <many-to-many name="products" reference="product" store-api-aware="true" />
        </fields>
    </entity>
</entities>
```

To enable the usage of custom fields, the `custom-fields-aware` setting should be set to true. Then, it is necessary to indicate a label field for the entity that will be used when selecting via the custom field. In this example, the `name` field is selected as the `label-property` field. It is important to note that this field must be included in the `fields` section of the entity definition and be of type `string`.

Now you will find your entity in the "Entity Type" select when creating a custom field of type "Entity Select". Without a snippet label for the entity, it will display as `custom_entity_bundle.label`. You can create a snippet to add a label like so:

```js
// Resources/app/administration/snippet/en-GB.json
{
  "custom_entity_bundle": {
    "label": "My Custom Entity"
  }
}
```

## Permissions

Unlike core entities, your app directly has full access rights to your own custom entities. However, if your entity has associations that reference core tables,
you need the appropriate [permissions](../../../../resources/references/app-reference/manifest-reference) to load and write these associations.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        <!-- ... -->
    </meta>
    <permissions>
        <read>product</read>
<!--    <read>custom_entity_blog</read>   < permissions for own entities are automatically set  -->
    </permissions>
</manifest>
```

## Shorthand prefix

Since v6.4.15.0 it is possible to also use the `ce_` shorthand prefix for your custom entities to prevent problems with length restrictions of names inside the DB.

```xml
<?xml version="1.0" encoding="utf-8" ?>
<entities xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/CustomEntity/Xml/entity-1.0.xsd">
    <entity name="ce_bundle">
        <fields>
            ...
        </fields>
    </entity>
</entities>
```

If you use the shorthand in the entity definition, you also need to use it if you use the repository or the API.

```twig
{% set blogs = services.repository.search('ce_blog', criteria) %}
```

```bash
POST /api/search/ce_blog
```

::: warning
Note that you can't rename existing custom entities as that would lead to the deletion of all existing data.
:::

---

---
url: /docs/v6.6/guides/plugins/apps/custom-data/custom-entities.md
---

# Custom entities

In addition to [Custom fields](custom-fields), you can create completely own entities in the system, named custom entities.
Unlike [Custom fields](custom-fields), you can generate completely custom data structures with custom relations, which can then be maintained by the admin.
To make use of the custom entities register your entities in your `entities.xml` file, which is located in the `Resources` directory of your app.

```xml
// <app root>/Resources/entities.xml
<?xml version="1.0" encoding="utf-8" ?>
<entities xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/CustomEntity/Xml/entity-1.0.xsd">
    <entity name="custom_entity_bundle">
        <fields>
            <string name="name" required="true" translatable="true" store-api-aware="true" />
            <price name="discount" required="true" store-api-aware="true"/>
            <many-to-many name="products" reference="product" store-api-aware="true" />
        </fields>
    </entity>
</entities>
```

For a complete reference of the structure of the entities file take a look at the [Custom entity xml reference](../../../../resources/references/app-reference/entities-reference).

## Functionality

All registered entities will get an automatically registered repository. It is also available in the [App scripts](../app-scripts/) section, in case you are allowed to access the repository service inside the hook.

```twig
{% set blogs = services.repository.search('custom_entity_blog', criteria) %}
```

Additionally, to the repository you can also access your custom entities via [Admin api](../../../../concepts/api/admin-api).

```bash
POST /api/search/custom-entity-blog
```

## Using Custom Entities with Custom Fields

::: info
The ability to use custom entities with custom fields is available since Shopware 6.5.1.0.
:::

By default, it is not possible to create a custom field of type "Entity Select", which references a custom entity. However, you can opt in to this behavior. You will need to add the `custom-fields-aware` & `label-property` attributes to your entity definition:

```xml
// Resources/entities.xml
<?xml version="1.0" encoding="utf-8" ?>
<entities xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/CustomEntity/Xml/entity-1.0.xsd">
    <entity name="custom_entity_bundle" custom-fields-aware="true" label-property="name">
        <fields>
            <string name="name" required="true" translatable="true" store-api-aware="true" />
            <price name="discount" required="true" store-api-aware="true"/>
            <many-to-many name="products" reference="product" store-api-aware="true" />
        </fields>
    </entity>
</entities>
```

To enable the usage of custom fields, the `custom-fields-aware` setting should be set to true. Then, it is necessary to indicate a label field for the entity that will be used when selecting via the custom field. In this example, the `name` field is selected as the `label-property` field. It is important to note that this field must be included in the `fields` section of the entity definition and be of type `string`.

Now you will find your entity in the "Entity Type" select when creating a custom field of type "Entity Select". Without a snippet label for the entity, it will display as `custom_entity_bundle.label`. You can create a snippet to add a label like so:

```javascript
// Resources/app/administration/snippet/en-GB.json
{
  "custom_entity_bundle": {
    "label": "My Custom Entity"
  }
}
```

## Permissions

Unlike core entities, your app directly has full access rights to your own custom entities. However, if your entity has associations that reference core tables,
you need the appropriate [permissions](../../../../resources/references/app-reference/manifest-reference) to load and write these associations.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-2.0.xsd">
    <meta>
        <!-- ... -->
    </meta>
    <permissions>
        <read>product</read>
<!--    <read>custom_entity_blog</read>   < permissions for own entities are automatically set  -->
    </permissions>
</manifest>
```

## Shorthand prefix

Since v6.4.15.0 it is possible to also use the `ce_` shorthand prefix for your custom entities to prevent problems with length restrictions of names inside the DB.

```xml
<?xml version="1.0" encoding="utf-8" ?>
<entities xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/CustomEntity/Xml/entity-1.0.xsd">
    <entity name="ce_bundle">
        <fields>
            ...
        </fields>
    </entity>
</entities>
```

If you use the shorthand in the entity definition, you also need to use it if you use the repository or the API.

```twig
{% set blogs = services.repository.search('ce_blog', criteria) %}
```

```bash
POST /api/search/ce_blog
```

::: warning
Note that you can't rename existing custom entities as that would lead to the deletion of all existing data.
:::

---

---
url: /docs/guides/plugins/apps/custom-data/custom-entities.md
---

# Custom Entities

## Overview

In addition to [Custom fields](custom-fields.md), you can define entirely new entities in the system, called custom entities. Unlike custom fields, custom entities let you model fully customized data structures and relationships. These entities can then be managed directly in the Administration.

To use custom entities, register them in your app's `Resources/entities.xml` file:

```xml
// <app root>/Resources/entities.xml
<?xml version="1.0" encoding="utf-8" ?>
<entities xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/CustomEntity/Xml/entity-1.0.xsd">
    <entity name="custom_entity_bundle">
        <fields>
            <string name="name" required="true" translatable="true" store-api-aware="true" />
            <price name="discount" required="true" store-api-aware="true"/>
            <many-to-many name="products" reference="product" store-api-aware="true" />
        </fields>
    </entity>
</entities>
```

For a complete reference of the structure of the entities file take a look at the [Custom entity xml reference](../../../../resources/references/app-reference/entities-reference.md).

## Functionality

All registered entities will get an automatically registered repository. It is also available in the [App scripts](../app-scripts/index.md) section, in case you are allowed to access the repository service inside the hook.

```twig
{% set blogs = services.repository.search('custom_entity_blog', criteria) %}
```

Additionally, to the repository you can also access your custom entities via [Admin API](../../../../concepts/api/admin-api.md).

```bash
POST /api/search/custom-entity-blog
```

## Using Custom Entities with Custom Fields

::: info
The ability to use custom entities with custom fields is available since Shopware 6.5.1.0.
:::

By default, it is not possible to create a custom field of type "Entity Select", which references a custom entity. However, you can opt in to this behavior. You will need to add the `custom-fields-aware` & `label-property` attributes to your entity definition:

```xml
// Resources/entities.xml
<?xml version="1.0" encoding="utf-8" ?>
<entities xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/CustomEntity/Xml/entity-1.0.xsd">
    <entity name="custom_entity_bundle" custom-fields-aware="true" label-property="name">
        <fields>
            <string name="name" required="true" translatable="true" store-api-aware="true" />
            <price name="discount" required="true" store-api-aware="true"/>
            <many-to-many name="products" reference="product" store-api-aware="true" />
        </fields>
    </entity>
</entities>
```

To enable the usage of custom fields, the `custom-fields-aware` setting should be set to true. Then, it is necessary to indicate a label field for the entity that will be used when selecting via the custom field. In this example, the `name` field is selected as the `label-property` field. It is important to note that this field must be included in the `fields` section of the entity definition and be of type `string`.

Now you will find your entity in the "Entity Type" select when creating a custom field of type "Entity Select". Without a snippet label for the entity, it will display as `custom_entity_bundle.label`. You can create a snippet to add a label like so:

```javascript
// Resources/app/administration/snippet/en-GB.json
{
  "custom_entity_bundle": {
    "label": "My Custom Entity"
  }
}
```

## Permissions

Unlike core entities, your app directly has full access rights to your own custom entities. However, if your entity has associations that reference core tables,
you need the appropriate [permissions](../../../../resources/references/app-reference/manifest-reference.md) to load and write these associations.

```xml
<?xml version="1.0" encoding="UTF-8"?>
<manifest xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
          xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/Framework/App/Manifest/Schema/manifest-3.0.xsd">
    <meta>
        <!-- ... -->
    </meta>
    <permissions>
        <read>product</read>
<!--    <read>custom_entity_blog</read>   < permissions for own entities are automatically set  -->
    </permissions>
</manifest>
```

## Shorthand prefix

Since v6.4.15.0 it is possible to also use the `ce_` shorthand prefix for your custom entities to prevent problems with length restrictions of names inside the DB.

```xml
<?xml version="1.0" encoding="utf-8" ?>
<entities xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="https://raw.githubusercontent.com/shopware/shopware/trunk/src/Core/System/CustomEntity/Xml/entity-1.0.xsd">
    <entity name="ce_bundle">
        <fields>
            ...
        </fields>
    </entity>
</entities>
```

If you use the shorthand in the entity definition, you also need to use it if you use the repository or the API.

```twig
{% set blogs = services.repository.search('ce_blog', criteria) %}
```

```bash
POST /api/search/ce_blog
```

::: warning
Note that you can't rename existing custom entities as that would lead to the deletion of all existing data.
:::

---

---
url: /docs/guides/plugins/plugins/framework/custom-field.md
---

# Custom Fields

Custom fields in Shopware refer to additional data fields that can be added to entities such as products, customers, or orders. These fields allow businesses to store and manage extra information that may be specific to their operations.

With custom fields, you can define and store data beyond the standard attributes provided by Shopware. For example, a clothing store might add a custom field to track fabric composition, while a hardware store could add a custom field to store product dimensions.

Through the administration or via the API, users can create and manage custom fields, define their data types (such as text, number, date, etc.), and assign them to specific entities. This allows businesses the ability to extend the default data structure enabling a more tailored and personalized e-commerce experience.

---

---
url: /docs/v6.5/guides/plugins/plugins/framework/custom-field.md
---

# Custom Fields

Custom fields in Shopware refer to additional data fields that can be added to entities such as products, customers, or orders. These fields allow businesses to store and manage extra information that may be specific to their operations.

With custom fields, you can define and store data beyond the standard attributes provided by Shopware. For example, a clothing store might add a custom field to track fabric composition, while a hardware store could add a custom field to store product dimensions.

Through the administration or via the API, users can create and manage custom fields, define their data types (such as text, number, date, etc.), and assign them to specific entities. This allows businesses the ability to extend the default data structure enabling a more tailored and personalized e-commerce experience.

---

---
url: /docs/v6.6/guides/plugins/plugins/framework/custom-field.md
---

# Custom Fields

Custom fields in Shopware refer to additional data fields that can be added to entities such as products, customers, or orders. These fields allow businesses to store and manage extra information that may be specific to their operations.

With custom fields, you can define and store data beyond the standard attributes provided by Shopware. For example, a clothing store might add a custom field to track fabric composition, while a hardware store could add a custom field to store product dimensions.

Through the administration or via the API, users can create and manage custom fields, define their data types (such as text, number, date, etc.), and assign them to specific entities. This allows businesses the ability to extend the default data structure enabling a more tailored and personalized e-commerce experience.

---

---
url: /frontends/guides/features/custom-products.md
---

# Custom Products extension

The example explains how **Custom Products** feature is implemented in `vue-demo-store` template (already done), but also can be used as a guide how to deal with the process in any project.

:::warning Custom Products for Shopware 6 is an extension that is part of the Shopware Rise plan.
[Read more](https://docs.shopware.com/en/shopware-6-en/extensions/customproducts).
:::

## Logic: Composable function

See [the source code](https://github.com/shopware/frontends/blob/main/examples/commercial-customized-products/src/composables/useProductCustomizedProductConfigurator.ts) of `useProductCustomizedProductConfigurator` composable function.

The composable is a main place to keep the logic related to *custom product* features:

* adds TypeScript types
* stores the state
* extracts the custom product's specific data
* exposes method for adding to cart
* serializes the state to be in a correct format for the request's payload (adding to cart)

### Example of usage:

:::warning
Works only if the `useProduct` is fulfilled and the product data is known. Typically on Product Details Page, when the product context is provided.

Visit the \[useProduct]/packages/composables.html#useproduct) reference to see more details.
:::

```ts
// useProductCustomizedProductConfigurator is autoimported
// in vue-demo-store template as it's located in ~/composables
const {
  isActive, // indicates whether product is empowered by Custom Products extension and active
  customizedProduct, // returns the custom product's template data
  state, // state to be used in option selector / forms
  addToCart, // triggers add to cart action (refreshCart() action invoked afterwards)
  handleFileUpload, // uploads an image, then gets mediaId from API and assigns it to the state
} = useProductCustomizedProductConfigurator();
```

## Presentation: Vue component

See [the source code](https://github.com/shopware/frontends/blob/main/examples/commercial-customized-products/src/components/ProductCustomizedProductConfigurator.vue) of the `ProductCustomizedProductConfigurator` Vue component.

The component is responsible for:

* Displaying product options in any type: text field, image upload, select, color select, image select (this one has to be fixed in the core to get the URL's of the images)
* Showing corresponding additional price and currency of an option

## Implementation

Add the mentioned component in a template. For instance in `<ProductStatic/>` for templates that not come from CMS:

```html{9}
<!-- part of templates/vue-demo-store/components/product/ProductStatic.vue -->
<!-- Options -->
<div class="mt-4 lg:mt-0 lg:row-span-3">
  <h2 class="sr-only">Product information</h2>
  <div class="product-variants mt-10">
    <ProductPrice :product="product" />
    <ProductUnits :product="product" class="text-sm" />
    <ProductVariantConfigurator @change="handleVariantChange" />
    <ProductCustomizedProductConfigurator /> <!-- ADDED -->
    <ProductAddToCart :product="product" />
  </div>
</div>
```

Overwrite a logic in `<ProductAddToCart/>` (or any other responsible for adding a product to cart in your template):

```ts{3-6,9-10}
// part of templates/vue-demo-store/components/product/ProductAddToCart.vue;
// the <script setup lang="ts"> section
const {
  addToCart: customizedProductAddToCart,
  isActive: isCustomizedProductActive,
} = useProductCustomizedProductConfigurator();

const addToCartProxy = async () => {
  if (isCustomizedProductActive.value) {
    await customizedProductAddToCart();
  } else {
    await addToCart();
  }
...
```

Used composable function allows to use `addToCart()` method and `isActive` computed property. Both are described in "Example of usage" chapter above.

There was a condition added to use a different method to add to cart a product if the product is enhanced by Custom Product template ([how to set it up](https://docs.shopware.com/en/shopware-6-en/extensions/customproducts)):

* if the product has a Custom Product template, then use `customizedProductAddToCart()` method.
* otherwise, don't change the adding to cart behavior and use the default one

## Known issues

* Missing images for "Image select" option type (reported in the extension repository)
* Missing cover image (aka thumbnail) for Custom Product in the Cart (reported in the extension repository)
* Display selected option for Cart Item ([Issue](https://github.com/shopware/frontends/issues/456) reported)

---

---
url: /frontends/introduction/templates/custom-react-project.md
---
# Custom React project

:::info
This template is a prototype. It shows how to integrate Composable Forntends into React.
::::

## About this project

* **React** and **Next.js** with **App Router**
* It is based on the [vercel-commerce](https://github.com/shopwareLabs/vercel-commerce) template
* It uses the new [api-client](https://www.npmjs.com/package/@shopware/api-client)
* There is **no headless checkout**, we are currently working on supporting the default checkout
* Each page is currently **pre-generated** during build time
  * Vercel supports building partial pages after updating when sending a webhook
  * This feature was not tested with Shopware (see API endpoint [here](https://github.com/shopwareLabs/vercel-commerce/blob/main/lib/shopware/index.ts#L302))

---

---
url: /docs/guides/hosting/configurations/framework/routes.md
---

# Custom routes

## Overview

Your default routes in Shopware 6 are defined in the controllers of the core or your plugins. An example could be the wishlist route:

```php
<?php declare(strict_types=1);

#[Route(path: '/wishlist', name: 'frontend.wishlist.page', options: ['seo' => false], defaults: ['_noStore' => true], methods: ['GET'])]
public function index(Request $request, SalesChannelContext $context): Response
{
    $customer = $context->getCustomer();

    if ($customer !== null && $customer->getGuest() === false) {
        $page = $this->wishlistPageLoader->load($request, $context, $customer);
        $this->hook(new WishlistPageLoadedHook($page, $context));
    } else {
        $page = $this->guestPageLoader->load($request, $context);
        $this->hook(new GuestWishlistPageLoadedHook($page, $context));
    }

    return $this->renderStorefront('@Storefront/storefront/page/wishlist/index.html.twig', ['page' => $page]);
}
```

It defines that your wishlist page is available at `/wishlist`. This is fine for an English-only shop, but for a multilingual shop, you might want to have a different route for each language.

For example, you could have `/wishlist` for English and `/merkliste` for German.

## Configuration

To easily configure those routes, you can use the `routes.yaml` file in ROOT/config/routes/routes.yaml. Symfony loads this file, which allows you to define your custom `paths`, in our case, for the wishlist index page.

```yaml
frontend.wishlist.page:
  path:
    en-GB: '/wishlist'
    de-DE: '/merkliste'
  controller: 'Shopware\Storefront\Controller\WishlistController::index'
  methods: ['GET']
  defaults:
    _noStore: true
    _routeScope: ['storefront']
  options:
    seo: false
```

You can configure the `path` with the **locales** (for example, `de-DE`) your shop uses.

If you want to learn more about routes in Symfony, check out the [Symfony documentation](https://symfony.com/doc/current/routing.html#creating-routes-as-attributes).

---

---
url: /docs/v6.6/guides/hosting/configurations/framework/routes.md
---

# Custom routes

## Overview

Your default routes in Shopware 6 are defined in the controllers of the core or your plugins. An example could be the wishlist route:

```php
<?php declare(strict_types=1);

#[Route(path: '/wishlist', name: 'frontend.wishlist.page', options: ['seo' => false], defaults: ['_noStore' => true], methods: ['GET'])]
public function index(Request $request, SalesChannelContext $context): Response
{
    $customer = $context->getCustomer();

    if ($customer !== null && $customer->getGuest() === false) {
        $page = $this->wishlistPageLoader->load($request, $context, $customer);
        $this->hook(new WishlistPageLoadedHook($page, $context));
    } else {
        $page = $this->guestPageLoader->load($request, $context);
        $this->hook(new GuestWishlistPageLoadedHook($page, $context));
    }

    return $this->renderStorefront('@Storefront/storefront/page/wishlist/index.html.twig', ['page' => $page]);
}
```

It defines that your wishlist page is available at `/wishlist`. This is fine for an English-only shop, but for a multilingual shop, you might want to have a different route for each language.

For example, you could have `/wishlist` for English and `/merkliste` for German.

## Configuration

To easily configure those routes, you can use the `routes.yaml` file in ROOT/config/routes/routes.yaml. Symfony loads this file, which allows you to define your custom `paths`, in our case, for the wishlist index page.

```yaml
frontend.wishlist.page:
  path:
    en-GB: '/wishlist'
    de-DE: '/merkliste'
  controller: 'Shopware\Storefront\Controller\WishlistController::index'
  methods: ['GET']
  defaults:
    _noStore: true
    _routeScope: ['storefront']
  options:
    seo: false
```

You can configure the `path` with the **locales** (for example, `de-DE`) your shop uses.

If you want to learn more about routes in Symfony, check out the [Symfony documentation](https://symfony.com/doc/current/routing.html#creating-routes-as-attributes).

---

---
url: /frontends/introduction/templates/custom-vue-project.md
---
# Custom Vue.js project

Follow these steps to integrate Shopware Frontends into an existing, custom Vue.js project

* Install the required dependencies
* Prepare a Vue plugin for better encapsulation
* Configure the API client and create application instance
* Store and handle client state

## Creating Vue project

:::info
You can skip this part if you have an existing project.
::::

```bash
pnpm create vue@latest
```

More information about creating a new Vue project can be found [here](https://vuejs.org/guide/quick-start.html)

## Install dependencies

First of all, install the required npm dependencies:

```bash
pnpm add @shopware/composables @shopware/api-client
```

Additionally, to keep the current session context even after page reloads, we are going to install a cookie helper to set and get value of [context token](https://shopware.stoplight.io/docs/store-api/ZG9jOjEwODA3NjQx-authentication-and-authorisation) in our plugin:

```bash
pnpm add js-cookie
```

For CMS components, you can add a package that contains ready-to-use components.
You can read more about CMS pages here:

```sh
# ✨ Auto-detect
npx nypm install -D @shopware/cms-base-layer

# npm
npm install -D @shopware/cms-base-layer

# yarn
yarn add -D @shopware/cms-base-layer

# pnpm
pnpm add -D @shopware/cms-base-layer

# bun
bun install -D @shopware/cms-base-layer

# deno
deno install --dev npm:@shopware/cms-base-layer
```

## Configure API client

:::tip Code example
Find a full example of the Vue.js plugin [here](#plugin-code).
:::

Now, let's configure the API client and business logic together.

:::info
The business logic is written to be Vue 3 compatible. Under the hood, it utilizes the composition API, especially the `provide`/`inject` feature for sharing state.
:::

In order to configure the business logic and API client together with your Vue 3 application, it's required to create a Shopware instance provided by a factory method within the `@shopware/composables` package. Everything will be encapsulated in a plugin and installed later on.

:::tip Vue plugins
This section requires having knowledge about the [concept of Vue 3 plugins](https://vuejs.org/guide/reusability/plugins.html#writing-a-plugin).
:::

Import necessary methods from `@shopware/api-client`, `@shopware/composables` and `js-cookie` packages:

```ts
// ./plugins/vue-shopware-frontends.ts file
import { ref } from "vue";
import type { App } from "vue";
import { createAPIClient } from "@shopware/api-client";
import { createShopwareContext } from "@shopware/composables";
import Cookies from "js-cookie";

export default {
  install: (app: App, options: ShopwareFrontendsOptions) => {
    ...
  },
};

```

We prepare some types to be used during the registration of the plugin to pass basic credentials for your Shopware 6 instance.

```ts
export type ShopwareFrontendsOptions = {
  endpoint: string;
  accessToken: string;
  shopwareApiClient?: {
    timeout: number;
  };
  enableDevtools?: boolean;
};
```

Now, once the plugin is created, we need to create an API client instance and the Shopware instance for Vue application.

The install method is a good place to do that:

```ts
const cookieContextToken = Cookies.get("sw-context-token");
const cookieLanguageId = Cookies.get("sw-language-id");

const contextToken = ref(cookieContextToken);
const languageId = ref(cookieLanguageId);

const instance = createInstance({
  endpoint: options.endpoint,
  accessToken: options.accessToken,
  timeout: options.shopwareApiClient?.timeout || 5000,
  contextToken: contextToken.value,
  languageId: languageId.value,
});
```

## Handle client state

:::tip Code example
Complete code example can be found [HERE](./custom-vue-project.html#plugin-code) you can find a full example of the plugin
:::

Now, we need to ensure that the context token, which identifies a user session, is properly stored and updated. The context token may change after operations like login or logout.

Then, we can take advantage of the onConfigChange method. It executes when the API client detects a new value of the context token coming from the API (as a header parameter or in the response body). In that case, the new context token should be saved in the cookie to keep the correct session:

```ts
/**
 * Save current contextToken when it changes
 */
instance.onConfigChange(({ config }) => {
  try {
    Cookies.set("sw-context-token", config.contextToken || "", {
      expires: 365,
      sameSite: "Lax",
      path: "/",
    });
    Cookies.set("sw-language-id", config.languageId || "", {
      expires: 365,
      sameSite: "Lax",
      path: "/",
    });

    contextToken.value = config.contextToken;
    languageId.value = config.languageId;
  } catch (e) {
    // Sometimes cookie is set on server after request is send, it can fail silently
  }
});
```

Another step is to create a Shopware instance that combines API Client and the business logic in composables to be used in entire Vue application:

```ts
const shopwareContext = createShopwareContext(app, {
  enableDevtools: !!options.enableDevtools, // decide if devtools should be enabled
});
```

And the last step is to provide the shopwareContext:

```ts
app.provide("apiClient", apiClient);
app.provide("shopware", shopwareContext);
// thanks to this, `shopwareContext` can be injected in a component and other Vue-instance-aware places (like composables).
app.provide("swSessionContext", ref());
```

## Register the plugin

```ts{6,9-14}
// main.ts
import { createApp } from "vue";
import "./style.css";
import App from "./App.vue";
// import previously implemented module
import ShopwareFrontends from "./plugins/vue-shopware-frontends";
const app = createApp(App);

app.use(ShopwareFrontends, {
    // pass options described under ShopwareFrontendsOptions type in the previous section
    endpoint: "https://demo-frontends.swstage.store",
    accessToken: "SWSCBHFSNTVMAWNZDNFKSHLAYW",
    apiDefaults: {},
});

app.mount("#app");
```

## Plugin code

```ts
// ./plugins/vue-shopware-frontends.ts file
import { ref } from "vue";
import type { App } from "vue";
import { createAPIClient } from "@shopware/api-client";
import { createShopwareContext } from "@shopware/composables";
import Cookies from "js-cookie";

// Types to be used during the registration of the plugin to pass basic credentials for your Shopware 6 instance.
export type ShopwareFrontendsOptions = {
  endpoint: string;
  accessToken: string;
  shopwareApiClient?: {
    timeout: number;
  };
  enableDevtools?: boolean;
};

export default {
  install: (app: App, options: ShopwareFrontendsOptions) => {
    const cookieContextToken = Cookies.get("sw-context-token");
    const cookieLanguageId = Cookies.get("sw-language-id");

    const contextToken = ref(cookieContextToken);
    const languageId = ref(cookieLanguageId);

    const apiClient = createAPIClient<operations>({
      baseURL: options.endpoint,
      accessToken: options.accessToken,
      contextToken: contextToken.value,
    });

    const shopwareContext = createShopwareContext(app, {
      enableDevtools: !!options.enableDevtools,
    });

    app.provide("apiClient", apiClient);
    app.provide("shopware", shopwareContext);
    app.provide("swSessionContext", ref());
  },
};
```

## Shopware Endpoint on the SSR mode

It may happen that for SSR and CSR, you need two different shopware endpoints. One of the most common situations is when you are using an internal network for communication between apps.

```
Server URL to the backend: http://shopware (not exposed)
Client URL to the backend  https://demo-frontends.shopware.store (exposed)
```

If you are using the Nuxt plugin, you can set private and public envs:

```
NUXT_SHOPWARE_ENDPOINT=http://shopware
NUXT_PUBLIC_SHOPWARE_ENDPOINT=https://demo-frontends.shopware.store
```

Otherwise, make sure that you are setting different values on the create instance phase

```ts
const instance = createInstance({
  endpoint: ssrValue || clientValue,
  accessToken: options.accessToken,
  timeout: options.shopwareApiClient?.timeout || 5000,
  contextToken: contextToken.value,
  languageId: languageId.value,
});
```

:::warning
If you need to redirect your media, you can use the `shopware.yaml` file to configure the main media URL.
For more details, please visit this [site](https://developer.shopware.com/docs/guides/hosting/infrastructure/filesystem.html#flysystem-overview).
:::

## Next steps

After your setup, you can follow our building guides to get started with Shopware Frontends

---

---
url: /docs/v6.5/guides/plugins/plugins/api/customer-specific-pricing.md
---

# Customer-specific Pricing

The Customer-specific pricing feature allows massive advances in the pricing model capabilities in the Shopware 6 ecosystem.

The API interface exposed by this module allows the user to operate a set of commands which will enable the granular overriding of prices via an external data repository or ERP system. This is achieved by defining a custom relationship between the current price and the Customer entity.

## Pre-requisites and setup

Customer-specific pricing is part of the Commercial plugin, requiring an existing Shopware 6 installation and the activated Shopware 6 Commercial plugin. This Commercial plugin can be installed as per the [install instructions](../../../../guides/plugins/plugins/plugin-base-guide#install-your-plugin). In addition, the `Custom Prices` feature needs to be activated within the relevant merchant account.

## Working with the API route

To create, alter and/or delete customer-specific prices, you can use the API endpoint `/api/_action/custom-price`. Like with any other admin request in Shopware, you must first authenticate yourself. Therefore, please head over to the
[authentication guide](https://shopware.stoplight.io/docs/admin-api/ZG9jOjEwODA3NjQx-authentication) for details.

Otherwise, the Customer-specific Pricing API interface models itself upon the interface of the [sync API](https://shopware.stoplight.io/docs/admin-api/twpxvnspkg3yu-quick-start-guide), so you will be able to package your requests similarly.

::: info
You can use the route with single `upsert` and `delete` actions or even combine those in a single request: you can pack several different commands inside one sync API request, and each of them is executed in an independent and isolated way
:::

So, it's not surprising that the request body looks like a familiar sync request. In the payload for the `upsert` action, you pass the following data:

* `productId`: The product whose price should be overwritten.
* `customerId`: The customer for whom we will assign a custom price.
* `price`: The new custom price you want to use.

This way, we come to use a payload as seen in the example below:

```json
[
  {
    "action": "upsert",
    "payload": [
      {
        "productId": "0001e32041ac451386bf9b7351c540f3",
        "customerId": "02a3c82b5ca842c492f8656029b2e63e",
        "price": [
          {
            "quantityStart": 1,
            "quantityEnd": null,
            "price": [
              {
                "currencyId": "b7d2554b0ce847cd82f3ac9bd1c0dfca",
                "gross": 682.0,
                "net": 682.0,
                "linked": true
              }
            ]
          }
        ]
      }
    ]
  }
]
```

For the `delete` action, the workflow operation accepts 3 different array of ids: `customerIds`, `productIds`, or `customerGroupIds`. Here, you can specify any combination of these id arrays, with the exception that the API route must have at least one UUID supplied in one of the id arrays (`customerIds`, `productIds`, or `customerGroupIds`)

```json
[
  {
    "action": "delete",
    "payload": [
      {
        "productIds": [
          "0001e32041ac451386bf9b7351c540f3",
          "363a6985f6434a7493b1ef3dabeed40f"
        ],
        "customerIds": [
          "53fc38877a510a47b0e0c44f1615f0c5"
        ],
        "customerGroupIds": []
      }
    ]
  }
]
```

::: info
In case of an error occurs, the response will not return an error code - which is typical for the sync API; instead, any validation errors will be stored within the `errors` key.
:::

::: warning
When working with this route, one difference sets it apart from the familiar `sync` requests: You cannot specify headers to adapt the endpoint's behavior.
:::

## Known caveats or issues

When working with custom prices, there are currently some caveats or issues to keep in mind:

* Price filtering (within the product listing page) will *currently* not support the overridden prices.
* ElasticSearch product mapping does not currently support Customer-specific Pricing data.
* Optional header flags within the core `sync` API are not supported within the provided endpoint (`indexing-behavior, single-operation`). Indexing of any relevant database (product) data is handled on a per-request basis without the need to specify indexing handling.
* The `customerGroupId` parameter within a Customer-specific Pricing API request body is a stub implementation to avoid breaking changes in future versions and is not currently functional. Any data provided for this parameter will not affect the Storefront.

---

---
url: /docs/v6.6/guides/plugins/plugins/api/customer-specific-pricing.md
---

# Customer-specific Pricing

The Customer-specific pricing feature allows massive advances in the pricing model capabilities in the Shopware 6 ecosystem.

The API interface exposed by this module allows the user to operate a set of commands which will enable the granular overriding of prices via an external data repository or ERP system. This is achieved by defining a custom relationship between the current price and the Customer entity.

## Pre-requisites and setup

Customer-specific pricing is part of the Commercial plugin, requiring an existing Shopware 6 installation and the activated Shopware 6 Commercial plugin. This Commercial plugin can be installed as per the [install instructions](../../../../guides/plugins/plugins/plugin-base-guide#install-your-plugin). In addition, the `Custom Prices` feature needs to be activated within the relevant merchant account.

## Working with the API route

To create, alter and/or delete customer-specific prices, you can use the API endpoint `/api/_action/custom-price`. Like with any other admin request in Shopware, you must first authenticate yourself. Therefore, please head over to the
[authentication guide](https://shopware.stoplight.io/docs/admin-api/ZG9jOjEwODA3NjQx-authentication) for details.

Otherwise, the Customer-specific Pricing API interface models itself upon the interface of the [sync API](https://shopware.stoplight.io/docs/admin-api/twpxvnspkg3yu-quick-start-guide), so you will be able to package your requests similarly.

::: info
You can use the route with single `upsert` and `delete` actions or even combine those in a single request: you can pack several different commands inside one sync API request, and each of them is executed in an independent and isolated way
:::

So, it's not surprising that the request body looks like a familiar sync request. In the payload for the `upsert` action, you pass the following data:

* `productId`: The product whose price should be overwritten.
* `customerId`: The customer for whom we will assign a custom price.
* `price`: The new custom price you want to use.

This way, we come to use a payload as seen in the example below:

```json
[
  {
    "action": "upsert",
    "payload": [
      {
        "productId": "0001e32041ac451386bf9b7351c540f3",
        "customerId": "02a3c82b5ca842c492f8656029b2e63e",
        "price": [
          {
            "quantityStart": 1,
            "quantityEnd": null,
            "price": [
              {
                "currencyId": "b7d2554b0ce847cd82f3ac9bd1c0dfca",
                "gross": 682.0,
                "net": 682.0,
                "linked": true
              }
            ]
          }
        ]
      }
    ]
  }
]
```

For the `delete` action, the workflow operation accepts 3 different array of ids: `customerIds`, `productIds`, or `customerGroupIds`. Here, you can specify any combination of these id arrays, with the exception that the API route must have at least one UUID supplied in one of the id arrays (`customerIds`, `productIds`, or `customerGroupIds`)

```json
[
  {
    "action": "delete",
    "payload": [
      {
        "productIds": [
          "0001e32041ac451386bf9b7351c540f3",
          "363a6985f6434a7493b1ef3dabeed40f"
        ],
        "customerIds": [
          "53fc38877a510a47b0e0c44f1615f0c5"
        ],
        "customerGroupIds": []
      }
    ]
  }
]
```

::: info
In case of an error occurs, the response will not return an error code - which is typical for the sync API; instead, any validation errors will be stored within the `errors` key.
:::

::: warning
When working with this route, one difference sets it apart from the familiar `sync` requests: You cannot specify headers to adapt the endpoint's behavior.
:::

## Known caveats or issues

When working with custom prices, there are currently some caveats or issues to keep in mind:

* Price filtering (within the product listing page) will *currently* not support the overridden prices.
* ElasticSearch product mapping does not currently support Customer-specific Pricing data.
* Optional header flags within the core `sync` API are not supported within the provided endpoint (`indexing-behavior, single-operation`). Indexing of any relevant database (product) data is handled on a per-request basis without the need to specify indexing handling.
* The `customerGroupId` parameter within a Customer-specific Pricing API request body is a stub implementation to avoid breaking changes in future versions and is not currently functional. Any data provided for this parameter will not affect the Storefront.

---

---
url: >-
  /docs/guides/plugins/plugins/integrations/commercial/customer-specific-pricing.md
---

# Customer-Specific Pricing

## Overview

The Customer-specific pricing feature enables significant advances in pricing model capabilities in the Shopware 6 ecosystem.

The API interface exposed by this module allows the user to execute a set of commands that enable granular price overrides via an external data repository or ERP system. This is achieved by defining a custom relationship between the current price and the Customer entity.

## Pre-requisites and setup

Customer-specific pricing is part of the Commercial plugin and requires an existing Shopware 6 installation and the activated Shopware 6 Commercial plugin. This Commercial plugin can be installed as per the [install instructions](../../../../../guides/plugins/plugins/plugin-base-guide.md#install-your-plugin). In addition, the `Custom Prices` feature needs to be activated within the relevant merchant account.

## Working with the API route

To create, alter, and/or delete customer-specific prices, you can use the API endpoint `/api/_action/custom-price`. Like with any other admin request in Shopware, you must first authenticate yourself. Therefore, please head over to the
[authentication guide](https://shopware.stoplight.io/docs/admin-api/authentication) for details.

Otherwise, the Customer-specific Pricing API interface models itself on the [sync API](https://shopware.stoplight.io/docs/admin-api/twpxvnspkg3yu-quick-start-guide), so you can package your requests similarly.

::: info
You can use the route with a single `upsert` and `delete` action, or combine them in a single request: you can pack several different commands into a single sync API request, and each is executed in an independent, isolated way.
:::

So, it's not surprising that the request body looks like a familiar sync request. In the payload for the `upsert` action, you pass the following data:

* `productId`: The product whose price should be overwritten.
* `customerId`: The customer for whom we will assign a custom price.
* `price`: The new custom price you want to use.

This way, we come to use a payload as seen in the example below:

```json
[
 {
    "action": "upsert",
    "payload": [
 {
        "productId": "0001e32041ac451386bf9b7351c540f3",
        "customerId": "02a3c82b5ca842c492f8656029b2e63e",
        "price": [
 {
            "quantityStart": 1,
            "quantityEnd": null,
            "price": [
 {
                "currencyId": "b7d2554b0ce847cd82f3ac9bd1c0dfca",
                "gross": 682.0,
                "net": 682.0,
                "linked": true
 }
 ]
 }
 ]
 }
 ]
 }
]
```

For the `delete` action, the workflow operation accepts 3 different arrays of ids: `customerIds`, `productIds`, or `customerGroupIds`. Here, you can specify any combination of these ID arrays, with the exception that the API route must have at least one UUID supplied in one of the ID arrays (`customerIds`, `productIds`, or `customerGroupIds`)

```json
[
 {
    "action": "delete",
    "payload": [
 {
        "productIds": [
          "0001e32041ac451386bf9b7351c540f3",
          "363a6985f6434a7493b1ef3dabeed40f"
 ],
        "customerIds": [
          "53fc38877a510a47b0e0c44f1615f0c5"
 ],
        "customerGroupIds": []
 }
 ]
 }
]
```

::: info
In case an error occurs, the response will not return an error code, which is typical for the sync API; instead, any validation errors will be stored within the `errors` key.
:::

::: warning
When working with this route, one difference sets it apart from the familiar `sync` requests: You cannot specify headers to adapt the endpoint's behavior.
:::

## Known caveats or issues

When working with custom prices, there are currently some caveats or issues to keep in mind:

* Price filtering (within the product listing page) will *currently* not support the overridden prices.
* ElasticSearch product mapping does not currently support Customer-specific Pricing data.
* Optional header flags within the core `sync` API are not supported within the provided endpoint (`indexing-behavior, single-operation`). Indexing of any relevant database (product) data is handled on a per-request basis, without the need to specify indexing.
* The `customerGroupId` parameter within a Customer-specific Pricing API request body is a stub implementation to avoid breaking changes in future versions and is not currently functional. Any data provided for this parameter will not affect the Storefront.

---

---
url: >-
  /docs/resources/references/adr/2020-09-08-custom-field-label-loading-in-storefront.md
---

# CustomField label loading in storefront

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2020-09-08-custom-field-label-loading-in-storefront.md)
:::

## Context

We want to provide the labels of custom fields in the storefront to third party developers.
On one hand we could add the labels to every loaded entity, but this will cause a heavy leak of performance and the labels
are often not used in the template.

## Decision

We implemented a subscriber, which listen on the `custom_field.written` event to add also snippets to all snippet sets with
the given label translations of the custom field. The `translationKey` of the snippets are prefixed with `customFields.`,
followed by the technical name of the custom field. Thus the snippets can be used in the storefront.

## Consequences

Inserting a custom field always creates new snippet with the given label translations.

---

---
url: >-
  /docs/v6.5/resources/references/adr/2020-09-08-custom-field-label-loading-in-storefront.md
---

# CustomField label loading in storefront

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2020-09-08-custom-field-label-loading-in-storefront.md)
:::

## Context

We want to provide the labels of custom fields in the storefront to third party developers.
On one hand we could add the labels to every loaded entity, but this will cause a heavy leak of performance and the labels
are often not used in the template.

## Decision

We implemented a subscriber, which listen on the `custom_field.written` event to add also snippets to all snippet sets with
the given label translations of the custom field. The `translationKey` of the snippets are prefixed with `customFields.`,
followed by the technical name of the custom field. Thus the snippets can be used in the storefront.

## Consequences

Inserting a custom field always creates new snippet with the given label translations.

---

---
url: >-
  /docs/v6.6/resources/references/adr/2020-09-08-custom-field-label-loading-in-storefront.md
---

# CustomField label loading in storefront

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2020-09-08-custom-field-label-loading-in-storefront.md)
:::

## Context

We want to provide the labels of custom fields in the storefront to third party developers.
On one hand we could add the labels to every loaded entity, but this will cause a heavy leak of performance and the labels
are often not used in the template.

## Decision

We implemented a subscriber, which listen on the `custom_field.written` event to add also snippets to all snippet sets with
the given label translations of the custom field. The `translationKey` of the snippets are prefixed with `customFields.`,
followed by the technical name of the custom field. Thus the snippets can be used in the storefront.

## Consequences

Inserting a custom field always creates new snippet with the given label translations.

---

---
url: /frontends/guides/cms/customize-components.md
---

# Customize Components

:::info Only for `cms-base` package
The directory structure is only relevant, if you want to customize the components of the `cms-base` package. If you are using a custom template, you can place components where you want, because you handle their resolution by yourself. In that case skip to [Create Elements](./create-elements).
:::

### Create new files

In order to customize a component, you need to override it. The process is the same regardless what type of component you want to override

* Sections
* Blocks
* Elements

To do so, you need to create a file with the same name as the component in the `components` directory or wherever according to the project's configuration.

```json
demo-store/
├─ components/
|  ├─ cms/
|  ├─ ├─ CmsBlockImageHighlightRow.vue
```

Now the CMS module will automatically resolve that file based on the name and you can start writing your component.

## Internal components

❗**Internal components are not a part of public API. Once overwritten you need to track the changes on your own.**

There is also a possibility to override the internal components, shared between public blocks and elements, the ones starting with `Sw` prefix, like [SwSlider.vue](https://github.com/shopware/frontends/blob/main/packages/cms-base-layer/app/components/SwSlider.vue) or [SwProductCard.vue](https://github.com/shopware/frontends/blob/main/packages/cms-base-layer/app/components/SwProductCard.vue).

### Additional Example

---

---
url: /docs/guides/plugins/plugins/storefront/templates/customize-header-footer.md
---

# Customize Header/Footer

## Overview

With the introduction of ESI loading for the header and footer, the way how to customize the header and footer has changed.
E.g. it is no longer possible to customize the header and footer depending on the current page data.

This guide will show you how to customize the header and footer in your plugin.

## Prerequisites

Refer to the [Plugin Base Guide](../../plugin-base-guide.md). Knowing [Twig](https://twig.symfony.com/) is an advantage but not necessary.

## Customizing by bypassing the ESI loading

The ESI loading of header and footer was introduced as they are parts of the page that usually do not change that often and could therefore stay cached for a longer time.
The header and footer are now loaded with sub-requests and are therefore no longer dependent on the current page data.
It is still possible to add custom data to the header and footer directly, see ["Add data to storefront page"](../controllers/add-data-to-storefront-page.md) guide for more information.

But if you need to customize the header or footer depending on the current page data you need to adjust the ESI loading with additional parameters.
This happens in the `Storefront/Resources/views/storefront/base.html.twig` [file](https://github.com/shopware/shopware/blob/6.7.0.0/src/Storefront/Resources/views/storefront/base.html.twig#L38).
The needed block names are `base_esi_header` and `base_esi_footer`.
Extend the `base.html.twig` in your plugin and overwrite for example the header block.

::: code-group

```twig [PLUGIN_ROOT/src/Resources/views/storefront/base.html.twig]
{% sw_extends '@Storefront/storefront/base.html.twig' %}

{% block base_esi_header %}
    {% set headerParameters = headerParameters|merge({ 'vendorPrefixPluginName': { 'activeRoute': activeRoute } }) %}
    {{ parent() }}
{% endblock %}
```

:::

The `headerParameters` are passed to the header route as query parameters and after that passed through to the header template.
With this change you are now able to access the current route in your header template:

::: code-group

```twig [PLUGIN_ROOT/src/Resources/views/storefront/layout/header.html.twig]
{% sw_extends '@Storefront/storefront/layout/header.html.twig' %}

{% block header %}
    {{ dump(headerParameters.vendorPrefixPluginName.activeRoute) }}
    {{ parent() }}
{% endblock %}
```

:::

This approach works both in plugins and apps.
In plugins, you can also use the `StorefrontRenderEvent`, to add custom data to the header and footer:

::: code-group

```php [PLUGIN_ROOT/src/StorefrontSubscriber.php]
class StorefrontSubscriber
{
    public function __invoke(StorefrontRenderEvent $event): void
    {
        if ($event->getRequest()->attributes->get('_route') !== 'frontend.header') {
            return;
        }

        $headerParameters = $event->getParameter('headerParameters') ?? [];
        $headerParameters['vendorPrefixPluginName']['salesChannelId'] = $event->getSalesChannelContext()->getSalesChannelId();

        $event->setParameter('headerParameters', $headerParameters);
    }
}
```

```twig [PLUGIN_ROOT/src/Resources/views/storefront/layout/header.html.twig]
{% sw_extends '@Storefront/storefront/layout/header.html.twig' %}

{% block header %}
    {{ dump(headerParameters.vendorPrefixPluginName.salesChannelId) }}
    {{ parent() }}
{% endblock %}
```

:::

::: warning
Please be aware, that `headerParameters` and `footerParameters` can only contain scalar values, as they are also query parameters for the ESI routes.
:::

It is also possible to load your custom header or footer templates.
This is also done in the core itself within the checkout process.
See e.g. the [checkout confirm page](https://github.com/shopware/shopware/blob/6.7.0.0/src/Storefront/Resources/views/storefront/page/checkout/confirm/index.html.twig#L3-L5).
Please be aware, that this will overwrite customizations from every other extension.
You also need to make sure, that the `header` and `footer` data is available, if your custom template extends from the original header or footer template.
See e.g. the [checkout confirm controller](https://github.com/shopware/shopware/blob/6.7.0.0/src/Storefront/Controller/CheckoutController.php#L152-L159).

---

---
url: /docs/v6.5/guides/plugins/plugins/administration/customizing-modules.md
---

# Customize modules

## Overview

In the `Administration` core code, each module is defined in a directory called `module`. A `module` is an encapsulated unit which implements a whole feature. For example there are modules for customers, orders, settings, etc.

## Prerequisites

All you need for this guide is a running Shopware 6 instance. Of course, you'll have to understand JavaScript and have a basic familiarity with TwigJS, the templating engine, used in the Administration. However, that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation.

## Customizing a module

Module settings like `color`, `icon`, `navigation` are fixed by design and cannot be changed.

A guide for customizing components, which are already defined in existing modules, can be found here - [Customizing components](customizing-components).

However, modules themselves cannot be directly overridden.

At some point you need to add or change the routes of a module. For example when you want to add a tab to the page.

This is done by creating a new module and implementing a `routeMiddleware`. You can add those changes to your `main.js` file, which could then look like this:

```javascript
// <plugin root>/src/Resources/app/administration/src/main.js
Shopware.Module.register('my-new-custom-route', {
    routeMiddleware(next, currentRoute) {
        if (currentRoute.name === 'sw.product.detail') {
            currentRoute.children.push({
                name: 'sw.product.detail.custom',
                path: '/sw/product/detail/:id/custom',
                component: 'sw-product-detail-custom',
                meta: {
                    parentPath: "sw.product.index"
                }
            });
        }
        next(currentRoute);
    }
});
```

In this example we register a new module which uses the `routeMiddleWare` to scan the routes while the `Vue router` is being set up. If we find the route `sw.product.detail` we just add another child route by pushing it to the `currentRoute.children`.

You can find a detailed example in the [Add tab to existing module](add-new-tab) guide.

## More interesting topics

* [Customizing components](customizing-components)
* [Adding a route](add-custom-route)

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/administration/module-component-management/customizing-modules.md
---

# Customize modules

## Overview

In the `Administration` core code, each module is defined in a directory called `module`. A `module` is an encapsulated unit which implements a whole feature. For example there are modules for customers, orders, settings, etc.

## Prerequisites

All you need for this guide is a running Shopware 6 instance. Of course, you'll have to understand JavaScript and have a basic familiarity with TwigJS, the templating engine, used in the Administration. However, that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation.

## Customizing a module

Module settings like `color`, `icon`, `navigation` are fixed by design and cannot be changed.

A guide for customizing components, which are already defined in existing modules, can be found here - [Customizing components](../module-component-management/customizing-components.md) ..

However, modules themselves cannot be directly overridden.

At some point you need to add or change the routes of a module. For example when you want to add a tab to the page.

This is done by creating a new module and implementing a `routeMiddleware`. You can add those changes to your `main.js` file, which could then look like this:

```javascript
// <plugin root>/src/Resources/app/administration/src/main.js
Shopware.Module.register('my-new-custom-route', {
    routeMiddleware(next, currentRoute) {
        if (currentRoute.name === 'sw.product.detail') {
            currentRoute.children.push({
                name: 'sw.product.detail.custom',
                path: '/sw/product/detail/:id/custom',
                component: 'sw-product-detail-custom',
                meta: {
                    parentPath: "sw.product.index"
                }
            });
        }
        next(currentRoute);
    }
});
```

In this example we register a new module which uses the `routeMiddleWare` to scan the routes while the `Vue router` is being set up. If we find the route `sw.product.detail` we just add another child route by pushing it to the `currentRoute.children`.

You can find a detailed example in the [Add tab to existing module](../routing-navigation/add-new-tab.md) guide.

## More interesting topics

* [Customizing components](../module-component-management/customizing-components.md)
* [Adding a route](../routing-navigation/add-custom-route.md)

---

---
url: >-
  /docs/guides/plugins/plugins/administration/module-component-management/customizing-modules.md
---

# Customize Modules

## Overview

In the `Administration` core code, each module is defined in a directory called `module`. A `module` is an encapsulated unit which implements a whole feature. For example there are modules for customers, orders, settings, etc.

## Prerequisites

All you need for this guide is a running Shopware 6 instance. Of course, you'll have to understand JavaScript and have a basic familiarity with TwigJS, the templating engine, used in the Administration. However, that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation.

## Customizing a module

Module settings like `color`, `icon`, `navigation` are fixed by design and cannot be changed.

A guide for customizing components, which are already defined in existing modules, can be found here - [Customizing components](../module-component-management/customizing-components.md) ..

However, modules themselves cannot be directly overridden.

At some point you need to add or change the routes of a module. For example when you want to add a tab to the page.

This is done by creating a new module and implementing a `routeMiddleware`. You can add those changes to your `main.js` file, which could then look like this:

```javascript
// <plugin root>/src/Resources/app/administration/src/main.js
Shopware.Module.register('my-new-custom-route', {
    routeMiddleware(next, currentRoute) {
        if (currentRoute.name === 'sw.product.detail') {
            currentRoute.children.push({
                name: 'sw.product.detail.custom',
                path: '/sw/product/detail/:id/custom',
                component: 'sw-product-detail-custom',
                meta: {
                    parentPath: "sw.product.index"
                }
            });
        }
        next(currentRoute);
    }
});
```

In this example we register a new module which uses the `routeMiddleWare` to scan the routes while the `Vue router` is being set up. If we find the route `sw.product.detail` we just add another child route by pushing it to the `currentRoute.children`.

You can find a detailed example in the [Add tab to existing module](../routing-navigation/add-new-tab.md) guide.

## More interesting topics

* [Customizing components](../module-component-management/customizing-components.md)
* [Adding a route](../routing-navigation/add-custom-route.md)

---

---
url: /docs/guides/plugins/plugins/checkout/payment/customize-payment-provider.md
---

# Customize Payment Provider

## Overview

This guide covers how to customize an existing payment provider. In this example we are customizing a synchronous payment flow, but the procedure also applies to an asynchronous approach.

## Prerequisites

Review the [Plugin base guide](../../plugin-base-guide). The guides for [adding a custom payment method](add-payment-plugin) and [adjusting a service](../../services/adjusting-service.md), which provides information about decorating services, are also helpful.

## Customize the payment provider

First, we create a new class that extends from the provider we want to customise.
In this example we customise the class `Shopware\Core\Checkout\Payment\Cart\PaymentHandler\DebitPayment` and name our class `ExampleDebitPayment`.
The constructor has to accept an instance of `OrderTransactionStateHandler` like the original service and additionally an instance of `DebitPayment` that we want to decorate.

After we've created our customized payment provider class, we have to register it to the DI-container via the `services.php`.

::: code-group

```php [ExampleDebitPayment.php]
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Checkout\Order\Aggregate\OrderTransaction\OrderTransactionStateHandler;
use Shopware\Core\Checkout\Payment\Cart\PaymentHandler\DebitPayment;
use Shopware\Core\Checkout\Payment\Cart\SyncPaymentTransactionStruct;
use Shopware\Core\Framework\Validation\DataBag\RequestDataBag;
use Shopware\Core\Framework\Context;
use Shopware\Core\Framework\Struct\Struct;
use Shopware\Core\System\SalesChannel\SalesChannelContext;
use Symfony\Component\HttpFoundation\Request;

class ExampleDebitPayment extends DebitPayment
{
    private DebitPayment $decorated;

    public function __construct(OrderTransactionStateHandler $transactionStateHandler, DebitPayment $decorated)
    {
        parent::__construct($transactionStateHandler);
        $this->decorated = $decorated;
    }

    public function getDecorated(): DebitPayment
    {
        return $this->decorated;
    }

    public function pay(Request $request, PaymentTransactionStruct $transaction, Context $context, ?Struct $validateStruct): ?RedirectResponse
    {
        // do some custom stuff here

        $this->transactionStateHandler->process($transaction->getOrderTransaction()->getId(), $salesChannelContext->getContext());
    }
}
```

```php [services.php]
<?php declare(strict_types=1);

use Shopware\Core\Checkout\Order\Aggregate\OrderTransaction\OrderTransactionStateHandler;
use Shopware\Core\Checkout\Payment\Cart\PaymentHandler\DebitPayment;
use Swag\BasicExample\Service\ExampleDebitPayment;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(ExampleDebitPayment::class)
        ->decorate(DebitPayment::class)
        ->args([
            service(OrderTransactionStateHandler::class),
            service('.inner'),
        ]);
};
```

:::

---

---
url: >-
  /docs/v6.5/guides/plugins/plugins/checkout/payment/customize-payment-provider.md
---

# Customize Payment Provider

## Overview

In this guide you'll learn how to customize an existing payment provider. In this example we are customizing a `SynchronousPaymentHandler`, but the procedure also applies to `AsynchronousPaymentHandler`.

## Prerequisites

As most guides, this guide is also built upon the [Plugin base guide](../../plugin-base-guide), but you don't necessarily need that. It is helpful to have looked at the guide about [adding a custom payment method](add-payment-plugin) beforehand. Furthermore, decorating a service is also not explained here, but it's covered in our guide about [adjusting a service](../../plugin-fundamentals/adjusting-service), so having this open in another tab won't hurt.

## Customize the payment provider

First, we create a new class that extends from the provider we want to customise. In this example we customise the class `Shopware\Core\Checkout\Payment\Cart\PaymentHandler\DebitPayment` and name our class `ExampleDebitPayment`. The constructor has to accept an instance of `OrderTransactionStateHandler` like the original service and additionally an instance of `DebitPayment` that we want to decorate.

```php
// <plugin root>/src/Service/ExampleDebitPayment.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Checkout\Order\Aggregate\OrderTransaction\OrderTransactionStateHandler;
use Shopware\Core\Checkout\Payment\Cart\PaymentHandler\DebitPayment;
use Shopware\Core\Checkout\Payment\Cart\SyncPaymentTransactionStruct;
use Shopware\Core\Framework\Validation\DataBag\RequestDataBag;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class ExampleDebitPayment extends DebitPayment
{
    private DebitPayment $decorated;

    public function __construct(OrderTransactionStateHandler $transactionStateHandler, DebitPayment $decorated)
    {
        parent::__construct($transactionStateHandler);
        $this->decorated = $decorated;
    }

    public function getDecorated(): DebitPayment
    {
        return $this->decorated;
    }

    public function pay(SyncPaymentTransactionStruct $transaction, RequestDataBag $dataBag, SalesChannelContext $salesChannelContext): void
    {
        // do some custom stuff here

        $this->transactionStateHandler->process($transaction->getOrderTransaction()->getId(), $salesChannelContext->getContext());
    }
}
```

After we've created our customized payment provider class, we have to register it to the DI-container.

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Service\ExampleDebitPayment" decorates="Shopware\Core\Checkout\Payment\Cart\PaymentHandler\DebitPayment">
            <argument type="service" id="Shopware\Core\Checkout\Order\Aggregate\OrderTransaction\OrderTransactionStateHandler"/>
            <argument type="service" id="Swag\BasicExample\Service\ExampleDebitPayment.inner"/>
        </service>
    </services>
</container>
```

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/checkout/payment/customize-payment-provider.md
---

# Customize Payment Provider

## Overview

In this guide you'll learn how to customize an existing payment provider. In this example we are customizing a `SynchronousPaymentHandler`, but the procedure also applies to `AsynchronousPaymentHandler`.

## Prerequisites

As most guides, this guide is also built upon the [Plugin base guide](../../plugin-base-guide), but you don't necessarily need that. It is helpful to have looked at the guide about [adding a custom payment method](add-payment-plugin) beforehand. Furthermore, decorating a service is also not explained here, but it's covered in our guide about [adjusting a service](../../plugin-fundamentals/adjusting-service), so having this open in another tab won't hurt.

## Customize the payment provider

First, we create a new class that extends from the provider we want to customise. In this example we customise the class `Shopware\Core\Checkout\Payment\Cart\PaymentHandler\DebitPayment` and name our class `ExampleDebitPayment`. The constructor has to accept an instance of `OrderTransactionStateHandler` like the original service and additionally an instance of `DebitPayment` that we want to decorate.

```php
// <plugin root>/src/Service/ExampleDebitPayment.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Checkout\Order\Aggregate\OrderTransaction\OrderTransactionStateHandler;
use Shopware\Core\Checkout\Payment\Cart\PaymentHandler\DebitPayment;
use Shopware\Core\Checkout\Payment\Cart\SyncPaymentTransactionStruct;
use Shopware\Core\Framework\Validation\DataBag\RequestDataBag;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class ExampleDebitPayment extends DebitPayment
{
    private DebitPayment $decorated;

    public function __construct(OrderTransactionStateHandler $transactionStateHandler, DebitPayment $decorated)
    {
        parent::__construct($transactionStateHandler);
        $this->decorated = $decorated;
    }

    public function getDecorated(): DebitPayment
    {
        return $this->decorated;
    }

    public function pay(SyncPaymentTransactionStruct $transaction, RequestDataBag $dataBag, SalesChannelContext $salesChannelContext): void
    {
        // do some custom stuff here

        $this->transactionStateHandler->process($transaction->getOrderTransaction()->getId(), $salesChannelContext->getContext());
    }
}
```

After we've created our customized payment provider class, we have to register it to the DI-container.

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>

<container xmlns="http://symfony.com/schema/dic/services"
xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Service\ExampleDebitPayment" decorates="Shopware\Core\Checkout\Payment\Cart\PaymentHandler\DebitPayment">
            <argument type="service" id="Shopware\Core\Checkout\Order\Aggregate\OrderTransaction\OrderTransactionStateHandler"/>
            <argument type="service" id="Swag\BasicExample\Service\ExampleDebitPayment.inner"/>
        </service>
    </services>
</container>
```

---

---
url: /docs/guides/plugins/plugins/checkout/cart/customize-price-calculation.md
---

# Customize Price Calculation

## Overview

This guide explains how to globally adjust the calculation of product prices by decorating a single service, and includes a brief example.

## Prerequisites

Review the [plugin base guide](../../plugin-base-guide.md) and the guide on [adjusting a service](../../services/adjusting-service.md) for guidance on service decoration.

## Decorating the calculator

In order to customize the price calculation for products as a whole, you'll have to decorate the service [ProductPriceCalculator](https://github.com/shopware/shopware/blob/trunk/src/Core/Content/Product/SalesChannel/Price/ProductPriceCalculator.php). It comes with a `calculate` method, which you can decorate and therefore customize.

So let's do that real quick. If you're looking for an in-depth explanation, head over to our guide about [adjusting a service](../../services/adjusting-service.md).

Here's an example decorated calculator:

```php
// <plugin root>/src/Service/CustomProductPriceCalculator.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Content\Product\SalesChannel\Price\AbstractProductPriceCalculator;
use Shopware\Core\Content\Product\SalesChannel\SalesChannelProductEntity;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class CustomProductPriceCalculator extends AbstractProductPriceCalculator
{
    /**
     * @var AbstractProductPriceCalculator
     */
    private AbstractProductPriceCalculator $productPriceCalculator;

    public function __construct(AbstractProductPriceCalculator $productPriceCalculator)
    {
        $this->productPriceCalculator = $productPriceCalculator;
    }

    public function getDecorated(): AbstractProductPriceCalculator
    {
        return $this->productPriceCalculator;
    }

    public function calculate(iterable $products, SalesChannelContext $context): void
    {
        /** @var SalesChannelProductEntity $product */
        foreach ($products as $product) {
            $price = $product->getPrice();
            // Just an example!
            // A product can have more than one price, which you also have to consider.
            // Also you might have to change the value of "getCheapestPrice"!
            $price->first()->setGross(100);
            $price->first()->setNet(50);
        }

        $this->getDecorated()->calculate($products, $context);
    }
}
```

So what is done here? The constructor gets passed the inner instance of `AbstractProductPriceCalculator`, most likely the `ProductPriceCalculator` itself. This will be used to call the original `calculate` method later on. You also have to return that instance in your `getDecorated` method.

Inside the overridden `calculate` method, we're iterating over each product and we straight forward set new prices. Of course this is just an example to show how you can now manipulate a product's prices.

Most likely you also want to narrow down which product's prices you want to edit, as in this example we're adjusting every single product and setting them all to the same price. You might want to have a look at the original [calculate method](https://github.com/shopware/shopware/blob/trunk/src/Core/Content/Product/SalesChannel/Price/ProductPriceCalculator.php#L45-L58) to see how calculating a price is done in the core code.

### Registering the decorator

Do not forget to actually register your decoration to the service container, otherwise it will not have any effect.

```php
// <plugin root>/src/Resources/config/services.php
<?php declare(strict_types=1);

use Shopware\Core\Content\Product\SalesChannel\Price\ProductPriceCalculator;
use Swag\BasicExample\Service\CustomProductPriceCalculator;
use Symfony\Component\DependencyInjection\Loader\Configurator\ContainerConfigurator;

use function Symfony\Component\DependencyInjection\Loader\Configurator\service;

return static function (ContainerConfigurator $configurator): void {
    $services = $configurator->services();

    $services->set(CustomProductPriceCalculator::class)
        ->decorate(ProductPriceCalculator::class)
        ->args([
            service('.inner'),
        ]);
};
```

## Next steps

Instead of manipulating a product's price, you can also try to add a discount or a surcharge to the cart. This is explained in our guide about [adding cart discounts](add-cart-discounts.md).

---

---
url: /docs/v6.5/guides/plugins/plugins/checkout/cart/customize-price-calculation.md
---

# Customize Price Calculation

## Overview

There are cases where you globally want to adjust the calculation of product prices. This can be achieved in Shopware by decorating a single service.

This guide will cover this subject with a short example.

## Prerequisites

As most guides, this guide is also built upon our [plugin base guide](../../plugin-base-guide), but it's not mandatory to use exactly that plugin as a foundation. The examples in this guide use the namespace however.

Furthermore, you'll have to understand service decoration for this guide, so if you're not familiar with that, head over to our guide regarding [adjusting a service](../../plugin-fundamentals/adjusting-service).

## Decorating the calculator

In order to customize the price calculation for products as a whole, you'll have to decorate the service [ProductPriceCalculator](https://github.com/shopware/shopware/blob/trunk/src/Core/Content/Product/SalesChannel/Price/ProductPriceCalculator.php). It comes with a `calculate` method, which you can decorate and therefore customize.

So let's do that real quick. If you're looking for an in-depth explanation, head over to our guide about [adjusting a service](../../plugin-fundamentals/adjusting-service).

Here's an example decorated calculator:

```php
// <plugin root>/src/Service/CustomProductPriceCalculator.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Content\Product\SalesChannel\Price\AbstractProductPriceCalculator;
use Shopware\Core\Content\Product\SalesChannel\SalesChannelProductEntity;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class CustomProductPriceCalculator extends AbstractProductPriceCalculator
{
    /**
     * @var AbstractProductPriceCalculator
     */
    private AbstractProductPriceCalculator $productPriceCalculator;

    public function __construct(AbstractProductPriceCalculator $productPriceCalculator)
    {
        $this->productPriceCalculator = $productPriceCalculator;
    }

    public function getDecorated(): AbstractProductPriceCalculator
    {
        return $this->productPriceCalculator;
    }

    public function calculate(iterable $products, SalesChannelContext $context): void
    {
        /** @var SalesChannelProductEntity $product */
        foreach ($products as $product) {
            $price = $product->getPrice();
            // Just an example!
            // A product can have more than one price, which you also have to consider.
            // Also you might have to change the value of "getCheapestPrice"!
            $price->first()->setGross(100);
            $price->first()->setNet(50);
        }

        $this->getDecorated()->calculate($products, $context);
    }
}
```

So what is done here? The constructor gets passed the inner instance of `AbstractProductPriceCalculator`, most likely the `ProductPriceCalculator` itself. This will be used to call the original `calculate` method later on. You also have to return that instance in your `getDecorated` method.

Inside the overridden `calculate` method, we're iterating over each product and we straight forward set new prices. Of course this is just an example to show how you can now manipulate a product's prices.

Most likely you also want to narrow down which product's prices you want to edit, as in this example we're adjusting every single product and setting them all to the same price. You might want to have a look at the original [calculate method](https://github.com/shopware/shopware/blob/trunk/src/Core/Content/Product/SalesChannel/Price/ProductPriceCalculator.php#L45-L58) to see how calculating a price is done in the core code.

### Registering the decorator

Do not forget to actually register your decoration to the service container, otherwise it will not have any effect.

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Service\CustomProductPriceCalculator" decorates="Shopware\Core\Content\Product\SalesChannel\Price\ProductPriceCalculator">
            <argument type="service" id="Swag\BasicExample\Service\CustomProductPriceCalculator.inner" />
        </service>
    </services>
</container>
```

## Next steps

Instead of manipulating a product's price, you can also try to add a discount or a surcharge to the cart. This is explained in our guide about [adding cart discounts](add-cart-discounts).

---

---
url: /docs/v6.6/guides/plugins/plugins/checkout/cart/customize-price-calculation.md
---

# Customize Price Calculation

## Overview

There are cases where you globally want to adjust the calculation of product prices. This can be achieved in Shopware by decorating a single service.

This guide will cover this subject with a short example.

## Prerequisites

As most guides, this guide is also built upon our [plugin base guide](../../plugin-base-guide), but it's not mandatory to use exactly that plugin as a foundation. The examples in this guide use the namespace however.

Furthermore, you'll have to understand service decoration for this guide, so if you're not familiar with that, head over to our guide regarding [adjusting a service](../../plugin-fundamentals/adjusting-service).

## Decorating the calculator

In order to customize the price calculation for products as a whole, you'll have to decorate the service [ProductPriceCalculator](https://github.com/shopware/shopware/blob/trunk/src/Core/Content/Product/SalesChannel/Price/ProductPriceCalculator.php). It comes with a `calculate` method, which you can decorate and therefore customize.

So let's do that real quick. If you're looking for an in-depth explanation, head over to our guide about [adjusting a service](../../plugin-fundamentals/adjusting-service).

Here's an example decorated calculator:

```php
// <plugin root>/src/Service/CustomProductPriceCalculator.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Service;

use Shopware\Core\Content\Product\SalesChannel\Price\AbstractProductPriceCalculator;
use Shopware\Core\Content\Product\SalesChannel\SalesChannelProductEntity;
use Shopware\Core\System\SalesChannel\SalesChannelContext;

class CustomProductPriceCalculator extends AbstractProductPriceCalculator
{
    /**
     * @var AbstractProductPriceCalculator
     */
    private AbstractProductPriceCalculator $productPriceCalculator;

    public function __construct(AbstractProductPriceCalculator $productPriceCalculator)
    {
        $this->productPriceCalculator = $productPriceCalculator;
    }

    public function getDecorated(): AbstractProductPriceCalculator
    {
        return $this->productPriceCalculator;
    }

    public function calculate(iterable $products, SalesChannelContext $context): void
    {
        /** @var SalesChannelProductEntity $product */
        foreach ($products as $product) {
            $price = $product->getPrice();
            // Just an example!
            // A product can have more than one price, which you also have to consider.
            // Also you might have to change the value of "getCheapestPrice"!
            $price->first()->setGross(100);
            $price->first()->setNet(50);
        }

        $this->getDecorated()->calculate($products, $context);
    }
}
```

So what is done here? The constructor gets passed the inner instance of `AbstractProductPriceCalculator`, most likely the `ProductPriceCalculator` itself. This will be used to call the original `calculate` method later on. You also have to return that instance in your `getDecorated` method.

Inside the overridden `calculate` method, we're iterating over each product and we straight forward set new prices. Of course this is just an example to show how you can now manipulate a product's prices.

Most likely you also want to narrow down which product's prices you want to edit, as in this example we're adjusting every single product and setting them all to the same price. You might want to have a look at the original [calculate method](https://github.com/shopware/shopware/blob/trunk/src/Core/Content/Product/SalesChannel/Price/ProductPriceCalculator.php#L45-L58) to see how calculating a price is done in the core code.

### Registering the decorator

Do not forget to actually register your decoration to the service container, otherwise it will not have any effect.

```xml
// <plugin root>/src/Resources/config/services.xml
<?xml version="1.0" ?>
<container xmlns="http://symfony.com/schema/dic/services"
           xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance"
           xsi:schemaLocation="http://symfony.com/schema/dic/services http://symfony.com/schema/dic/services/services-1.0.xsd">

    <services>
        <service id="Swag\BasicExample\Service\CustomProductPriceCalculator" decorates="Shopware\Core\Content\Product\SalesChannel\Price\ProductPriceCalculator">
            <argument type="service" id="Swag\BasicExample\Service\CustomProductPriceCalculator.inner" />
        </service>
    </services>
</container>
```

## Next steps

Instead of manipulating a product's price, you can also try to add a discount or a surcharge to the cart. This is explained in our guide about [adding cart discounts](add-cart-discounts).

---

---
url: /docs/guides/plugins/apps/storefront/customize-templates.md
---

# Customize Templates

## Overview

This guide will cover customizing Storefront templates using an app.

## Prerequisites

Before you begin, make sure you have:

* A basic understanding of [Shopware app development](../app-base-guide.md).
* Familiarity with the [Twig template](https://twig.symfony.com/) is beneficial.

## Getting started

This guide assumes you have already set up your Shopware app. If not, refer to the [app base guide](../app-base-guide.md) for the initial setup.

The following sections give you a very short example of how you can extend a storefront block. For simplicity's sake, only the page logo is replaced with a 'Hello world!' text.

### Setting up app's view directory

First of all, in your app's root, register your app's own view path, which basically represents a path in which Shopware 6 is looking for template-files. By default, Shopware 6 is looking for a directory called `views` in your app's `Resources` directory, so the path could look like this: `<app root>/Resources/views`

### Locating the template

As mentioned earlier, this guide is only trying to replace the 'demo' logo with a 'Hello world!' text. In order to find the proper template, you can simply search for the term 'logo' inside the `<shopware root>/src/Storefront` directory. This will eventually lead you to [this file](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Storefront/Resources/views/storefront/layout/header/logo.html.twig).

::: info
The [FroshDevelopmentHelper](https://github.com/FriendsOfShopware/FroshDevelopmentHelper) plugin adds hints about template blocks and includes into the rendered HTML. This way, it's easier to actually find the proper template.
:::

### Overriding the template

Now that you have found the proper template for the logo, you can override it.

Overriding this file now requires you to copy the exact same directory structure starting from the `views` directory for your custom file. In this case, the file `logo.html.twig` is located in a directory called `storefront/layout/header`, so make sure to remember this path.

Finally, you have to set up the following directory path in your app: `<app root>/Resources/views/storefront/layout/header`. Next, create a new file called `logo.html.twig`, just like the original file. Once more to understand what's going on here: In the Storefront code, the path to the logo file looks like this: `Storefront/Resources/views/storefront/layout/header/logo.html.twig`. Now have a look at the path being used in your app: `<app root>/Resources/views/storefront/layout/header/logo.html.twig`

Starting from the `views` directory, the path is **exactly the same**, and that's the important part for your custom template to be loaded automatically.

### Customizing the template

First extend from the original file, to override its blocks. Now fill your custom `logo.html.twig` file.

Put this line at the very beginning of your file:

```twig
{% sw_extends '@Storefront/storefront/layout/header/logo.html.twig' %}
```

This is simply extending the `logo.html.twig` file from the Storefront bundle. If you would leave the file like that, it wouldn't change anything, as you are currently just extending from the original file with no overrides.

To replace the logo with some custom text, take a look at the block called `layout_header_logo_link` in the original file. Its contents create an anchor tag, which is not necessary for our case anymore, so this seems to be a great block to override.

To override it now, just add the very same block into your custom file and replace its contents:

```twig
{% sw_extends '@Storefront/storefront/layout/header/logo.html.twig' %}

{% block layout_header_logo_link %}
    <h2>Hello world!</h2>
{% endblock %}
```

If you wanted to append your text to the logo instead of replacing it, you could add a line like this to your override: {{ parent() }}

And that's it, you are done. However, you might have to clear the cache and refresh your storefront to see your changes in action. This can be done by using the following command:

```bash
./bin/console cache:clear
```

::: info
Also remember to not only activate your app but also to assign your theme to the correct sales channel by clicking on it in the sidebar, going to the tab Theme and selecting your theme.
:::

### Finding variables

Of course, this example is very simplified and does not use any variables, even though you most likely want to do that. Using variables is exactly the same as in [Twig](https://twig.symfony.com/doc/3.x/templates.html#variables) in general, so this won't be explained here in detail. However, this is how you use a variable: {{ variableName }}

But how do you know which variables are available to use? For this, you can just dump all available variables:

```twig
{{ dump() }}
```

This `dump()` call will print out all variables available on this page.

::: info
[FroshDevelopmentHelper](https://github.com/FriendsOfShopware/FroshDevelopmentHelper) adds all available page data to the Twig tab in the profiler when opening a request, and its details as well. This might help here as well.
:::

## Storefront Components

Since Shopware 6.7.11.0, a new component system is available which offers the possibility to build atomic template components which can be reused in a composable way throughout the Storefront.

To learn more about how to use Storefront Components in your app, refer to the main documentation of [Storefront Components](../../../../concepts/framework/storefront-components).

---

---
url: /docs/guides/plugins/plugins/storefront/templates/customize-templates.md
---

# Customize Templates

## Overview

This guide will cover customizing Storefront templates with a plugin.

## Prerequisites

* Familiarity with the [Plugin base guide](../../plugin-base-guide.md) and how to create plugins
* Knowledge of [Twig](https://twig.symfony.com/) is advantageous but not necessary

## Getting started

In this guide you will see a very short example on how you can extend a storefront block.
For simplicity's sake, only the logo is replaced with a 'Hello world!' text.

### Setting up your view directory

First of all you need to register your plugin's own view path, which basically represents a path in which Shopware 6 is looking for template-files.
By default, Shopware 6 is looking for a directory called `views` in your plugin's `Resources` directory, so the path could look like this: `<plugin root>/src/Resources/views`

### Finding the proper template

As mentioned earlier, this guide is only trying to replace the 'demo' logo with a 'Hello world!' text.
In order to find the proper template, you can simply search for the term 'logo' inside the `<shopware root>/src/Storefront` directory.
This will eventually lead you to [this file](https://github.com/shopware/shopware/blob/v6.6.10.2/src/Storefront/Resources/views/storefront/layout/header/logo.html.twig).

Overriding this file now requires you to copy the exact same directory structure starting from the `views` directory.
In this case, the file `logo.html.twig` is located in a directory called `storefront/layout/header`, so make sure to remember this path.

::: info
There's a plugin out there called [FroshDevelopmentHelper](https://github.com/FriendsOfShopware/FroshDevelopmentHelper), that adds hints about template blocks and includes into the rendered HTML. This way it's easier to actually find the proper template.
:::

### Overriding the template

Now, that you've found the proper template for the logo, you can override it.

This is done by creating the very same directory structure for your custom file, which is also being used in the Storefront core.
As you hopefully remember, you have to set up the following directory path in your plugin: `<plugin root>/src/Resources/views/storefront/layout/header`.
In there you want to create a new file called `logo.html.twig`, just like the original file.
Once more to understand what's going on here: In the Storefront code, the path to the logo file looks like this: `Storefront/Resources/views/storefront/layout/header/logo.html.twig`.
Now have a look at the path being used in your plugin: `<plugin root>/src/Resources/views/storefront/layout/header/logo.html.twig`

Starting from the `views` directory, the path is **exactly the same**, and that's the important part for your custom template to be loaded automatically.

### Custom template content

It's time to fill your custom `logo.html.twig` file.
First of all you want to extend from the original file, so you can override its blocks.

Put this line at the very beginning of your file:

```twig
{% sw_extends '@Storefront/storefront/layout/header/logo.html.twig' %}
```

This is simply extending the `logo.html.twig` file from the Storefront bundle.
If you left the file like that, it wouldn't change anything, as you're currently just extending from the original file with no overrides.

You want to replace the logo with some custom text though, so let's have a look at the original file.
In there you'll find a block called `layout_header_logo_link`.
Its contents then would create an anchor tag, which is not necessary for our case anymore, so this seems to be a great block to override.

To override it now, just add the very same block into your custom file and replace its contents:

```twig
{% sw_extends '@Storefront/storefront/layout/header/logo.html.twig' %}

{% block layout_header_logo_link %}
    <h2>Hello world!</h2>
{% endblock %}
```

If you wanted to append your text to the logo instead of replacing it, you could add a line like this to your override: {{ parent() }}

And that's it already, you're done.
You might have to clear the cache and refresh your storefront to see your changes in action.
This can be done by using the command following command inside your command line:

```bash
./bin/console cache:clear
```

::: info
Also remember to not only activate your plugin but also to assign your theme to the correct sales channel by clicking on it in the sidebar, going to the tab Theme and selecting your theme.
:::

### Finding variables

Of course this example is very simplified and does not use any variables, even though you most likely want to do that.
Using variables is exactly the same as in [Twig](https://twig.symfony.com/doc/3.x/templates.html#variables) in general, so this won't be explained here in detail.
Still, this is how you use a variable: {{ variableName }}

But rather than that, how do you know which variables are available to use? For this case, you can just dump all available variables:

```twig
{{ dump() }}
```

This `dump()` call will print out all variables available on this page.

::: info
Once again, the plugin called [FroshDevelopmentHelper](https://github.com/FriendsOfShopware/FroshDevelopmentHelper) adds all available page data to the Twig tab in the profiler, when opening a request and its details. This might help here as well.
:::

## Storefront Components

Since Shopware 6.7.11.0, a new component system is available which offers the possibility to build atomic template components which can be reused in a composable way throughout the Storefront.

To learn more about how to use Storefront Components in your plugin, refer to the main documentation of [Storefront Components](../../../../../concepts/framework/storefront-components.md).

## Next steps

You are able to customize templates now, which is a good start.
However, there are a few more things you should definitely learn here:

* [Adding styles](../styling/add-custom-styling.md)
* [Adding translations](../styling/add-translations.md)
* [Using icons](../styling/add-icons.md)
* [Using custom assets](../styling/add-custom-assets.md)

---

---
url: /docs/v6.5/guides/plugins/apps/storefront/customize-templates.md
---

# Customize Templates

## Overview

This guide will cover customizing Storefront templates using an app.

## Prerequisites

Before you begin, make sure you have:

* A basic understanding of [Shopware app development](../app-base-guide).
* Familiarity with the [Twig template](https://twig.symfony.com/) is beneficial.

## Getting started

This guide assumes you have already set up your Shopware app. If not, refer to the [app base guide](../app-base-guide) for the initial setup.

The following sections give you a very short example of how you can extend a storefront block. For simplicity's sake, only the page logo is replaced with a 'Hello world!' text.

### Setting up app's view directory

First of all, in your app's root, register your app's own view path, which basically represents a path in which Shopware 6 is looking for template-files. By default, Shopware 6 is looking for a directory called `views` in your app's `Resources` directory, so the path could look like this: `<app root>/src/Resources/views`

### Locating the template

As mentioned earlier, this guide is only trying to replace the 'demo' logo with a 'Hello world!' text. In order to find the proper template, you can simply search for the term 'logo' inside the `<shopware root>/src/Storefront` directory. This will eventually lead you to [this file](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Storefront/Resources/views/storefront/layout/header/logo.html.twig).

::: info
There's a plugin out there called [FroshDevelopmentHelper](https://github.com/FriendsOfShopware/FroshDevelopmentHelper), that adds hints about template blocks and includes into the rendered HTML. This way, it's easier to actually find the proper template.
:::

### Overriding the template

Now that you have found the proper template for the logo, you can override it.

Overriding this file now requires you to copy the exact same directory structure starting from the `views` directory for your custom file. In this case, the file `logo.html.twig` is located in a directory called `storefront/layout/header`, so make sure to remember this path.

Finally, you have to set up the following directory path in your app: `<app root>/src/Resources/views/storefront/layout/header`. Next, create a new file called `logo.html.twig`, just like the original file. Once more to understand what's going on here: In the Storefront code, the path to the logo file looks like this: `Storefront/Resources/views/storefront/layout/header/logo.html.twig`. Now have a look at the path being used in your app: `<app root>/src/Resources/views/storefront/layout/header/logo.html.twig`

Starting from the `views` directory, the path is **exactly the same**, and that's the important part for your custom template to be loaded automatically.

### Customizing the template

First extend from the original file, to override its blocks. Now fill your custom `logo.html.twig` file.

Put this line at the very beginning of your file:

```twig
{% sw_extends '@Storefront/storefront/layout/header/logo.html.twig' %}
```

This is simply extending the `logo.html.twig` file from the Storefront bundle. If you would leave the file like that, it wouldn't change anything, as you are currently just extending from the original file with no overrides.

To replace the logo with some custom text, take a look at the block called `layout_header_logo_link` in the original file. Its contents create an anchor tag, which is not necessary for our case anymore, so this seems to be a great block to override.

To override it now, just add the very same block into your custom file and replace its contents:

```twig
{% sw_extends '@Storefront/storefront/layout/header/logo.html.twig' %}

{% block layout_header_logo_link %}
    <h2>Hello world!</h2>
{% endblock %}
```

If you wanted to append your text to the logo instead of replacing it, you could add a line like this to your override: {{ parent() }}

And that's it, you are done. However, you might have to clear the cache and refresh your storefront to see your changes in action. This can be done by using the following command:

```bash
./bin/console cache:clear
```

::: info
Also remember to not only activate your app but also to assign your theme to the correct sales channel by clicking on it in the sidebar, going to the tab Theme and selecting your theme.
:::

### Finding variables

Of course, this example is very simplified and does not use any variables, even though you most likely want to do that. Using variables is exactly the same as in [Twig](https://twig.symfony.com/doc/3.x/templates.html#variables) in general, so this won't be explained here in detail. However, this is how you use a variable: {{ variableName }}

But how do you know which variables are available to use? For this, you can just dump all available variables:

```twig
{{ dump() }}
```

This `dump()` call will print out all variables available on this page.

::: info
Once again, the plugin called [FroshDevelopmentHelper](https://github.com/FriendsOfShopware/FroshDevelopmentHelper) adds all available page data to the Twig tab in the profiler, when opening a request and its details. This might help here as well.
:::

---

---
url: /docs/v6.5/guides/plugins/plugins/storefront/customize-templates.md
---

# Customize Templates

## Overview

This guide will cover customizing Storefront templates with a plugin.

## Prerequisites

As most guides, this guide is built upon the [Plugin base guide](../plugin-base-guide), so you might want to have a look at it. Other than that, knowing [Twig](https://twig.symfony.com/) is a big advantage for this guide, but that's not necessary.

## Getting started

In this guide you will see a very short example on how you can extend a storefront block. For simplicity's sake, only the logo is replaced with a 'Hello world!' text.

### Setting up your view directory

First of all you need to register your plugin's own view path, which basically represents a path in which Shopware 6 is looking for template-files. By default, Shopware 6 is looking for a directory called `views` in your plugin's `Resources` directory, so the path could look like this: `<plugin root>/src/Resources/views`

### Finding the proper template

As mentioned earlier, this guide is only trying to replace the 'demo' logo with a 'Hello world!' text. In order to find the proper template, you can simply search for the term 'logo' inside of the `<shopware root>/src/Storefront` directory. This will eventually lead you to [this file](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Storefront/Resources/views/storefront/layout/header/logo.html.twig).

Overriding this file now requires you to copy the exact same directory structure starting from the `views` directory. In this case, the file `logo.html.twig` is located in a directory called `storefront/layout/header`, so make sure to remember this path.

::: info
There's a plugin out there called [FroshDevelopmentHelper](https://github.com/FriendsOfShopware/FroshDevelopmentHelper), that adds hints about template blocks and includes into the rendered HTML. This way it's easier to actually find the proper template.
:::

### Overriding the template

Now, that you've found the proper template for the logo, you can override it.

This is done by creating the very same directory structure for your custom file, which is also being used in the Storefront core. As you hopefully remember, you have to set up the following directory path in your plugin: `<plugin root>/src/Resources/views/storefront/layout/header` In there you want to create a new file called `logo.html.twig`, just like the original file. Once more to understand what's going on here: In the Storefront code, the path to the logo file looks like this: `Storefront/Resources/views/storefront/layout/header/logo.html.twig` Now have a look at the path being used in your plugin: `<plugin root>/src/Resources/views/storefront/layout/header/logo.html.twig`

Starting from the `views` directory, the path is **exactly the same**, and that's the important part for your custom template to be loaded automatically.

### Custom template content

It's time to fill your custom `logo.html.twig` file. First of all you want to extend from the original file, so you can override its blocks.

Put this line at the very beginning of your file:

```twig
{% sw_extends '@Storefront/storefront/layout/header/logo.html.twig' %}
```

This is simply extending the `logo.html.twig` file from the Storefront bundle. If you would leave the file like that, it wouldn't change anything, as you're currently just extending from the original file with no overrides.

You want to replace the logo with some custom text though, so let's have a look at the original file. In there you'll find a block called `layout_header_logo_link`. Its contents then would create an anchor tag, which is not necessary for our case anymore, so this seems to be a great block to override.

To override it now, just add the very same block into your custom file and replace its contents:

```twig
{% sw_extends '@Storefront/storefront/layout/header/logo.html.twig' %}

{% block layout_header_logo_link %}
    <h2>Hello world!</h2>
{% endblock %}
```

If you wanted to append your text to the logo instead of replacing it, you could add a line like this to your override: {{ parent() }}

And that's it already, you're done. You might have to clear the cache and refresh your storefront to see your changes in action. This can be done by using the command following command inside your command line:

```bash
./bin/console cache:clear
```

::: info
Also remember to not only activate your plugin but also to assign your theme to the correct sales channel by clicking on it in the sidebar, going to the tab Theme and selecting your theme.
:::

### Finding variables

Of course this example is very simplified and does not use any variables, even though you most likely want to do that. Using variables is exactly the same like in [Twig](https://twig.symfony.com/doc/3.x/templates.html#variables) in general, so this won't be explained here in detail. Still, this is how you use a variable: `{{ variableName }}`

But rather than that, how do you know which variables are available to use? For this case, you can just dump all available variables:

```twig
{{ dump() }}
```

This `dump()` call will print out all variables available on this page.

::: info
Once again, the plugin called [FroshDevelopmentHelper](https://github.com/FriendsOfShopware/FroshDevelopmentHelper) adds all available page data to the Twig tab in the profiler, when opening a request and its details. This might help here as well.
:::

## Next steps

You are able to customize templates now, which is a good start. However, there are a few more things you should definitely learn here:

* [Adding styles](add-custom-styling)
* [Adding translations](add-translations)
* [Using icons](add-icons)
* [Using custom assets](add-custom-assets)

---

---
url: /docs/v6.6/guides/plugins/apps/storefront/customize-templates.md
---

# Customize Templates

## Overview

This guide will cover customizing Storefront templates using an app.

## Prerequisites

Before you begin, make sure you have:

* A basic understanding of [Shopware app development](../app-base-guide).
* Familiarity with the [Twig template](https://twig.symfony.com/) is beneficial.

## Getting started

This guide assumes you have already set up your Shopware app. If not, refer to the [app base guide](../app-base-guide) for the initial setup.

The following sections give you a very short example of how you can extend a storefront block. For simplicity's sake, only the page logo is replaced with a 'Hello world!' text.

### Setting up app's view directory

First of all, in your app's root, register your app's own view path, which basically represents a path in which Shopware 6 is looking for template-files. By default, Shopware 6 is looking for a directory called `views` in your app's `Resources` directory, so the path could look like this: `<app root>/Resources/views`

### Locating the template

As mentioned earlier, this guide is only trying to replace the 'demo' logo with a 'Hello world!' text. In order to find the proper template, you can simply search for the term 'logo' inside the `<shopware root>/src/Storefront` directory. This will eventually lead you to [this file](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Storefront/Resources/views/storefront/layout/header/logo.html.twig).

::: info
There's a plugin out there called [FroshDevelopmentHelper](https://github.com/FriendsOfShopware/FroshDevelopmentHelper), that adds hints about template blocks and includes into the rendered HTML. This way, it's easier to actually find the proper template.
:::

### Overriding the template

Now that you have found the proper template for the logo, you can override it.

Overriding this file now requires you to copy the exact same directory structure starting from the `views` directory for your custom file. In this case, the file `logo.html.twig` is located in a directory called `storefront/layout/header`, so make sure to remember this path.

Finally, you have to set up the following directory path in your app: `<app root>/Resources/views/storefront/layout/header`. Next, create a new file called `logo.html.twig`, just like the original file. Once more to understand what's going on here: In the Storefront code, the path to the logo file looks like this: `Storefront/Resources/views/storefront/layout/header/logo.html.twig`. Now have a look at the path being used in your app: `<app root>/Resources/views/storefront/layout/header/logo.html.twig`

Starting from the `views` directory, the path is **exactly the same**, and that's the important part for your custom template to be loaded automatically.

### Customizing the template

First extend from the original file, to override its blocks. Now fill your custom `logo.html.twig` file.

Put this line at the very beginning of your file:

```twig
{% sw_extends '@Storefront/storefront/layout/header/logo.html.twig' %}
```

This is simply extending the `logo.html.twig` file from the Storefront bundle. If you would leave the file like that, it wouldn't change anything, as you are currently just extending from the original file with no overrides.

To replace the logo with some custom text, take a look at the block called `layout_header_logo_link` in the original file. Its contents create an anchor tag, which is not necessary for our case anymore, so this seems to be a great block to override.

To override it now, just add the very same block into your custom file and replace its contents:

```twig
{% sw_extends '@Storefront/storefront/layout/header/logo.html.twig' %}

{% block layout_header_logo_link %}
    <h2>Hello world!</h2>
{% endblock %}
```

If you wanted to append your text to the logo instead of replacing it, you could add a line like this to your override: {{ parent() }}

And that's it, you are done. However, you might have to clear the cache and refresh your storefront to see your changes in action. This can be done by using the following command:

```bash
./bin/console cache:clear
```

::: info
Also remember to not only activate your app but also to assign your theme to the correct sales channel by clicking on it in the sidebar, going to the tab Theme and selecting your theme.
:::

### Finding variables

Of course, this example is very simplified and does not use any variables, even though you most likely want to do that. Using variables is exactly the same as in [Twig](https://twig.symfony.com/doc/3.x/templates.html#variables) in general, so this won't be explained here in detail. However, this is how you use a variable: {{ variableName }}

But how do you know which variables are available to use? For this, you can just dump all available variables:

```twig
{{ dump() }}
```

This `dump()` call will print out all variables available on this page.

::: info
Once again, the plugin called [FroshDevelopmentHelper](https://github.com/FriendsOfShopware/FroshDevelopmentHelper) adds all available page data to the Twig tab in the profiler, when opening a request and its details. This might help here as well.
:::

---

---
url: /docs/v6.6/guides/plugins/plugins/storefront/customize-templates.md
---

# Customize Templates

## Overview

This guide will cover customizing Storefront templates with a plugin.

## Prerequisites

As most guides, this guide is built upon the [Plugin base guide](../plugin-base-guide), so you might want to have a look at it. Other than that, knowing [Twig](https://twig.symfony.com/) is a big advantage for this guide, but that's not necessary.

## Getting started

In this guide you will see a very short example on how you can extend a storefront block. For simplicity's sake, only the logo is replaced with a 'Hello world!' text.

### Setting up your view directory

First of all you need to register your plugin's own view path, which basically represents a path in which Shopware 6 is looking for template-files. By default, Shopware 6 is looking for a directory called `views` in your plugin's `Resources` directory, so the path could look like this: `<plugin root>/src/Resources/views`

### Finding the proper template

As mentioned earlier, this guide is only trying to replace the 'demo' logo with a 'Hello world!' text. In order to find the proper template, you can simply search for the term 'logo' inside of the `<shopware root>/src/Storefront` directory. This will eventually lead you to [this file](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Storefront/Resources/views/storefront/layout/header/logo.html.twig).

Overriding this file now requires you to copy the exact same directory structure starting from the `views` directory. In this case, the file `logo.html.twig` is located in a directory called `storefront/layout/header`, so make sure to remember this path.

::: info
There's a plugin out there called [FroshDevelopmentHelper](https://github.com/FriendsOfShopware/FroshDevelopmentHelper), that adds hints about template blocks and includes into the rendered HTML. This way it's easier to actually find the proper template.
:::

### Overriding the template

Now, that you've found the proper template for the logo, you can override it.

This is done by creating the very same directory structure for your custom file, which is also being used in the Storefront core. As you hopefully remember, you have to set up the following directory path in your plugin: `<plugin root>/src/Resources/views/storefront/layout/header` In there you want to create a new file called `logo.html.twig`, just like the original file. Once more to understand what's going on here: In the Storefront code, the path to the logo file looks like this: `Storefront/Resources/views/storefront/layout/header/logo.html.twig` Now have a look at the path being used in your plugin: `<plugin root>/src/Resources/views/storefront/layout/header/logo.html.twig`

Starting from the `views` directory, the path is **exactly the same**, and that's the important part for your custom template to be loaded automatically.

### Custom template content

It's time to fill your custom `logo.html.twig` file. First of all you want to extend from the original file, so you can override its blocks.

Put this line at the very beginning of your file:

```twig
{% sw_extends '@Storefront/storefront/layout/header/logo.html.twig' %}
```

This is simply extending the `logo.html.twig` file from the Storefront bundle. If you would leave the file like that, it wouldn't change anything, as you're currently just extending from the original file with no overrides.

You want to replace the logo with some custom text though, so let's have a look at the original file. In there you'll find a block called `layout_header_logo_link`. Its contents then would create an anchor tag, which is not necessary for our case anymore, so this seems to be a great block to override.

To override it now, just add the very same block into your custom file and replace its contents:

```twig
{% sw_extends '@Storefront/storefront/layout/header/logo.html.twig' %}

{% block layout_header_logo_link %}
    <h2>Hello world!</h2>
{% endblock %}
```

If you wanted to append your text to the logo instead of replacing it, you could add a line like this to your override: {{ parent() }}

And that's it already, you're done. You might have to clear the cache and refresh your storefront to see your changes in action. This can be done by using the command following command inside your command line:

```bash
./bin/console cache:clear
```

::: info
Also remember to not only activate your plugin but also to assign your theme to the correct sales channel by clicking on it in the sidebar, going to the tab Theme and selecting your theme.
:::

### Finding variables

Of course this example is very simplified and does not use any variables, even though you most likely want to do that. Using variables is exactly the same like in [Twig](https://twig.symfony.com/doc/3.x/templates.html#variables) in general, so this won't be explained here in detail. Still, this is how you use a variable: `{{ variableName }}`

But rather than that, how do you know which variables are available to use? For this case, you can just dump all available variables:

```twig
{{ dump() }}
```

This `dump()` call will print out all variables available on this page.

::: info
Once again, the plugin called [FroshDevelopmentHelper](https://github.com/FriendsOfShopware/FroshDevelopmentHelper) adds all available page data to the Twig tab in the profiler, when opening a request and its details. This might help here as well.
:::

## Next steps

You are able to customize templates now, which is a good start. However, there are a few more things you should definitely learn here:

* [Adding styles](add-custom-styling)
* [Adding translations](add-translations)
* [Using icons](add-icons)
* [Using custom assets](add-custom-assets)

---

---
url: /docs/v6.5/guides/plugins/plugins/administration/customizing-components.md
---

# Customizing components

The Shopware 6 Administration allows you to override twig blocks to change its content.
This guide will teach you the basics of overriding parts of the Administration.

## Prerequisites

All you need for this guide is a running Shopware 6 instance, the files and preferably a registered module.
Of course, you'll have to understand JavaScript and have a basic familiarity with TwigJS, the templating engine, used in the Administration.
However, that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation.

## Finding the block to override

In this guide we want to change the heading of the Shopware 6 dashboard to be `Welcome to a customized Administration` instead of `Welcome to Shopware 6`.
To do this we first need to find an appropriate twig block to override.
We don't want to replace too much but also to not override too little of the Administration.
In this case we only want to override the headline and not links or anything else on the page.
Looking at the twig markup for the dashboard [here](https://github.com/shopware/shopware/blob/trunk/src/Administration/Resources/app/administration/src/module/sw-dashboard/page/sw-dashboard-index/sw-dashboard-index.html.twig),
suggests that we only need to override the Twig block with the name `sw_dashboard_index_content_intro_content_headline` to achieve our goal.

## Preparing the override

Now that we know where to place our override, we need to decide what to override it with.
In this very simple example it suffices to create a twig file, declare a block with the name we previously found and to insert our new header into the block.

```text
<!-- <plugin root>/src/Resources/app/administration/src/sw-dashboard-index-override/sw-dashboard-index.html.twig -->
{% block sw_dashboard_index_content_intro_content_headline %}
    <h1>
        Welcome to a customized component
    </h1>
{% endblock %}
```

This overrides the entire Twig block with our new markup.
However, if we want to retain the original content of the Twig block and just add our markup to the existing one, we can do that by including a {% parent %} somewhere in the Twig block.
Learn more about the capabilities of twig.js [here](https://github.com/twigjs/twig.js/wiki).

As you might have noticed the heading we just replaced had a `{ $tc() }` [string interpolation](https://vuejs.org/v2/guide/syntax.html#Text) which is used to make it multilingual.
Learn more about internationalization in the Shopware 6 Administration and about adding your own snippets to the Administration [here](adding-snippets).

## Applying the override

Registering the override of the Vue component is done by using the override method of our ComponentFactory.
This could be done in any `.js` file, which then has to be later imported, but we'll place it in `<plugin root>/src/Resources/app/administration/src/sw-dashboard-index-override/index.js`.

```javascript
import template from './sw-dashboard-index.html.twig';

Shopware.Component.override('sw-dashboard-index', {
    template
});
```

The first parameter matches the component to override, the second parameter has to be an object containing the actually overridden properties , e.g. the new twig template extension for this component.

## Loading the JavaScript File

The main entry point to customize the Administration via a plugin is the `main.js` file.
It has to be placed into the `<plugin root>/src/Resources/app/administration/src` directory in order to be automatically found by Shopware 6.

The only thing now left to just add an import for our of previously created `./sw-dashboard-index-override/index.js` in the `main.js`:

```javascript
import './sw-dashboard-index-override/';
```

## More interesting topics

* [Customizing templates](writing-templates)
* [Customizing via custom styles](add-custom-styles)
* [Using base components](using-base-components)

---

---
url: >-
  /docs/v6.6/guides/plugins/plugins/administration/module-component-management/customizing-components.md
---

# Customizing components

The Shopware 6 Administration allows you to override and extend components to change its content and its behavior.

## Prerequisites

All you need for this guide is a running Shopware 6 instance, the files and preferably a registered module.
Of course, you will have to understand JavaScript, Vue and have a basic familiarity with TwigJS block system, and the templating engine used in the Administration. It is just used for the block extending and overriding. Every other feature of TwigJS is not used in the Administration.
However, that is a prerequisite for Shopware as a whole and will not be taught as part of this documentation.

## General

To add new functionality or change the behavior of an existing component, you can either override or extend the component.

The difference between the two methods is that with `Component.extend()` a new component is created. With `Component.override()`, on the other hand, the previous behavior of the component is simply overwritten.

## Override a component

The following example shows how you can override the template of the `sw-text-field` component.

```JS
// import the new twig-template file
import template from './sw-text-field-new.html.twig';

// override the existing component `sw-text-field` by passing the new configuration
Shopware.Component.override('sw-text-field', {
    template
});
```

## Extending a component

To create your custom text-field `sw-custom-field` based on the existing `sw-text-field` you can implement it like the following:

```JS
// import the custom twig-template file
import template from './sw-custom-field.html.twig';

// extend the existing component `sw-text-field` by passing
// a new component name and the new configuration
Shopware.Component.extend('sw-custom-field', 'sw-text-field', {
    template
});
```

Now you can render your new component `sw-custom-field` in any template like this:

```twig
    <sw-custom-field></sw-custom-field>
```

## Customize a component template

To extend a given template you can use the Twig `block` feature.

Imagine, the component you want to extend/override has the following template:

```twig
{% block card %}
    <div class="sw-card">
        {% block card_header %}
            <div class="sw-card--header">
                {{ header }}
            </div>
        {% endblock %}

        {% block card_content %}
            <div class="sw-card--content">
                {{ content }}
            </div>
        {% endblock %}
    </div>
{% endblock %}
```

Maybe you want to replace the markup of the header section and add an extra block to the content.
With the Twig `block` feature you can implement a solution like this:

```twig
{# override/replace an existing block #}
{% block card_header %}
    <h1 class="custom-header">
        {{ header }}
    </h1>
{% endblock %}

{% block card_content %}

    {# render the original block #}
    {% parent %}

    <div class="card-custom-content">
        ...
    </div>
{% endblock %}
```

Summarized with the `block` feature you will be able to replace blocks inside a template.
Additionally, you can render the original markup of a block by using `{% parent %}`

## Extending methods and computed properties

Sometimes you need to change the logic of a method or a computed property while you are extending/overriding a component.
In the following example we extend the `sw-text-field` component and change the `onInput()` method, which gets called after the value of the input field changes.

```JS
// extend the existing component `sw-text-field` by passing
// a new component name and the new configuration
Shopware.Component.extend('sw-custom-field', 'sw-text-field', {

    // override the logic of the onInput() method
    methods: {
        onInput() {
            // add your custom logic in here
            // ...
        }
    }
});
```

In the previous example, the inherited logic of `onInput()` will be replaced completely.
But sometimes, you will only be able to add additional logic to the method. You can achieve this by using `this.$super()` call.

```JS
// extend the existing component `sw-text-field` by passing
// a new component name and the new configuration
Shopware.Component.extend('sw-custom-field', 'sw-text-field', {

    // extend the logic of the onInput() method
    methods: {
        onInput() {
            // call the original implementation of `onInput()`
            const superCallResult = this.$super('onInput');

            // add your custom logic in here
            // ...
        }
    }
});
```

This technique also works for `computed` properties, for example:

```JS
// extend the existing component `sw-text-field` by passing
// a new component name and the new configuration
Shopware.Component.extend('sw-custom-field', 'sw-text-field', {

    // extend the logic of the computed property `stringRepresentation`
    computed: {
        stringRepresentation() {
            // call the original implementation of `onInput()`
            const superCallResult = this.$super('stringRepresentation');

            // add your custom logic in here
            // ...
        }
    }
});
```

## Real world example for block overriding

### Finding the block to override

In this guide we want to change the heading of the Shopware 6 dashboard to be `Welcome to a customized Administration` instead of `Welcome to Shopware 6`.
To do this, we first need to find an appropriate twig block to override.
We don't want to replace too much but also to not override too little of the Administration.
In this case, we only want to override the headline and not links or anything else on the page.
Looking at the twig markup for the dashboard [here](https://github.com/shopware/shopware/blob/trunk/src/Administration/Resources/app/administration/src/module/sw-dashboard/page/sw-dashboard-index/sw-dashboard-index.html.twig),
suggests that we only need to override the twig block with the name `sw_dashboard_index_content_intro_content_headline` to achieve our goal.

### Preparing the override

Now that we know where to place our override, we need to decide what to override it with.
In this very simple example it suffices to create a twig file, declare a block with the name we previously found and to insert our new header into the block.

```text
<!-- <plugin root>/src/Resources/app/administration/src/sw-dashboard-index-override/sw-dashboard-index.html.twig -->
{% block sw_dashboard_index_content_intro_content_headline %}
    <h1>
        Welcome to a customized component
    </h1>
{% endblock %}
```

This overrides the entire twig block with our new markup.
However, if we want to retain the original content of the twig block and just add our markup to the existing one, we can do that by including a {% parent %} somewhere in the twig block.
Learn more about the capabilities of twig.js [here](https://github.com/twigjs/twig.js/wiki).

As you might have noticed the heading we just replaced had a `{ $tc() }` [string interpolation](https://vuejs.org/v2/guide/syntax.html#Text) which is used to make it multilingual.
Learn more about internationalization in the Shopware 6 Administration and about adding your own snippets to the Administration [here](../templates-styling/adding-snippets.md).

### Applying the override

Registering the override of the Vue component is done by using the override method of our ComponentFactory.
This could be done in any `.js` file, which then has to be later imported, but we'll place it in `<plugin root>/src/Resources/app/administration/src/sw-dashboard-index-override/index.js`.

```javascript
import template from './sw-dashboard-index.html.twig';

Shopware.Component.override('sw-dashboard-index', {
    template
});
```

The first parameter matches the component to override, the second parameter has to be an object containing the actually overridden properties for example, the new twig template extension for this component.

### Loading the JavaScript File

The main entry point to customize the Administration via a plugin is the `main.js` file.
It has to be placed into the `<plugin root>/src/Resources/app/administration/src` directory in order to be automatically found by Shopware 6.

The only thing now left to just add an import for our previously created `./sw-dashboard-index-override/index.js` in the `main.js`:

```javascript
import './sw-dashboard-index-override/';
```

## Experimental: Composition API extension system

Shopware 6 is introducing a new way to extend components using the Composition API. This system is currently in an experimental state and is needed for the future migration of components from the Options API to the Composition API.

### Current status and future plans

* The existing Options API extension system remains fully supported and functional.
* The new Composition API extension system is introduced as an experimental feature.
* In future versions, components will gradually migrate from Options API to Composition API.
* Plugin developers are encouraged to familiarize themselves with the new system, but should continue using the current Component factory extension system for components written with the Options API.
* For components written with the Composition API, the new extension system should be used.
* In the long term, the Composition API extension system will become the standard way to override components. The Options API extension system will be deprecated and eventually removed when all components are migrated to the Composition API.

### How it works

The new extension system introduces two main functions:

1. `Shopware.Component.createExtendableSetup`: Used within components to make them extendable. This will mainly be used by the core team to make components extendable.
2. `Shopware.Component.overrideComponentSetup`: Used by plugins to override components.

### Using overrideComponentSetup

The `overrideComponentSetup` function is a key part of the new Composition API extension system. It allows plugin developers to override or extend the behavior of existing components without directly altering their source code.

### Basic usage

```javascript
Shopware.Component.overrideComponentSetup()('componentName', (previousState, props, context) => {
    // Your extension logic here
    return {
        // Return the new or modified properties and methods
    };
});
```

#### Parameters

1. `componentName`: A string identifying the component you want to override.
2. Callback function: This function receives three arguments:
   1. `previousState`: The current state of the component, including all its reactive properties and methods.
   2. `props`: The props passed to the component.
   3. `context`: The setup context, similar to what you would receive in a standard Vue 3 setup function.

#### Return value

The callback function should return an object containing any new or modified properties or methods you want to add or change in the component.

#### Example: Replacing a Single Property

```javascript
Shopware.Component.overrideComponentSetup()('sw-product-list', (previousState) => {
    const newPageSize = ref(50);

    return {
        pageSize: newPageSize // Override the default page size with the new ref
    };
});
```

#### Example: Adding a New Method

```javascript
Shopware.Component.overrideComponentSetup()('sw-order-list', (previousState) => {
    return {
        newCustomMethod() {
            console.log('This is a new method added to sw-order-list');
        }
    };
});
```

#### Example: Modifying existing data

```javascript
Shopware.Component.overrideComponentSetup()('sw-customer-list', (previousState) => {
    // Add a new column to the list
    previousState.columns.push({ property: 'customField', label: 'Custom Field' });
    
    return {};
});
```

#### Example: Overwriting a method

```javascript
Shopware.Component.overrideComponentSetup()('sw-customer-list', (previousState) => {
    // Overwrite the existing method
    const newIncrement = () => {
        // Able to access the previous method
        previousState.increment();
        // Add custom logic
        console.log('Incremented by 1');
    };

    return {
        increment: newIncrement,
    };
});
```

#### Example: Accessing props and context

```javascript
Shopware.Component.overrideComponentSetup()('sw-customer-list', (previousState, props, context) => {
    // Access the props
    console.log(props);

    // Access the context
    console.log(context);

    return {};
});
```

### Important notes

1. Type Safety: The system aims to provide type safety. Make sure your IDE is set up to recognize the types from Shopware's type definitions.
2. Reactive Properties: When modifying reactive properties, ensure you maintain their reactivity. Use Vue's reactive utilities when necessary.
3. Multiple Overrides: Multiple plugins can override the same component. Overrides are applied in the order they are registered.
4. Performance: Be mindful of performance implications when adding complex logic to frequently used components.
5. Compatibility: This method is part of the experimental Composition API system. Ensure your plugin clearly states its dependency on this feature.
6. Testing: Thoroughly test your overrides, especially when modifying core component behavior.

### Example real world usage

Here is an example of how to create an extendable component and how to override it:

```javascript
import { defineComponent, reactive } from 'vue';

// Original component
const originalComponent = defineComponent({
    template: `
        <div>
            <h1>{{ message }}</h1>
            <div>
                <mt-button @click="increment">Increment</mt-button>

                <p>
                    {{ countMessage }}
                </p>

                <p>
                    Notifications are currently: {{ showNotification ? 'enabled' : 'disabled' }}
                </p>
            </div>
        </div>
    `,
    props: {
        showNotification: {
            type: Boolean,
            default: false,
        },
    },
    setup: (props, context) => Shopware.Component.createExtendableSetup({
        props,
        context,
        name: 'originalComponent',
    }, () => {
        const count = ref(0);
        const message = 'Hello from Shopware!';
        const countMessage = computed(() => `The current count is: ${count.value}`);

        const increment = () => {
            count.value++;
        };

        const privateExample = ref('This is a private property');

        return {
            public: {
                count,
                message,
                countMessage,
                increment,
            },
            private: {
                privateExample,
            }
        };            
    }),
});

// Overriding the component with a plugin
Shopware.Component.overrideComponentSetup()('originalComponent', (previousState, props) => { 
    const newMessage = 'Hello from the plugin!';
    const newCountMessage = computed(() => `The new, amazing count is: ${previousState.count.value}`);
    const newIncrement = () => {
        previousState.increment();
        
        if (props.showNotification) {
            Shopware.ServiceContainer.get('notification').dispatch({
                title: 'Incremented!',
                message: `The count has been incremented by the user to ${previousState.count.value}!`,
                variant: 'success',
            });
        }
    };

    return {
        message: newMessage,
        countMessage: newCountMessage,
        increment: newIncrement,
    };
});
```

In this example, `createExtendableSetup` is used to make the `originalComponent` extendable. The `overrideComponentSetup` function is then used to modify the properties of the component. In this case, the message is changed, a new computed property is added, and the increment method is modified to show a notification if the `showNotification` prop is set to `true`.

### Key differences from Options API extension system

* Uses Composition API syntax and reactive primitives of Vue 3 instead of Vue 2 options API.
* Extensions are applied using function composition rather than option merging.
* Provides more granular control over what parts of a component can be overridden.
* Only overrides are possible. Extending a component is not supported anymore. This can be done natively with the Composition API.

### Using TypeScript

To take full advantage of the Composition API extension system, it is recommended to use TypeScript. This will provide better type safety and autocompletion in your IDE and prevent common errors.

For adding type safety to props you need to import the type of the component you want to override and use it in the `overrideComponentSetup` function as a generic type: `<typeof _InternalTestComponent>`. The types for the `previousState` are automatically inferred from the component you are overriding by using the correct component name.

```typescript
import _InternalTestComponent from 'src/the/path/to/the/exported/component';

Shopware.Component.overrideComponentSetup<typeof _InternalTestComponent>()('_internal_test_compponent', (previousState, props) => {
    const newBaseValue = ref(5);
    const newMultipliedValue = computed(() => {
        // Props are now correctly typed
        return newBaseValue.value * props.multiplier!;
    });

    // Previous state is now correctly typed
    previousState.baseValue.value = 2;

    return {
        baseValue: newBaseValue,
        multipliedValue: newMultipliedValue,
    };
});
```

### Accessing private properties

In some cases, you may need to access private properties of a component. This is not recommended, as it can lead to unexpected behavior and breakages when the component is updated. However, if you need to access private properties for debugging or testing purposes, you can do so using the `_private` property of the `previousState` object where all private properties are stored.

Note: overriding and accessing private properties has no TS support and is not recommended for production use.

```javascript
Shopware.Component.overrideComponentSetup()('sw-customer-list', (previousState, props, context) => {
    // Access the private properties
    console.log(previousState._private.thePrivateProperty);
});
```

## More interesting topics

* [Customizing templates](../templates-styling/writing-templates.md)
* [Customizing via custom styles](../templates-styling/add-custom-styles.md)
* [Using base components](../module-component-management/using-base-components.md)

---

---
url: >-
  /docs/guides/plugins/plugins/administration/module-component-management/customizing-components.md
---

# Customizing Components

## Overview

The Shopware 6 Administration allows you to override and extend components to change its content and its behavior.

## Prerequisites

All you need for this guide is a running Shopware 6 instance, the files and preferably a registered module.
Of course, you will have to understand JavaScript, Vue and have a basic familiarity with TwigJS block system, and the templating engine used in the Administration. It is just used for the block extending and overriding. Every other feature of TwigJS is not used in the Administration.
However, that is a prerequisite for Shopware as a whole and will not be taught as part of this documentation.

## General

To add new functionality or change the behavior of an existing component, you can either override or extend the component.

The difference between the two methods is that with `Component.extend()` a new component is created. With `Component.override()`, on the other hand, the previous behavior of the component is simply overwritten.

## Override a component

The following example shows how you can override the template of the `sw-text-field` component.

```JS
// import the new twig-template file
import template from './sw-text-field-new.html.twig';

// override the existing component `sw-text-field` by passing the new configuration
Shopware.Component.override('sw-text-field', {
    template
});
```

## Extending a component

To create your custom text-field `sw-custom-field` based on the existing `sw-text-field` you can implement it like the following:

```JS
// import the custom twig-template file
import template from './sw-custom-field.html.twig';

// extend the existing component `sw-text-field` by passing
// a new component name and the new configuration
Shopware.Component.extend('sw-custom-field', 'sw-text-field', {
    template
});
```

Now you can render your new component `sw-custom-field` in any template like this:

```twig
    <sw-custom-field></sw-custom-field>
```

## Customize a component template

To extend a given template you can use the Twig `block` feature.

Imagine, the component you want to extend/override has the following template:

```twig
{% block card %}
    <div class="sw-card">
        {% block card_header %}
            <div class="sw-card--header">
                {{ header }}
            </div>
        {% endblock %}

        {% block card_content %}
            <div class="sw-card--content">
                {{ content }}
            </div>
        {% endblock %}
    </div>
{% endblock %}
```

Maybe you want to replace the markup of the header section and add an extra block to the content.
With the Twig `block` feature you can implement a solution like this:

```twig
{# override/replace an existing block #}
{% block card_header %}
    <h1 class="custom-header">
        {{ header }}
    </h1>
{% endblock %}

{% block card_content %}

    {# render the original block #}
    {% parent %}

    <div class="card-custom-content">
        ...
    </div>
{% endblock %}
```

Summarized with the `block` feature you will be able to replace blocks inside a template.
Additionally, you can render the original markup of a block by using `{% parent %}`

## Extending methods and computed properties

Sometimes you need to change the logic of a method or a computed property while you are extending/overriding a component.
In the following example we extend the `sw-text-field` component and change the `onInput()` method, which gets called after the value of the input field changes.

```JS
// extend the existing component `sw-text-field` by passing
// a new component name and the new configuration
Shopware.Component.extend('sw-custom-field', 'sw-text-field', {

    // override the logic of the onInput() method
    methods: {
        onInput() {
            // add your custom logic in here
            // ...
        }
    }
});
```

In the previous example, the inherited logic of `onInput()` will be replaced completely.
But sometimes, you will only be able to add additional logic to the method. You can achieve this by using `this.$super()` call.

```JS
// extend the existing component `sw-text-field` by passing
// a new component name and the new configuration
Shopware.Component.extend('sw-custom-field', 'sw-text-field', {

    // extend the logic of the onInput() method
    methods: {
        onInput() {
            // call the original implementation of `onInput()`
            const superCallResult = this.$super('onInput');

            // add your custom logic in here
            // ...
        }
    }
});
```

This technique also works for `computed` properties, for example:

```JS
// extend the existing component `sw-text-field` by passing
// a new component name and the new configuration
Shopware.Component.extend('sw-custom-field', 'sw-text-field', {

    // extend the logic of the computed property `stringRepresentation`
    computed: {
        stringRepresentation() {
            // call the original implementation of `onInput()`
            const superCallResult = this.$super('stringRepresentation');

            // add your custom logic in here
            // ...
        }
    }
});
```

## Real world example for block overriding

### Finding the block to override

In this guide we want to change the heading of the Shopware 6 dashboard to be `Welcome to a customized Administration` instead of `Welcome to Shopware 6`.
To do this, we first need to find an appropriate twig block to override.
We don't want to replace too much but also to not override too little of the Administration.
In this case, we only want to override the headline and not links or anything else on the page.
Looking at the twig markup for the dashboard [here](https://github.com/shopware/shopware/blob/trunk/src/Administration/Resources/app/administration/src/module/sw-dashboard/page/sw-dashboard-index/sw-dashboard-index.html.twig),
suggests that we only need to override the twig block with the name `sw_dashboard_index_content_intro_content_headline` to achieve our goal.

### Preparing the override

Now that we know where to place our override, we need to decide what to override it with.
In this very simple example it suffices to create a twig file, declare a block with the name we previously found and to insert our new header into the block.

```text
<!-- <plugin root>/src/Resources/app/administration/src/sw-dashboard-index-override/sw-dashboard-index.html.twig -->
{% block sw_dashboard_index_content_intro_content_headline %}
    <h1>
        Welcome to a customized component
    </h1>
{% endblock %}
```

This overrides the entire twig block with our new markup.
However, if we want to retain the original content of the twig block and just add our markup to the existing one, we can do that by including a {% parent %} somewhere in the twig block.
Learn more about the capabilities of twig.js [here](https://github.com/twigjs/twig.js/wiki).

As you might have noticed the heading we just replaced had a `{ $tc() }` [string interpolation](https://vuejs.org/v2/guide/syntax.html#Text) which is used to make it multilingual.
Learn more about internationalization in the Shopware 6 Administration and about adding your own snippets to the Administration [here](../templates-styling/adding-snippets.md).

### Applying the override

Registering the override of the Vue component is done by using the override method of our ComponentFactory.
This could be done in any `.js` file, which then has to be later imported, but we'll place it in `<plugin root>/src/Resources/app/administration/src/sw-dashboard-index-override/index.js`.

```javascript
import template from './sw-dashboard-index.html.twig';

Shopware.Component.override('sw-dashboard-index', {
    template
});
```

The first parameter matches the component to override, the second parameter has to be an object containing the actually overridden properties for example, the new twig template extension for this component.

### Loading the JavaScript File

The main entry point to customize the Administration via a plugin is the `main.js` file.
It has to be placed into the `<plugin root>/src/Resources/app/administration/src` directory in order to be automatically found by Shopware 6.

The only thing now left to just add an import for our previously created `./sw-dashboard-index-override/index.js` in the `main.js`:

```javascript
import './sw-dashboard-index-override/';
```

## Experimental: Composition API extension system

:::warning
The Composition API extension system is **experimental**. Its API can still change, and there is no committed timeline or release version for when it will become the standard.
:::

Shopware 6 is introducing a new way to extend components using the Composition API. This system is currently in an experimental state and is needed for the future migration of components from the Options API to the Composition API.

### Current status and future plans

* The existing Options API extension system remains fully supported and functional.
* The new Composition API extension system is introduced as an experimental feature.
* In future versions, components will gradually migrate from Options API to Composition API.
* Plugin developers are encouraged to familiarize themselves with the new system, but should continue using the current Component factory extension system for components written with the Options API.
* For components written with the Composition API, the new extension system should be used.
* In the long term, the Composition API extension system will become the standard way to override components. The Options API extension system will be deprecated and eventually removed when all components are migrated to the Composition API.

### How it works

The new extension system introduces two main functions:

1. `Shopware.Component.createExtendableSetup`: Used within components to make them extendable. This will mainly be used by the core team to make components extendable.
2. `Shopware.Component.overrideComponentSetup`: Used by plugins to override components.

### Using overrideComponentSetup

The `overrideComponentSetup` function is a key part of the new Composition API extension system. It allows plugin developers to override or extend the behavior of existing components without directly altering their source code.

### Basic usage

```javascript
Shopware.Component.overrideComponentSetup()('componentName', (previousState, props, context) => {
    // Your extension logic here
    return {
        // Return the new or modified properties and methods
    };
});
```

#### Parameters

1. `componentName`: A string identifying the component you want to override.
2. Callback function: This function receives three arguments:
   1. `previousState`: The current state of the component, including all its reactive properties and methods.
   2. `props`: The props passed to the component.
   3. `context`: The setup context, similar to what you would receive in a standard Vue 3 setup function.

#### Return value

The callback function should return an object containing any new or modified properties or methods you want to add or change in the component.

#### Example: Replacing a Single Property

```javascript
Shopware.Component.overrideComponentSetup()('sw-product-list', (previousState) => {
    const newPageSize = ref(50);

    return {
        pageSize: newPageSize // Override the default page size with the new ref
    };
});
```

#### Example: Adding a New Method

```javascript
Shopware.Component.overrideComponentSetup()('sw-order-list', (previousState) => {
    return {
        newCustomMethod() {
            console.log('This is a new method added to sw-order-list');
        }
    };
});
```

#### Example: Modifying existing data

```javascript
Shopware.Component.overrideComponentSetup()('sw-customer-list', (previousState) => {
    // Add a new column to the list
    previousState.columns.push({ property: 'customField', label: 'Custom Field' });
    
    return {};
});
```

#### Example: Overwriting a method

```javascript
Shopware.Component.overrideComponentSetup()('sw-customer-list', (previousState) => {
    // Overwrite the existing method
    const newIncrement = () => {
        // Able to access the previous method
        previousState.increment();
        // Add custom logic
        console.log('Incremented by 1');
    };

    return {
        increment: newIncrement,
    };
});
```

#### Example: Accessing props and context

```javascript
Shopware.Component.overrideComponentSetup()('sw-customer-list', (previousState, props, context) => {
    // Access the props
    console.log(props);

    // Access the context
    console.log(context);

    return {};
});
```

### Important notes

1. Type Safety: The system aims to provide type safety. Make sure your IDE is set up to recognize the types from Shopware's type definitions.
2. Reactive Properties: When modifying reactive properties, ensure you maintain their reactivity. Use Vue's reactive utilities when necessary.
3. Multiple Overrides: Multiple plugins can override the same component. Overrides are applied in the order they are registered.
4. Performance: Be mindful of performance implications when adding complex logic to frequently used components.
5. Compatibility: This method is part of the experimental Composition API system. Ensure your plugin clearly states its dependency on this feature.
6. Testing: Thoroughly test your overrides, especially when modifying core component behavior.

### Example real world usage

Here is an example of how to create an extendable component and how to override it:

```javascript
import { defineComponent, reactive } from 'vue';

// Original component
const originalComponent = defineComponent({
    template: `
        <div>
            <h1>{{ message }}</h1>
            <div>
                <mt-button @click="increment">Increment</mt-button>

                <p>
                    {{ countMessage }}
                </p>

                <p>
                    Notifications are currently: {{ showNotification ? 'enabled' : 'disabled' }}
                </p>
            </div>
        </div>
    `,
    props: {
        showNotification: {
            type: Boolean,
            default: false,
        },
    },
    setup: (props, context) => Shopware.Component.createExtendableSetup({
        props,
        context,
        name: 'originalComponent',
    }, () => {
        const count = ref(0);
        const message = 'Hello from Shopware!';
        const countMessage = computed(() => `The current count is: ${count.value}`);

        const increment = () => {
            count.value++;
        };

        const privateExample = ref('This is a private property');

        return {
            public: {
                count,
                message,
                countMessage,
                increment,
            },
            private: {
                privateExample,
            }
        };            
    }),
});

// Overriding the component with a plugin
Shopware.Component.overrideComponentSetup()('originalComponent', (previousState, props) => { 
    const newMessage = 'Hello from the plugin!';
    const newCountMessage = computed(() => `The new, amazing count is: ${previousState.count.value}`);
    const newIncrement = () => {
        previousState.increment();
        
        if (props.showNotification) {
            Shopware.ServiceContainer.get('notification').dispatch({
                title: 'Incremented!',
                message: `The count has been incremented by the user to ${previousState.count.value}!`,
                variant: 'success',
            });
        }
    };

    return {
        message: newMessage,
        countMessage: newCountMessage,
        increment: newIncrement,
    };
});
```

In this example, `createExtendableSetup` is used to make the `originalComponent` extendable. The `overrideComponentSetup` function is then used to modify the properties of the component. In this case, the message is changed, a new computed property is added, and the increment method is modified to show a notification if the `showNotification` prop is set to `true`.

### Key differences from Options API extension system

* Uses Composition API syntax and reactive primitives of Vue 3 instead of Vue 2 options API.
* Extensions are applied using function composition rather than option merging.
* Provides more granular control over what parts of a component can be overridden.
* Only overrides are possible. Extending a component is not supported anymore. This can be done natively with the Composition API.

### Using TypeScript

To take full advantage of the Composition API extension system, it is recommended to use TypeScript. This will provide better type safety and autocompletion in your IDE and prevent common errors.

For adding type safety to props you need to import the type of the component you want to override and use it in the `overrideComponentSetup` function as a generic type: `<typeof _InternalTestComponent>`. The types for the `previousState` are automatically inferred from the component you are overriding by using the correct component name.

```typescript
import _InternalTestComponent from 'src/the/path/to/the/exported/component';

Shopware.Component.overrideComponentSetup<typeof _InternalTestComponent>()('_internal_test_compponent', (previousState, props) => {
    const newBaseValue = ref(5);
    const newMultipliedValue = computed(() => {
        // Props are now correctly typed
        return newBaseValue.value * props.multiplier!;
    });

    // Previous state is now correctly typed
    previousState.baseValue.value = 2;

    return {
        baseValue: newBaseValue,
        multipliedValue: newMultipliedValue,
    };
});
```

### Accessing private properties

In some cases, you may need to access private properties of a component. This is not recommended, as it can lead to unexpected behavior and breakages when the component is updated. However, if you need to access private properties for debugging or testing purposes, you can do so using the `_private` property of the `previousState` object where all private properties are stored.

Note: overriding and accessing private properties has no TS support and is not recommended for production use.

```javascript
Shopware.Component.overrideComponentSetup()('sw-customer-list', (previousState, props, context) => {
    // Access the private properties
    console.log(previousState._private.thePrivateProperty);
});
```

## More interesting topics

* [Customizing templates](../templates-styling/writing-templates.md)
* [Customizing via custom styles](../templates-styling/add-custom-styles.md)
* [Using base components](../module-component-management/using-base-components.md)

---

---
url: /docs/guides/development/testing/legacy/cypress.md
---

# Cypress

In end-to-end testing (E2E testing in short), real user workflows are simulated, whereby as many as possible functional areas and parts of the technology stack used in the application should be included. This way, we are able to put our UI under constant stress and ensure that Shopware's main functionalities are always working correctly.

## Prerequisites

To run Shopware E2E tests, you first need a Shopware 6 installation running. To ensure your tests are reliable, you should have a clean installation. Cleanup means no categories, no products, no settings, nothing!

The easiest way to clean up your installation is the initialization. Using the command `composer run init`, Shopware 6 gets initialized clean and without demo data. Installation of E2E dependencies can be done separately by running `npm install` in the E2E folder you're using, e.g., for Shopware Administration, it's `src/Administration/Resources/app/administration/test/e2e`.

Since our tests should run on an installation that is as close as possible to a release package, we use production mode. If you run the tests on a development environment, the test results may vary.

Additionally, please make sure your shop has a theme assigned. When using `composer run e2e:open` or `run`, this is done automatically.

This guide also won't teach you how to write Cypress tests in general. Please refer to the official Cypress documentation for further guidance.

### Using our testsuite

The [E2E platform testsuite package](https://github.com/shopwareArchive/e2e-testsuite-platform) contains commands and helpers supporting you while building E2E tests for Shopware 6. On top of that, test data management and custom commands are included. More on that here: [Command reference](../../../../../resources/references/core-reference/commands-reference.md).

This test suite is built on top of [Cypress](https://www.cypress.io/) as well as the following Cypress plugins:

* [cypress-select-tests](https://github.com/bahmutov/cypress-select-tests)
* [cypress-log-to-output](https://github.com/flotwig/cypress-log-to-output)
* [cypress-file-upload](https://github.com/abramenal/cypress-file-upload)

Here you can find the npm package of our testsuite:

Please have a look at our [cypress.json](https://github.com/shopwareArchive/e2e-testsuite-platform/blob/3.x/cypress.json). A few of our commands expect configuration, e.g., viewportHeight and width, because the admin menu only opens if the viewport is wide enough.

## Setup steps

When you use our [Development template](https://github.com/shopwareArchive/development), we provide you with some tooling scripts in `dev-ops/e2e/actions` to run E2E tests more comfortably.

The `composer` scripts to run our E2E tests in CLI or in Cypress' test runner are explained in the "Executing E2E Tests" section below.

Depending on your environment (administration or storefront), please create the following folder structure:

```text
Resources
 `-- app
 `-- <environment>
 `-- test
 `-- e2e
 `-- cypress
 |-- fixtures
 |-- integration
 |-- plugins
 `-- support
```

We will cover the use of every folder in detail.

Within the folder `Resources/app/<environment>/test/e2e`, please run `npm init -y` to generate a `package.json` file. It is very convenient to place a script inside the newly created `package.json` to run the tests locally. Please add the following section to do so:

```javascript
"scripts": {
   "open": "node_modules/.bin/cypress open"
},
```

Now install this package with the following command:

```text
npm install @shopware-ag/e2e-testsuite-platform
```

As the next step, please create a new file `e2e/cypress/plugins/index.js` with the following content:

```javascript
module.exports = require('@shopware-ag/e2e-testsuite-platform/cypress/plugins');
```

Finally, create a new file e2e/cypress/support/index.js with the following line:

```javascript
// Require test suite commands
require('@shopware-ag/e2e-testsuite-platform/cypress/support');
```

However, since we're using this image to run the test runner as well, you may need to configure it first. Based on this [guide](https://www.cypress.io/blog/run-cypress-with-a-single-docker-command), you need to forward the XVFB messages from Cypress out of the Docker container into an X11 server running on the host machine. The guide shows an example for Mac; other operating systems might require different commands.

In case you're using Docker on Mac, we have summarized the steps from the guide mentioned above, so you can follow these to prepare your environment to get the Test Runner up and running:

**Install and configure XQuartz**

Install XQuartz via [Homebrew](https://docs.brew.sh/Installation) or alternatively [download](https://www.xquartz.org/) it from the official homepage:

```bash
brew install --cask xquartz
```

Run XQuartz via CLI or open it from your Desktop:

```bash
open -a XQuartz
```

Got to `XQuartz > Preferences` (`⌘ + ,`) and enable `Allow connections from network clients`:

![XQuartz Preferences](../../../../../assets/xquartz-allow-connections-from-network-clients.png)

::: warning
Restart your Mac before proceeding with the following steps.
:::

**Configure your environment**

Grab your IP address and save it to the environment variable `IP`:

```bash
IP=$(ipconfig getifaddr en0)
```

Depending on how you're connected, you might have to use another interface instead of `en0`.

Now set the `DISPLAY` environment variable:

```bash
DISPLAY=$IP:0
```

Add `$IP` to xhost's ACL:

```bash
xhost + $IP
```

::: danger
It is **crucial** to set these environment variables in the **same terminal session** from where you will later run `psh e2e:open`!

Make sure the `DISPLAY` environment variable on your Mac is correctly set **before** you start the containers, as it will be **passed** to the Cypress container when it is **created**.
Updating the variable on your host won't update it in the container until it is re-created!
:::



## Executing E2E tests

If you want to run E2E tests in your plugin, just switch to the folder `Resources/app/<environment>/test/e2e` and execute the following command:

```bash
CYPRESS_baseUrl=<your-url> npm run open
```

`<your-url>` means the Storefront URL of your Shopware environment.

It opens the Cypress test runner, which lets you run and debug your tests, similar to the `e2e:open` command.

::: danger
Don't forget that you might need to adjust test cleanup and other environment-related settings based on your plugin's setup.
:::

To prepare your shopware installation, your environment, and install dependencies, please run the following command as the first step, **outside** of your docker container:

```bash
 composer run e2e:setup
```

In our tests, we assume a clean shopware installation, so we strongly recommend using `e2e:setup`. However, if your shopware installation is already clean and prepared, you can skip the preparation of your shopware installation by using the following command **inside** your docker container:

```bash
 composer run e2e:prepare
```

Afterwards, just use the following command outside of your container to run the Cypress Test Runner:

```bash
composer run e2e:open
```

If you want to run the tests in CLI, please use the following command outside your container:

```bash
composer e2e:cypress -- run --spec="cypress/e2e/administration/**/*.cy.js"
```

or

```bash
composer e2e:cypress -- run --spec="cypress/e2e/storefront/**/*.cy.js"
```

To see a complete overview of all PSH scripts for e2e tests, feel free to refer to our [e2e command reference](../../../../../resources/references/testing-reference/e2e-commands.md).



## Writing your first test

### Folder structure

In the Shopware platform, you can find the tests in `src/Administration/Resources/app/administration/test/e2e`. There you can find the following folder structure, depending on your environment being Administration or Storefront:

```bash
`-- e2e
 `-- cypress
 |-- fixtures
        `-- example.json
    |-- integration
 `-- testfile.spec.js
 |-- plugins
        `-- index.js
    |-- support
        |-- commands.js
 `-- index.js
 |--cypress.json
    `--cypress.env.json
```

In the `cypress` folder, all test-related folders are located. Most things will take place in these four folders:

* `fixtures`: Fixtures are used as external pieces of static data that your tests can use. You can use them with the `cy.fixture` command.

* `integration`: By default, the test files are located here. A file with the suffix "\*.spec.js" is a test file that contains a sequence of tests, performed in the order defined in it.

* `plugins`: Contains extensions or plugins. By default, Cypress automatically includes the plugins file before every spec file it runs.

* `support`: The support folder is a great place to put reusable behavior, such as custom commands or global overrides, that you want to be applied and available to all of your spec files.

These two configuration files are essential to mention as well:

* `cypress.json`
* `cypress.env.json`

These are Cypress configuration files. If you need more information about them, take a look at the

[Cypress configuration docs](https://docs.cypress.io/app/references/configuration).

If you need to use this structure in a plugin, it is just the path to the `e2e` folder, which is slightly different. You can find the folder structure in the "Setup Steps" section below.

If you want to contribute to the Shopware platform's tests, please ensure to place your test in one of those folders:

```javascript
`-- integration
 |-- catalogue
 |-- content
 |-- customer
 |-- general
 |-- media-marketing
 |-- order
 |-- rule-product-stream
 `-- settings
```

::: warning
This is important because otherwise your test is not considered by our CI.
:::

### Test layout and syntax

Cypress tests are written in Javascript. If you worked with Mocha before, you will be familiar with Cypress' test layout. The test interface borrowed from Mocha provides `describe()`, `context()`, `it()` and `specify()`.

To have a frame surrounding your test and provide a nice way to keep your test organized, use `describe()` (or `context()` as its alias):

```javascript
describe('Test: This is my test file', () => {
    it('test something', () => {
        // This is your first test
 });
    it('tests something else', () => {
        // This is your second test
 });
});
```

The `it()` functions within the `describe()` function are your actual tests. Similar to `describe()` and `context()`, `it()` is identical to `specify()`. However, for writing Shopware tests, we focus on `it()` to keep it consistent.

## Commands and assertions

In Cypress, you use commands and assertions to describe the workflow you want to test.

### Commands

Commands are the actions you need to perform to interact with the elements of your application and reproduce the workflow you intend to test in the end.

```javascript
it('test something', () => {
 ...
    cy.get('.sw-grid__row--0')
 .contains('A Set Name Snippet')
 .dblclick();
    cy.get('.sw-grid__row--0 input')
 .clear()
 .type('Nordfriesisch')
 .click();
 ...
 });
```

You can chain commands by passing their return value to the next one. These commands may include additional steps, e.g., a `click` or `type` operation.

Cypress provides many commands to represent a variety of steps a user could take. On top of that, our E2E testsuite contains a couple of [custom commands](../../../../../resources/references/testing-reference/e2e-custom-commands.md) specially for Shopware.

### Assertions

Assertions describe the desired state of your elements, objects, and application. Cypress bundles the Chai Assertion Library (including extensions for Sinon and jQuery) and supports both BDD (expect/should) and TDD (assert) style assertions. For consistency reasons, we prefer BDD syntax in Shopware's tests.

```javascript
it('test something', () => {
 ...
    cy.get('.sw-loader')
 .should('not.exist')
 .should('be.visible')
 .should('not.have.css', 'display', 'none');
    cy.get('div')
 .should(($div) => {
            expect($div).to.have.length(1)
 });
 ...
 });
```

## Hooks

You might want to set hooks to run before a set of tests or before each test. At Shopware, we use those, e.g., to clean up Shopware itself, log in to the Administration, or to set the admin language.

Cypress got you covered, similar to Mocha, by providing hooks. These can be used to set conditions that run before or after a set of tests, or before or after each test.

```javascript
describe('We are using hooks', function() {
  before(function() {
    // runs once before all tests in the block
 })

  beforeEach(function() {
    // runs before each test in the block
 })

  afterEach(function() {
    // runs after each test in the block
 })

  after(function() {
    // runs once after all tests in the block
 })
})
```

### Build up and teardown

As we mentioned before, we use these hooks to build up the ideal situation for our test to run. This includes cleaning up the tests' state - based on a clean Shopware installation. According to Cypress's [thoughts on anti-patterns](https://docs.cypress.io/guides/references/best-practices.html#Using-after-or-afterEach-hooks), we clean up the previous state of Shopware beforehand. The reason is pretty simple: You can't be completely sure to reach the `after` hook (sometimes tests may fail), the safer way to clean up your tests is the `beforeEach` hook. In addition to stability advantages, it's possible to stop tests at any time without manual cleanup.

## Handling test data

It's important and necessary that the E2E tests are isolated. This means the test should be created beforehand, with all the data needed to run it. Afterwards, the state in the database and the browser must be removed completely. This way, the spec avoids dependencies on demo data or data from other tests, and it cannot be disturbed by them.

One test should only test one workflow, the one it's written for. For example, if you want to test product creation, you should not include category creation in your test, even though it is needed to test the product properly. As best practice, we recommend handling everything not related to the test using the [lifecycle hooks](https://docs.cypress.io/guides/core-concepts/writing-and-organizing-tests.html#Hooks) provided by Cypress.

In the Shopware platform, we use Shopware's REST API to create the data we need. As a result, our tests can focus on a single workflow without testing the workflows that are typically required to provide the data we need. Another aspect of handling it this way is that creating test data via API is faster than doing it inside the test.

### Cypress' fixtures

To define the request you send to Shopware and to set the first test data, store it as a `json` file in the folder `e2e/cypress/fixtures`. You can use those files to provide fixed test data that can be used directly to create the desired entity without any further searching or processing. Fortunately, Cypress provides a way to handle those fixtures by default. The command `cy.fixture()` loads this fixed set of data located in a JSON file.

The example file below defines and creates a customer. So, it provides the data needed to create a customer in Shopware.

```json
{
  "customerNumber": "C-1232123",
  "salutation": "Mr",
  "firstName": "Pep",
  "lastName": "Eroni",
  "email": "test@example.com",
  "guest": true,
  "addresses": [
 {
        ...
 }
 ]
}
```

::: warning
Use only fields that you can access in the UI / Storefront. Keep in mind that all tests in the file may use the fixture. So keep an eye on compatibility.
:::

A small note on ID usage: Using IDs may be easier for finding elements, but it isn't a proper way for testing in every case - it depends on your application. You need to be 100% sure that the ID is persistent and won't change between builds. Never use IDs here if you cannot be 100% sure they will not change, e.g., in another build.

::: info
In our Shopware case, IDs on a UUID basis tend to change from one installation to the next, so they are not always suitable to use as selectors in your test.
:::

### API implementation

Analogous to the Administration itself, the API access for the e2e test uses [axios](https://www.npmjs.com/package/axios), a promise-based HTTP client for the browser and Node.js.

Just as the Administration does, we use services to access Shopware's REST API. Therefore, we use the ApiService to provide the basic methods for accessing the api. Located in `e2e/cypress/support/service/api.service.js`, ApiService is shared between all repositories and acts as a basis for all your next steps of creating fixtures. That implies that the axios implementation of all important api methods can be found there. This service acts as an interface: Next to the basic functions like get, post, etc, the request method is specified here as well as some Shopware-related methods which have to be available in all repositories.

::: info
Cypress provides its own axios-based way to handle requests in its command `cy.request`. However, Cypress commands are not real promises; see [Commands are not Promises](https://docs.cypress.io/guides/core-concepts/introduction-to-cypress.html#Commands-Are-Not-Promises). As we aim to parallelize the promises to fetch test data, we use our own implementation instead.
:::

### Services and commands

To apply all test fixture data to our Shopware installation, we use services to send API requests to find, create, or update the data we need. To access these services conveniently, we provide custom commands, which we'll cover a bit later. Let's continue with the general things first.

All fixture services can be found in `cypress/support/service/`:

```bash
service
 |-- administration // this folder stores the Administration channel API services
    `-- <environment>
 `-- test
        `-- e2e
 `-- cypress
 |-- fixture
 |-- admin-api.service.js // Provides all methods which communicate with the admin api directly
            `-- fixture.service.js // Provides all methods for general fixture handling
  |-- saleschannel // this one stores the sales channel API services
 `-- api.service.js // axios interface
```

If you want to use all known services, you can access them using custom commands. These commands can be found in `cypress/support/commands/api-commands.js` for general operation and `cypress/support/commands/fixture-commands.js` specifically for fixture handling.

#### Default fixture command

The stationary fixtures mentioned in the paragraph "Cypress' fixtures" can be sent to Shopware's REST API directly: In most cases, Shopware does not need any additional data, like IDs or other data already stored in Shopware. That means the request can be sent, and the desired entity can be created immediately: You just need to use the `createDefaultFixture(endpoint, options = [])` command, as seen below:

```javascript
    beforeEach(() => {
        cy.createDefaultFixture('tax');
 });
```

In this example, a tax rate will be created with the data provided based on the `json` file located in the `fixtures` folder. Let's look at the command in detail:

```javascript
Cypress.Commands.add('createDefaultFixture', (endpoint, data = {}, jsonPath) => {
    const fixture = new Fixture();
    let finalRawData = {};

    if (!jsonPath) {
        jsonPath = endpoint;
 }

    // Get test data from cy.fixture first
    return cy.fixture(jsonPath).then((json) => {

        // Merge fixed test data with possible custom one
        finalRawData = Cypress._.merge(json, data);

        // Create the fixture using the method from the fixture service
        return fixture.create(endpoint, finalRawData);
 });
});
```

#### Commands of customised services

You will soon notice that some entities need data that has already been created. That means you have to find the specific IDs or use a completely different approach. In this case, your own service has to be created, located in `e2e/cypress/support/service`. Some examples of these services are:

* Customer
* Sales channel
* Languages
* Products

In most cases, the use of these services is similar to that of the basic ones already implemented. There are commands for each of those services provided by our E2E testsuite package. You don't need to define the API endpoint when using those commands. As these services extend `FixturesService`, all its methods can be used in all other services as well.

#### Writing your own customised service

Let's look at the custom service `shipping.fixture.js`. This service is a relatively simple example - It depicts a service in need of some customization for creating a shipping method correctly. With that being said, let's start.

Your `ShippingFixtureService` has to extend the class `AdminFixtureService`. Afterwards, you create a function called `setShippingFixture(userData)` with the parameter `userData` for the data you want to use to create your shipping method. This way, your class should look like this:

```javascript
const AdminFixtureService = require('../fixture.service.js');

class ShippingFixtureService extends AdminFixtureService {
    setShippingFixture(userData) {
        // Here we're going to create our shipping fixture
 }
}

module.exports = ShippingFixtureService;

global.ShippingFixtureService = new ShippingFixtureService();
```

All custom services hold a distinct method for creating fixtures. First, it's important to collect the necessary data via the REST API. This is done by filtering POST requests used in promises. In your `ShippingFixtureService`, you need the ID of the rule you want to use for availability, as well as the ID of the delivery time.

```javascript
 const findRuleId = () => this.search('rule', {
        type: 'equals',
        value: 'Cart >= 0 (Payment)'
 });
 const findDeliveryTimeId = () => this.search('delivery-time', {
    type: 'equals',
    value: '3-4 weeks'
});
```

The responses of these calls are used to provide the missing IDs for your final POST request. At first, we will merge the missing data with the existing data, then create our shipping method:

```javascript
return Promise.all([
    findRuleId(),
    findDeliveryTimeId()
]).then(([rule, deliveryTime]) => {
    return this.mergeFixtureWithData(userData, {
        availabilityRuleId: rule.id,
        deliveryTimeId: deliveryTime.id
 });
}).then((finalShippingData) => {
    return this.apiClient.post('/shipping-method?_response=true', finalShippingData);
});
```

That's it! There you go: You have successfully created a customised service that sets up a shipping method in Shopware. Actually, we use this service in our platform test to create our shipping method as well. You can find the full service [here](https://github.com/shopwareArchive/e2e-testsuite-platform/blob/master/cypress/support/service/administration/fixture/shipping.fixture.js). Look at this example to see the full class.

Below you will find some best practices and tricks we explored to help you with your testing tasks:

* A source of information can be found in the FieldCollection of several EntityDefinition files. All fields belonging to an entity are defined there. For example, if you're searching for customer-related data, please search for the `CustomerDefinition` in the Shopware platform.
* If you want to extract mandatory data that is not covered by the error message received with the API's response, it's useful to reproduce your workflow manually: E.g., if you need to find out what data is mandatory for creating a customer, try to save an empty one in the Administration. Keep an eye on your browser's developer tools while doing so, especially in the preview and response sections of your request. As you get your response, you can see what data is still missing.
* If you need to set non-mandatory data, reproducing the above mentioned workflow is recommended as well: Even if the error response does not contain a readable error, you can still inspect it: All the relevant information is stored in 'data'. IDs can be found there directly; other relevant data is stored in the "attributes" section.
* Cypress's test runner can help you a lot with inspecting API requests. Just click on the request in the test runner's log to get a full print of it in your console.

## More interesting topics

* [Unit testing with PHPUnit](../../unit/php-unit.md)
* [Jest unit tests in Shopware's administration](../../unit/jest-admin.md)
* [Jest unit tests in Shopware's storefront](../../unit/jest-storefront.md)

---

---
url: /docs/resources/references/adr/2020-11-19-dal-join-filter.md
---

# DAL join filter

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2020-11-19-dal-join-filter.md)
:::

## Context

Currently, there are various difficulties with the current implementation of the `anti-join-filter`.
Sometimes this does not lead to the correct results or the query cannot be executed due to a PHP exception.
Furthermore the counterpart to the `anti-join-filter`, the `join-filter`, is missing.
Currently the `anti-join-filter` is automatically assembled in the entity searcher if a `not-filter` exists that points to a field of an association.

### Anti join filter concept

The `anti-join-filter` should make sure that a `to-many` association can be queried negated on multiple values, here is an example:

**Give me all products which do not have "red" or "yellow" as property, but also not "XL" or "L".**
On the SQL side, the following query must be generated for this purpose:

```sql
SELECT product.id

FROM product
    LEFT JOIN property_properties color_filter
        ON color_filter.product_id = product.id
        AND color_filter.id IN ("red", "yellow")

    LEFT JOIN property_properties size_filter
        ON size_filter.product_id = product.id
        AND size_filter.id IN ("XL", "L")

WHERE size_filter.product_id IS NULL
AND color_filter.product_id IS NULL

```

### Join filter concept

The `join-filter` should make sure that a `to-many` association can be queried on multiple values, here is an example:

**Give me all products which do have "red" or "yellow" as property, but also "XL" or "L".**
On the SQL side, the following query must be generated for this purpose:

```sql
SELECT product.id

FROM product
    LEFT JOIN property_properties color_filter
        ON color_filter.product_id = product.id
        AND color_filter.id IN ("red", "yellow")

    LEFT JOIN property_properties size_filter
        ON size_filter.product_id = product.id
        AND size_filter.id IN ("XL", "L")

WHERE size_filter.product_id IS NOT NULL
AND color_filter.product_id IS NOT NULL

```

## Decision

Whether several joins must be made on an association must be recognized by the DBAL implementation itself. The user of the DAL does not have to pass an extra parameter for this.
However, since it is difficult to interpret what exactly is to be determined by the criteria, the algorithm for determination is based on certain rules.

We will form so called `join-groups` in the DAL. These are created per `multi-filter` layer. So a join to an association is only possible once per `multi-filter` layer. So we allow to query several fields within one join.
But if an already filtered field is filtered in another or nested `multi-filter`, a separate join is created for this field.
It is only necessary to resolve the `to-many` association several times.
After the `join-groups` have been formed, the field to be resolved is passed to the `FieldResolver` (which forms the SQL JOIN) and the filter in which this field is located.
Resolved filters in the JOIN are then marked and later in the WHERE they are linked with the corresponding AND/OR/NOT logic.

## Consequences

Queries against the DAL can now behave differently if multiple filters are set on a to many association.
To filter a to many association on multiple fields, where all filters should be related to each other, they must now be wrapped in a multi filter.

Note: If you use filters that filter on a to-many association field, you should check if the results of this query are still correct. It may be that more or less records are returned.

The following example shows how the filter behavior has changed on to-many associations:

```
1: 
$criteria->addFilter(
    new AndFilter([
        new EqualsFilter('product.categories.name', 'test-category'),
        new EqualsFilter('product.categories.active', true)
    ])
);

2:
$criteria->addFilter(
    new EqualsFilter('product.categories.name', 'test-category')
);
$criteria->addFilter(
    new EqualsFilter('product.categories.active', true)
);
```

1: Returns all products assigned to the `test-category` category where `test-category` is also active.
2: Returns all products that are assigned to the `test-category` category AND have a category assigned that is active.

---

---
url: /docs/v6.5/resources/references/adr/2020-11-19-dal-join-filter.md
---

# DAL join filter

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2020-11-19-dal-join-filter.md)
:::

## Context

Currently, there are various difficulties with the current implementation of the `anti-join-filter`.
Sometimes this does not lead to the correct results or the query cannot be executed due to a PHP exception.
Furthermore the counterpart to the `anti-join-filter`, the `join-filter`, is missing.
Currently the `anti-join-filter` is automatically assembled in the entity searcher if a `not-filter` exists that points to a field of an association.

### Anti join filter concept

The `anti-join-filter` should make sure that a `to-many` association can be queried negated on multiple values, here is an example:

**Give me all products which do not have "red" or "yellow" as property, but also not "XL" or "L".**
On the SQL side, the following query must be generated for this purpose:

```sql
SELECT product.id

FROM product
    LEFT JOIN property_properties color_filter
        ON color_filter.product_id = product.id
        AND color_filter.id IN ("red", "yellow")

    LEFT JOIN property_properties size_filter
        ON size_filter.product_id = product.id
        AND size_filter.id IN ("XL", "L")

WHERE size_filter.product_id IS NULL
AND color_filter.product_id IS NULL

```

### Join filter concept

The `join-filter` should make sure that a `to-many` association can be queried on multiple values, here is an example:

**Give me all products which do have "red" or "yellow" as property, but also "XL" or "L".**
On the SQL side, the following query must be generated for this purpose:

```sql
SELECT product.id

FROM product
    LEFT JOIN property_properties color_filter
        ON color_filter.product_id = product.id
        AND color_filter.id IN ("red", "yellow")

    LEFT JOIN property_properties size_filter
        ON size_filter.product_id = product.id
        AND size_filter.id IN ("XL", "L")

WHERE size_filter.product_id IS NOT NULL
AND color_filter.product_id IS NOT NULL

```

## Decision

Whether several joins must be made on an association must be recognized by the DBAL implementation itself. The user of the DAL does not have to pass an extra parameter for this.
However, since it is difficult to interpret what exactly is to be determined by the criteria, the algorithm for determination is based on certain rules.

We will form so called `join-groups` in the DAL. These are created per `multi-filter` layer. So a join to an association is only possible once per `multi-filter` layer. So we allow to query several fields within one join.
But if an already filtered field is filtered in another or nested `multi-filter`, a separate join is created for this field.
It is only necessary to resolve the `to-many` association several times.
After the `join-groups` have been formed, the field to be resolved is passed to the `FieldResolver` (which forms the SQL JOIN) and the filter in which this field is located.
Resolved filters in the JOIN are then marked and later in the WHERE they are linked with the corresponding AND/OR/NOT logic.

## Consequences

Queries against the DAL can now behave differently if multiple filters are set on a to many association.
To filter a to many association on multiple fields, where all filters should be related to each other, they must now be wrapped in a multi filter.

Note: If you use filters that filter on a to-many association field, you should check if the results of this query are still correct. It may be that more or less records are returned.

The following example shows how the filter behavior has changed on to-many associations:

```
1: 
$criteria->addFilter(
    new AndFilter([
        new EqualsFilter('product.categories.name', 'test-category'),
        new EqualsFilter('product.categories.active', true)
    ])
);

2:
$criteria->addFilter(
    new EqualsFilter('product.categories.name', 'test-category')
);
$criteria->addFilter(
    new EqualsFilter('product.categories.active', true)
);
```

1: Returns all products assigned to the `test-category` category where `test-category` is also active.
2: Returns all products that are assigned to the `test-category` category AND have a category assigned that is active.

---

---
url: /docs/v6.6/resources/references/adr/2020-11-19-dal-join-filter.md
---

# DAL join filter

::: info
This document represents an architecture decision record (ADR) and has been mirrored from the ADR section in our Shopware 6 repository.
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/adr/2020-11-19-dal-join-filter.md)
:::

## Context

Currently, there are various difficulties with the current implementation of the `anti-join-filter`.
Sometimes this does not lead to the correct results or the query cannot be executed due to a PHP exception.
Furthermore the counterpart to the `anti-join-filter`, the `join-filter`, is missing.
Currently the `anti-join-filter` is automatically assembled in the entity searcher if a `not-filter` exists that points to a field of an association.

### Anti join filter concept

The `anti-join-filter` should make sure that a `to-many` association can be queried negated on multiple values, here is an example:

**Give me all products which do not have "red" or "yellow" as property, but also not "XL" or "L".**
On the SQL side, the following query must be generated for this purpose:

```sql
SELECT product.id

FROM product
    LEFT JOIN property_properties color_filter
        ON color_filter.product_id = product.id
        AND color_filter.id IN ("red", "yellow")

    LEFT JOIN property_properties size_filter
        ON size_filter.product_id = product.id
        AND size_filter.id IN ("XL", "L")

WHERE size_filter.product_id IS NULL
AND color_filter.product_id IS NULL

```

### Join filter concept

The `join-filter` should make sure that a `to-many` association can be queried on multiple values, here is an example:

**Give me all products which do have "red" or "yellow" as property, but also "XL" or "L".**
On the SQL side, the following query must be generated for this purpose:

```sql
SELECT product.id

FROM product
    LEFT JOIN property_properties color_filter
        ON color_filter.product_id = product.id
        AND color_filter.id IN ("red", "yellow")

    LEFT JOIN property_properties size_filter
        ON size_filter.product_id = product.id
        AND size_filter.id IN ("XL", "L")

WHERE size_filter.product_id IS NOT NULL
AND color_filter.product_id IS NOT NULL

```

## Decision

Whether several joins must be made on an association must be recognized by the DBAL implementation itself. The user of the DAL does not have to pass an extra parameter for this.
However, since it is difficult to interpret what exactly is to be determined by the criteria, the algorithm for determination is based on certain rules.

We will form so called `join-groups` in the DAL. These are created per `multi-filter` layer. So a join to an association is only possible once per `multi-filter` layer. So we allow to query several fields within one join.
But if an already filtered field is filtered in another or nested `multi-filter`, a separate join is created for this field.
It is only necessary to resolve the `to-many` association several times.
After the `join-groups` have been formed, the field to be resolved is passed to the `FieldResolver` (which forms the SQL JOIN) and the filter in which this field is located.
Resolved filters in the JOIN are then marked and later in the WHERE they are linked with the corresponding AND/OR/NOT logic.

## Consequences

Queries against the DAL can now behave differently if multiple filters are set on a to many association.
To filter a to many association on multiple fields, where all filters should be related to each other, they must now be wrapped in a multi filter.

Note: If you use filters that filter on a to-many association field, you should check if the results of this query are still correct. It may be that more or less records are returned.

The following example shows how the filter behavior has changed on to-many associations:

```
1: 
$criteria->addFilter(
    new AndFilter([
        new EqualsFilter('product.categories.name', 'test-category'),
        new EqualsFilter('product.categories.active', true)
    ])
);

2:
$criteria->addFilter(
    new EqualsFilter('product.categories.name', 'test-category')
);
$criteria->addFilter(
    new EqualsFilter('product.categories.active', true)
);
```

1: Returns all products assigned to the `test-category` category where `test-category` is also active.
2: Returns all products that are assigned to the `test-category` category AND have a category assigned that is active.

---

---
url: /docs/guides/development/troubleshooting/dal-reference.md
---

# DAL Reference

The DAL reference documents fields, flags, filters, and aggregations for effective data management and querying within the platform.

The Data Abstraction Layer (DAL) reference helps you work with Shopware's entity model and query system. Use this section to look up DAL building blocks such as fields, flags, filters, and aggregations, and refer to the [DAL concepts guide](../../../../concepts/framework/data-abstraction-layer.md) for the architectural background.

## Section resources

* [Fields Reference](./fields-reference/index.md): Overview of available DAL field types and their storage characteristics.
* [Flags Reference](flags-reference.md): Reference for field flags such as `Required`, `ApiAware`, `Runtime`, or `WriteProtected`.
* [Filters Reference](filters-reference.md): Reference for DAL filters such as `equals`, `range`, `multi`, or `not`.
* [Aggregations Reference](aggregations-reference.md): Reference for metric and bucket aggregations such as `avg`, `terms`, `filter`, or `histogram`.

---

---
url: /docs/v6.5/resources/references/core-reference/dal-reference.md
---

# DAL Reference

The DAL reference documents fields, flags, filters, and aggregations for effective data management and querying within the platform.

---

---
url: /docs/v6.6/resources/references/core-reference/dal-reference.md
---

# DAL Reference

The DAL reference documents fields, flags, filters, and aggregations for effective data management and querying within the platform.

---

---
url: /docs/concepts/framework/data-abstraction-layer.md
---

# Data Abstraction Layer

## Database access

### Database guide

In contrast to most Symfony applications, Shopware uses no ORM, but a thin abstraction layer called the data abstraction layer (DAL).
The DAL is implemented with the specific needs of Shopware in mind and lets developers access the database via pre-defined interfaces.
Some concepts used by the DAL, like Criteria, may sound familiar to you if you know [Doctrine](https://symfony.com/doc/current/doctrine.html) or other ORMs.
A reference to more in-depth documentation about the DAL can be found below.

Refer to [Shopware 6.6.5.0 entity relationship model](https://developer.shopware.com/assets/shopware6-erd.pdf) that depicts different tables and their relationships.

Alternatively, you can export a fresh ER model, using [MySQL Workbench](https://dev.mysql.com/doc/workbench/en/wb-reverse-engineering.html), [PHPStorm Database Tools](https://www.jetbrains.com/help/phpstorm/creating-diagrams.html), or similar tool.

::: info
Mysql Workbench → File → Import → Reverse Engineer Mysql Script → Select Db → ER diagram is created.
If you want to have it as an image: File → Export → Export as PNG
:::

### CRUD operations

An EntityRepository is used to interact with the DAL.
This is the recommended way for developers to interface with the DAL or the database in general.

### Provisioning code to use the repositories

Before using the repositories, you will need to get them from the [Dependency Injection Container (DIC)](../../guides/plugins/plugins/services/dependency-injection.md).
This is done with [Constructor injection](https://symfony.com/doc/current/service_container/injection_types.html#constructor-injection), so you will need to extend your services constructor by expecting an EntityRepository:

```php
// <plugin root>/src/Service/DalExampleService.php
public function __construct (EntityRepository $productRepository)
{
    $this->productRepository = $productRepository;
}
```

If you are using [Service autowiring](https://symfony.com/doc/current/service_container/autowiring.html) with the correct type and argument variable names, the repository will be injected automatically.

Alternatively, configure the `product.repository` service to be injected explicitly:

```php
// <plugin root>src/Resources/config/services.php
$services->set(Swag\ExamplePlugin\Service\DalExampleService::class)
    ->args([service('product.repository')]);
```

You can read more about dependency injection and service registration in Shopware in the services guides:

### Translations

The DAL was designed, among other things, to enable the special requirements of Shopware's translation system.
When a record is read or searched, three language levels are searched.

1. **Current language**: The first level is the current language that is set and displayed to the user.
2. **Parent language**: the second level is an optional parent language that can be configured.
   So it is possible to translate certain dialects faster.
3. **System language**: The third and last level is the system language that is selected during the installation.
   Each entity in the system has a translation in this language.
   This serves as a final fallback to ensure only one label for the entity in the end.

The translations for a record are stored in a separate table.
The name of this table is always the same as the table for which the records are translated, with the additional suffix `_translation`.

On read, every translatable property is exposed twice: as the plain field for the current language (which may be `null`) and under `translated` with inheritance applied. Prefer `translated` in storefront and sales-channel contexts; use the plain field in Admin/CRUD flows where you need to know what is stored for that language. See [Plain vs translated entity fields](translations/plain-vs-translated-fields.md).

### Versioning

Another feature that the DAL offers is versioning.
This makes it possible to store multiple versions of a single entity.
All data assigned to an entity is duplicated and made available under the new version.
Multiple entities or changes to different entities can be stored for one version.
The versioning was designed for previews, publishing, or campaign features, to prepare changes that are not yet live and to be able to view them in the store.
Currently, it is not possible (yet) to create a completely new entity with another version than the default live version.
Means, you cannot "draft" the entity first and then update it into the live version.
A live version of your entity is always required, before deriving a new version from it.

The versioning is also reflected in the database.
Entities that are versionable always have a compound foreign key: `id`, `version_id`.
Also, the foreign keys, which point to a versioned record, always consist of two columns, e.g.: `product_id` and `product_version_id`.

### Context

The context `core/Framework/Context.php` defines important configuration of the shop system and is instantiated once per request.
Depending on the passed parameters it can change the CRUD behavior of the DAL.
For example when using the currency toggle in the storefront and selecting Dollar instead of Euro, the context currency ID is changed accordingly and all operations now refer to Dollar.

### Inheritance

Another reason why the DAL was designed is to meet the requirements of the product and variant system.
For this purpose, a parent-child inheritance system was implemented in the DAL.
This allows variants to inherit records, properties, or even whole associations from the parent or container product.
For example, if a variant has not been assigned any categories or images, those of the parent product are used.

### Indexing

The DAL was designed to be optimized for use in ecommerce.
One principle has proven to be very effective so far: "The more time you put into indexing data, the faster it is possible to read it".
This is reflected in Shopware as follows:

* A product is written once every X minutes
* A product is called X times every X seconds by a customer.

This varies depending on the store, but the ratio is always the same.
Data records are read way more often than they are written.
Therefore, it is worthwhile to spend a little more time on the writing process in order to minimize the effort required for the reading process.
This is done in the DAL via the Entity Indexer pattern.
As soon as a product record is written, the corresponding Product Indexer is triggered, which pre-selects certain aggregations and writes them away optimized for the later reading process.

---

---
url: /docs/v6.5/concepts/framework/data-abstraction-layer.md
---

# Data Abstraction Layer

## Database access

### Database guide

In contrast to most Symfony applications, Shopware uses no ORM, but a thin abstraction layer called the data abstraction layer (DAL). The DAL is implemented with the specific needs of Shopware in mind and lets developers access the database via pre-defined interfaces. Some concepts used by the DAL, like Criteria, may sound familiar to you if you know [Doctrine](https://symfony.com/doc/current/doctrine.html) or other ORMs. A reference to more in-depth documentation about the DAL can be found below.

### CRUD operations

An EntityRepository is used to interact with the DAL. This is the recommended way for developers to interface with the DAL or the database in general.

### Provisioning code to use the repositories

Before using the repositories, you will need to get them from the [Dependency Injection Container (DIC)](../../guides/plugins/plugins/plugin-fundamentals/dependency-injection). This is done with [Constructor injection](https://symfony.com/doc/current/service_container/injection_types.html#constructor-injection), so you will need to extend your services constructor by expecting an EntityRepository:

```php
// <plugin root>/src/Service/DalExampleService.php
public function __construct (EntityRepository $productRepository)
{
    $this->productRepository = $productRepository;
}
```

If you are using [Service autowiring](https://symfony.com/doc/current/service_container/autowiring.html) with the correct type and argument variable names, the repository will be injected automatically.

Alternatively, configure the `product.repository` service to be injected explicitly:

```html
// <plugin root>src/Resources/config/service.xml
<service id="Swag\ExamplePlugin\Service\DalExampleService">
    <argument type="service" id="product.repository"/>
</service>
```

You can read more about dependency injection and service registration in Shopware in the services guides:

### Translations

The DAL was designed, among other things, to enable the special requirements of Shopware's translation system. When a record is read or searched, three language levels are searched.

1. **Current language**: The first level is the current language that is set and displayed to the user.
2. **Parent language**: the second level is an optional parent language that can be configured. So it is possible to translate certain dialects faster.
3. **System language**: The third and last level is the system language that is selected during the installation. Each entity in the system has a translation in this language. This serves as a final fallback to ensure only one label for the entity in the end.

The translations for a record are stored in a separate table. The name of this table is always the same as the table for which the records are translated, with the additional suffix `_translation`.

### Versioning

Another feature of the DAL is the versioning it brings with it. This makes it possible to store multiple versions of an entity. All data subordinate to an entity is duplicated and made available under the new version. Multiple entities or changes to different entities can be stored for one version. The versioning was designed for previews, publishing, or campaign features, to prepare changes that are not yet live and to be able to view them in the store.

The versioning is also reflected in the database. Entities that are versionable always have a compound foreign key: `id`, `version_id`. Also, the foreign keys, which point to a versioned record, always consist of two columns, e.g.: `product_id` and `product_version_id`.

### Context

The context `core/Framework/Context.php` defines important configuration of the shop system and is instantiated once per request. Depending on the passed parameters it can change the CRUD behavior of the DAL. For example when using the currency toggle in the storefront and selecting Dollar instead of Euro, the context currency ID is changed accordingly and all operations now refer to Dollar.

### Inheritance

Another reason why the DAL was designed is to meet the requirements of the product and variant system. For this purpose, a parent-child inheritance system was implemented in the DAL. This allows variants to inherit records, properties, or even whole associations from the parent or container product. For example, if a variant has not been assigned any categories or images, those of the parent product are used.

### Indexing

The DAL was designed to be optimized for use in ecommerce. One principle has proven to be very effective so far: "The more time you put into indexing data, the faster it is possible to read it". This is reflected in Shopware as follows:

* A product is written once every X minutes
* A product is called X times every X seconds by a customer.

This varies depending on the store, but the ratio is always the same. Data records are read way more often than they are written. Therefore it is worthwhile to spend a little more time on the writing process in order to minimize the effort required for the reading process. This is done in the DAL via the Entity Indexer pattern. As soon as a product record is written, the corresponding Product Indexer is triggered, which pre-selects certain aggregations and writes them away optimized for the later reading process.

---

---
url: /docs/v6.6/concepts/framework/data-abstraction-layer.md
---

# Data Abstraction Layer

## Database access

### Database guide

In contrast to most Symfony applications, Shopware uses no ORM, but a thin abstraction layer called the data abstraction layer (DAL).
The DAL is implemented with the specific needs of Shopware in mind and lets developers access the database via pre-defined interfaces.
Some concepts used by the DAL, like Criteria, may sound familiar to you if you know [Doctrine](https://symfony.com/doc/current/doctrine.html) or other ORMs.
A reference to more in-depth documentation about the DAL can be found below.

Refer to [Shopware 6.6.5.0 entity relationship model](../../../assets/shopware6-erd.pdf) that depicts different tables and their relationships.

Alternatively, you can export a fresh ER model, using [MySQL Workbench](https://dev.mysql.com/doc/workbench/en/wb-reverse-engineering.html), [PHPStorm Database Tools](https://www.jetbrains.com/help/phpstorm/creating-diagrams.html), or similar tool.

::: info
Mysql Workbench → File → Import → Reverse Engineer Mysql Script → Select Db → ER diagram is created.
If you want to have it as an image: File → Export → Export as PNG
:::

### CRUD operations

An EntityRepository is used to interact with the DAL.
This is the recommended way for developers to interface with the DAL or the database in general.

### Provisioning code to use the repositories

Before using the repositories, you will need to get them from the [Dependency Injection Container (DIC)](../../guides/plugins/plugins/plugin-fundamentals/dependency-injection).
This is done with [Constructor injection](https://symfony.com/doc/current/service_container/injection_types.html#constructor-injection), so you will need to extend your services constructor by expecting an EntityRepository:

```php
// <plugin root>/src/Service/DalExampleService.php
public function __construct (EntityRepository $productRepository)
{
    $this->productRepository = $productRepository;
}
```

If you are using [Service autowiring](https://symfony.com/doc/current/service_container/autowiring.html) with the correct type and argument variable names, the repository will be injected automatically.

Alternatively, configure the `product.repository` service to be injected explicitly:

```html
// <plugin root>src/Resources/config/service.xml
<service id="Swag\ExamplePlugin\Service\DalExampleService">
    <argument type="service" id="product.repository"/>
</service>
```

You can read more about dependency injection and service registration in Shopware in the services guides:

### Translations

The DAL was designed, among other things, to enable the special requirements of Shopware's translation system.
When a record is read or searched, three language levels are searched.

1. **Current language**: The first level is the current language that is set and displayed to the user.
2. **Parent language**: the second level is an optional parent language that can be configured.
   So it is possible to translate certain dialects faster.
3. **System language**: The third and last level is the system language that is selected during the installation.
   Each entity in the system has a translation in this language.
   This serves as a final fallback to ensure only one label for the entity in the end.

The translations for a record are stored in a separate table.
The name of this table is always the same as the table for which the records are translated, with the additional suffix `_translation`.

### Versioning

Another feature that the DAL offers is versioning.
This makes it possible to store multiple versions of a single entity.
All data assigned to an entity is duplicated and made available under the new version.
Multiple entities or changes to different entities can be stored for one version.
The versioning was designed for previews, publishing, or campaign features, to prepare changes that are not yet live and to be able to view them in the store.
Currently, it is not possible (yet) to create a completely new entity with another version than the default live version.
Means, you cannot "draft" the entity first and then update it into the live version.
A live version of your entity is always required, before deriving a new version from it.

The versioning is also reflected in the database.
Entities that are versionable always have a compound foreign key: `id`, `version_id`.
Also, the foreign keys, which point to a versioned record, always consist of two columns, e.g.: `product_id` and `product_version_id`.

### Context

The context `core/Framework/Context.php` defines important configuration of the shop system and is instantiated once per request.
Depending on the passed parameters it can change the CRUD behavior of the DAL.
For example when using the currency toggle in the storefront and selecting Dollar instead of Euro, the context currency ID is changed accordingly and all operations now refer to Dollar.

### Inheritance

Another reason why the DAL was designed is to meet the requirements of the product and variant system.
For this purpose, a parent-child inheritance system was implemented in the DAL.
This allows variants to inherit records, properties, or even whole associations from the parent or container product.
For example, if a variant has not been assigned any categories or images, those of the parent product are used.

### Indexing

The DAL was designed to be optimized for use in ecommerce.
One principle has proven to be very effective so far: "The more time you put into indexing data, the faster it is possible to read it".
This is reflected in Shopware as follows:

* A product is written once every X minutes
* A product is called X times every X seconds by a customer.

This varies depending on the store, but the ratio is always the same.
Data records are read way more often than they are written.
Therefore, it is worthwhile to spend a little more time on the writing process in order to minimize the effort required for the reading process.
This is done in the DAL via the Entity Indexer pattern.
As soon as a product record is written, the corresponding Product Indexer is triggered, which pre-selects certain aggregations and writes them away optimized for the later reading process.

---

---
url: /resources/admin-extension-sdk/concepts/datahandling.md
---

# Data Handling

This guide elaborates on how the data handling works between extensions and the Shopware Administration.

## What are datasets?

Datasets consist of a unique identifier, an `id` and some `data` which could be anything from a single value to a whole entity.
The id gives some insight on what to expect as the value. For example `sw-product-detail__product` contains the product of the product detail page.

## How to find available datasets

You can explore all available datasets with the Vue Devtool extension we provide with the Shopware administration.

* Open the Vue DevTools in the Shopware Administration
* Change to the Shopware Extension API inspector

In this inspector you will see all published datasets if there are any in the current view.

## Example

![Action button example](./assets/devtool-example.png)

---

---
url: /docs/guides/plugins/plugins/administration/data-handling-processing.md
---

# Data Handling and Processing

These guides cover how plugins work with data in the Administration and Storefront.

They cover how to manipulate, display, and extend data in the Administration, including working with repositories, criteria, associations, custom fields, media, and related UI components.

* [Using Data Handling](./using-data-handling)
* [Using the Data Grid Component](./using-the-data-grid-component)
* [Using Custom Fields](./using-custom-fields)
* [Handling Media](./handling-media)
* [Add Custom Data to the Search](./search-custom-data.md)
* [Using Vuex State](./using-vuex-state)
* [The Shopware Object](./the-shopware-object)

---

---
url: /docs/guides/plugins/plugins/framework/data-handling.md
---

# Data Handling/Data Abstraction Layer

The data handling, or the Data Abstraction Layer (DAL), can be an overwhelming topic. Yet, if you know the right start, it will be fairly easy to deal with.

Start with the step that matches what you want to do:

* Create or change database tables for a plugin - [Database migrations](../../database/database-migrations.md)
* Add a custom DAL entity for a plugin table - [Adding Custom Complex Data](add-custom-complex-data.md)
* Read data through repositories and criteria - [Reading Data](reading-data.md)
* Write data through repositories - [Writing Data](writing-data.md)
* React to DAL write or entity events - [Using Database Events](using-database-events.md)

For custom plugin data, create the database table first with a migration, then add the DAL entity definition that maps to that table.

---

---
url: /docs/v6.5/guides/plugins/plugins/framework/data-handling.md
---

# Data Handling/DataAbstractionLayer

The data handling, or the Data Abstraction Layer (DAL), can be an overwhelming topic. Yet, if you know the right start, it will be fairly easy to deal with.

Hence, here are some good starting topics:

Also, [listening to events](using-database-events) of the DAL will come in handy for sure.

---

---
url: /docs/v6.6/guides/plugins/plugins/framework/data-handling.md
---

# Data Handling/DataAbstractionLayer

The data handling, or the Data Abstraction Layer (DAL), can be an overwhelming topic. Yet, if you know the right start, it will be fairly easy to deal with.

Hence, here are some good starting topics:

Also, [listening to events](using-database-events) of the DAL will come in handy for sure.

---

---
url: >-
  /docs/resources/references/app-reference/script-reference/data-loading-script-services-reference.md
---

# Data Loading script services reference

## [services.repository (`Shopware\Core\Framework\DataAbstractionLayer\Facade\RepositoryFacade`)](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Facade/RepositoryFacade.php) {#repositoryfacade}

The `repository` service allows you to query data, that is stored inside shopware.
Keep in mind that your app needs to have the correct permissions for the data it queries through this service.

### aggregate()

* The `aggregate()` method allows you to execute aggregations specified in the given criteria.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Search\AggregationResult\AggregationResultCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Search/AggregationResult/AggregationResultCollection.php)

  A `AggregationResultCollection` including the results of the aggregations you specified in the criteria.

* **Arguments:**
  * *`string`* **entityName**: The name of the Entity you want to aggregate data on, e.g. `product` or `media`.
  * *`array`* **criteria**: The criteria that define your aggregations.

* **Examples:**
  * Aggregate data for multiple entities, e.g. the sum of the gross price of all products.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'aggregations': [
            { 'name': 'sumOfPrices', 'type': 'sum', 'field': 'price.gross' }
        ]
    } %}

    {% set sumResult = services.repository.aggregate('product', criteria).get('sumOfPrices') %}

    {% do page.addArrayExtension('myProductAggregations', {
        'sum': sumResult.getSum
    }) %}
    ```

### ids()

* The `ids()` method allows you to search for the Ids of Entities that match a given criteria.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Search\IdSearchResult`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Search/IdSearchResult.php)

  A `IdSearchResult` including all entity-ids that matched your criteria.

* **Arguments:**
  * *`string`* **entityName**: The name of the Entity you want to search for, e.g. `product` or `media`.
  * *`array`* **criteria**: The criteria used for your search.

* **Examples:**
  * Get the Ids of products with the given ProductNumber.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'filter': [
            { 'field': 'productNumber', 'type': 'equals', 'value': 'p1' }
        ]
    } %}

    {% set productIds = services.repository.ids('product', criteria).ids %}

    {% do page.addArrayExtension('myProductIds', {
        'ids': productIds
    }) %}
    ```

### search()

* The `search()` method allows you to search for Entities that match a given criteria.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Search\EntitySearchResult`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Search/EntitySearchResult.php)

  A `EntitySearchResult` including all entities that matched your criteria.

* **Arguments:**
  * *`string`* **entityName**: The name of the Entity you want to search for, e.g. `product` or `media`.
  * *`array`* **criteria**: The criteria used for your search.

* **Examples:**
  * Load a single product.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'ids': [ hook.productId ]
    } %}

    {% set product = services.repository.search('product', criteria).getEntities().first %}

    {% do page.addExtension('myProduct', product) %}
    ```
  * Filter the search result.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'filter': [
            { 'field': 'productNumber', 'type': 'equals', 'value': 'p1' }
        ]
    } %}

    {% set product = services.repository.search('product', criteria).getEntities().first %}

    {% do page.addExtension('myProduct', product) %}
    ```
  * Add associations that should be included in the result.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'ids': [ hook.productId ],
        'associations': {
            'manufacturer': {}
        }
    } %}

    {% set product = services.repository.search('product', criteria).getEntities().first %}

    {% do page.addExtension('myProduct', product) %}
    {% do page.addExtension('myManufacturer', product.manufacturer) %}
    ```

***

## [services.store (`Shopware\Core\Framework\DataAbstractionLayer\Facade\SalesChannelRepositoryFacade`)](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Facade/SalesChannelRepositoryFacade.php) {#saleschannelrepositoryfacade}

The `store` service can be used to access publicly available `store-api` data.
As the data is publicly available your app does not need any additional permissions to use this service,
however querying data and also loading associations is restricted to the entities that are also available through the `store-api`.

Notice that the returned entities are already processed for the storefront,
this means that e.g. product prices are already calculated based on the current context.

### aggregate()

* The `aggregate()` method allows you to execute aggregations specified in the given criteria.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Search\AggregationResult\AggregationResultCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Search/AggregationResult/AggregationResultCollection.php)

  A `AggregationResultCollection` including the results of the aggregations you specified in the criteria.

* **Arguments:**
  * *`string`* **entityName**: The name of the Entity you want to aggregate data on, e.g. `product` or `media`.
  * *`array`* **criteria**: The criteria that define your aggregations.

* **Examples:**
  * Aggregate data for multiple entities, e.g. the sum of the children of all products.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'aggregations': [
            { 'name': 'sumOfChildren', 'type': 'sum', 'field': 'childCount' }
        ]
    } %}

    {% set sumResult = services.store.aggregate('product', criteria).get('sumOfChildren') %}

    {% do page.addArrayExtension('myProductAggregations', {
        'sum': sumResult.getSum
    }) %}
    ```

### ids()

* The `ids()` method allows you to search for the Ids of Entities that match a given criteria.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Search\IdSearchResult`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Search/IdSearchResult.php)

  A `IdSearchResult` including all entity-ids that matched your criteria.

* **Arguments:**
  * *`string`* **entityName**: The name of the Entity you want to search for, e.g. `product` or `media`.
  * *`array`* **criteria**: The criteria used for your search.

* **Examples:**
  * Get the Ids of products with the given ProductNumber.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'filter': [
            { 'field': 'productNumber', 'type': 'equals', 'value': 'p1' }
        ]
    } %}

    {% set productIds = services.store.ids('product', criteria).ids %}

    {% do page.addArrayExtension('myProductIds', {
        'ids': productIds
    }) %}
    ```

### search()

* The `search()` method allows you to search for Entities that match a given criteria.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Search\EntitySearchResult`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Search/EntitySearchResult.php)

  A `EntitySearchResult` including all entities that matched your criteria.

* **Arguments:**
  * *`string`* **entityName**: The name of the Entity you want to search for, e.g. `product` or `media`.
  * *`array`* **criteria**: The criteria used for your search.

* **Examples:**
  * Load a single storefront product.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'ids': [ hook.productId ]
    } %}

    {% set product = services.store.search('product', criteria).getEntities().first %}

    {% do page.addExtension('myProduct', product) %}
    ```
  * Filter the search result.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'filter': [
            { 'field': 'productNumber', 'type': 'equals', 'value': 'p1' }
        ]
    } %}

    {% set product = services.store.search('product', criteria).getEntities().first %}

    {% do page.addExtension('myProduct', product) %}
    ```
  * Add associations that should be included in the result.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'ids': [ hook.productId ],
        'associations': {
            'manufacturer': {}
        }
    } %}

    {% set product = services.store.search('product', criteria).getEntities().first %}

    {% do page.addExtension('myProduct', product) %}
    {% do page.addExtension('myManufacturer', product.manufacturer) %}
    ```

***

---

---
url: >-
  /docs/v6.5/resources/references/app-reference/script-reference/data-loading-script-services-reference.md
---

# Data Loading script services reference

## [services.repository (`Shopware\Core\Framework\DataAbstractionLayer\Facade\RepositoryFacade`)](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Facade/RepositoryFacade.php) {#repositoryfacade}

The `repository` service allows you to query data, that is stored inside shopware.
Keep in mind that your app needs to have the correct permissions for the data it queries through this service.

### search()

* The `search()` method allows you to search for Entities that match a given criteria.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Search\EntitySearchResult`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Search/EntitySearchResult.php)

  A `EntitySearchResult` including all entities that matched your criteria.

* **Arguments:**
  * *`string`* **entityName**: The name of the Entity you want to search for, e.g. `product` or `media`.
  * *`array`* **criteria**: The criteria used for your search.

* **Examples:**
  * Load a single product.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'ids': [ hook.productId ]
    } %}

    {% set product = services.repository.search('product', criteria).first %}

    {% do page.addExtension('myProduct', product) %}
    ```

  * Filter the search result.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'filter': [
            { 'field': 'productNumber', 'type': 'equals', 'value': 'p1' }
        ]
    } %}

    {% set product = services.repository.search('product', criteria).first %}

    {% do page.addExtension('myProduct', product) %}
    ```

  * Add associations that should be included in the result.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'ids': [ hook.productId ],
        'associations': {
            'manufacturer': {}
        }
    } %}

    {% set product = services.repository.search('product', criteria).first %}

    {% do page.addExtension('myProduct', product) %}
    {% do page.addExtension('myManufacturer', product.manufacturer) %}
    ```

### ids()

* The `ids()` method allows you to search for the Ids of Entities that match a given criteria.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Search\IdSearchResult`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Search/IdSearchResult.php)

  A `IdSearchResult` including all entity-ids that matched your criteria.

* **Arguments:**
  * *`string`* **entityName**: The name of the Entity you want to search for, e.g. `product` or `media`.
  * *`array`* **criteria**: The criteria used for your search.

* **Examples:**
  * Get the Ids of products with the given ProductNumber.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'filter': [
            { 'field': 'productNumber', 'type': 'equals', 'value': 'p1' }
        ]
    } %}

    {% set productIds = services.repository.ids('product', criteria).ids %}

    {% do page.addArrayExtension('myProductIds', {
        'ids': productIds
    }) %}
    ```

### aggregate()

* The `aggregate()` method allows you to execute aggregations specified in the given criteria.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Search\AggregationResult\AggregationResultCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Search/AggregationResult/AggregationResultCollection.php)

  A `AggregationResultCollection` including the results of the aggregations you specified in the criteria.

* **Arguments:**
  * *`string`* **entityName**: The name of the Entity you want to aggregate data on, e.g. `product` or `media`.
  * *`array`* **criteria**: The criteria that define your aggregations.

* **Examples:**
  * Aggregate data for multiple entities, e.g. the sum of the gross price of all products.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'aggregations': [
            { 'name': 'sumOfPrices', 'type': 'sum', 'field': 'price.gross' }
        ]
    } %}

    {% set sumResult = services.repository.aggregate('product', criteria).get('sumOfPrices') %}

    {% do page.addArrayExtension('myProductAggregations', {
        'sum': sumResult.getSum
    }) %}
    ```

***

## [services.store (`Shopware\Core\Framework\DataAbstractionLayer\Facade\SalesChannelRepositoryFacade`)](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Facade/SalesChannelRepositoryFacade.php) {#saleschannelrepositoryfacade}

The `store` service can be used to access publicly available `store-api` data.
As the data is publicly available your app does not need any additional permissions to use this service,
however querying data and also loading associations is restricted to the entities that are also available through the `store-api`.

Notice that the returned entities are already processed for the storefront,
this means that e.g. product prices are already calculated based on the current context.

### search()

* The `search()` method allows you to search for Entities that match a given criteria.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Search\EntitySearchResult`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Search/EntitySearchResult.php)

  A `EntitySearchResult` including all entities that matched your criteria.

* **Arguments:**
  * *`string`* **entityName**: The name of the Entity you want to search for, e.g. `product` or `media`.
  * *`array`* **criteria**: The criteria used for your search.

* **Examples:**
  * Load a single storefront product.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'ids': [ hook.productId ]
    } %}

    {% set product = services.store.search('product', criteria).first %}

    {% do page.addExtension('myProduct', product) %}
    ```

  * Filter the search result.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'filter': [
            { 'field': 'productNumber', 'type': 'equals', 'value': 'p1' }
        ]
    } %}

    {% set product = services.store.search('product', criteria).first %}

    {% do page.addExtension('myProduct', product) %}
    ```

  * Add associations that should be included in the result.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'ids': [ hook.productId ],
        'associations': {
            'manufacturer': {}
        }
    } %}

    {% set product = services.store.search('product', criteria).first %}

    {% do page.addExtension('myProduct', product) %}
    {% do page.addExtension('myManufacturer', product.manufacturer) %}
    ```

### ids()

* The `ids()` method allows you to search for the Ids of Entities that match a given criteria.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Search\IdSearchResult`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Search/IdSearchResult.php)

  A `IdSearchResult` including all entity-ids that matched your criteria.

* **Arguments:**
  * *`string`* **entityName**: The name of the Entity you want to search for, e.g. `product` or `media`.
  * *`array`* **criteria**: The criteria used for your search.

* **Examples:**
  * Get the Ids of products with the given ProductNumber.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'filter': [
            { 'field': 'productNumber', 'type': 'equals', 'value': 'p1' }
        ]
    } %}

    {% set productIds = services.store.ids('product', criteria).ids %}

    {% do page.addArrayExtension('myProductIds', {
        'ids': productIds
    }) %}
    ```

### aggregate()

* The `aggregate()` method allows you to execute aggregations specified in the given criteria.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Search\AggregationResult\AggregationResultCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Search/AggregationResult/AggregationResultCollection.php)

  A `AggregationResultCollection` including the results of the aggregations you specified in the criteria.

* **Arguments:**
  * *`string`* **entityName**: The name of the Entity you want to aggregate data on, e.g. `product` or `media`.
  * *`array`* **criteria**: The criteria that define your aggregations.

* **Examples:**
  * Aggregate data for multiple entities, e.g. the sum of the children of all products.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'aggregations': [
            { 'name': 'sumOfChildren', 'type': 'sum', 'field': 'childCount' }
        ]
    } %}

    {% set sumResult = services.store.aggregate('product', criteria).get('sumOfChildren') %}

    {% do page.addArrayExtension('myProductAggregations', {
        'sum': sumResult.getSum
    }) %}
    ```

***

---

---
url: >-
  /docs/v6.6/resources/references/app-reference/script-reference/data-loading-script-services-reference.md
---

# Data Loading script services reference

## [services.repository (`Shopware\Core\Framework\DataAbstractionLayer\Facade\RepositoryFacade`)](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Facade/RepositoryFacade.php) {#repositoryfacade}

The `repository` service allows you to query data, that is stored inside shopware.
Keep in mind that your app needs to have the correct permissions for the data it queries through this service.

### search()

* The `search()` method allows you to search for Entities that match a given criteria.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Search\EntitySearchResult`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Search/EntitySearchResult.php)

  A `EntitySearchResult` including all entities that matched your criteria.

* **Arguments:**
  * *`string`* **entityName**: The name of the Entity you want to search for, e.g. `product` or `media`.
  * *`array`* **criteria**: The criteria used for your search.

* **Examples:**
  * Load a single product.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'ids': [ hook.productId ]
    } %}

    {% set product = services.repository.search('product', criteria).first %}

    {% do page.addExtension('myProduct', product) %}
    ```

  * Filter the search result.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'filter': [
            { 'field': 'productNumber', 'type': 'equals', 'value': 'p1' }
        ]
    } %}

    {% set product = services.repository.search('product', criteria).first %}

    {% do page.addExtension('myProduct', product) %}
    ```

  * Add associations that should be included in the result.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'ids': [ hook.productId ],
        'associations': {
            'manufacturer': {}
        }
    } %}

    {% set product = services.repository.search('product', criteria).first %}

    {% do page.addExtension('myProduct', product) %}
    {% do page.addExtension('myManufacturer', product.manufacturer) %}
    ```

### ids()

* The `ids()` method allows you to search for the Ids of Entities that match a given criteria.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Search\IdSearchResult`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Search/IdSearchResult.php)

  A `IdSearchResult` including all entity-ids that matched your criteria.

* **Arguments:**
  * *`string`* **entityName**: The name of the Entity you want to search for, e.g. `product` or `media`.
  * *`array`* **criteria**: The criteria used for your search.

* **Examples:**
  * Get the Ids of products with the given ProductNumber.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'filter': [
            { 'field': 'productNumber', 'type': 'equals', 'value': 'p1' }
        ]
    } %}

    {% set productIds = services.repository.ids('product', criteria).ids %}

    {% do page.addArrayExtension('myProductIds', {
        'ids': productIds
    }) %}
    ```

### aggregate()

* The `aggregate()` method allows you to execute aggregations specified in the given criteria.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Search\AggregationResult\AggregationResultCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Search/AggregationResult/AggregationResultCollection.php)

  A `AggregationResultCollection` including the results of the aggregations you specified in the criteria.

* **Arguments:**
  * *`string`* **entityName**: The name of the Entity you want to aggregate data on, e.g. `product` or `media`.
  * *`array`* **criteria**: The criteria that define your aggregations.

* **Examples:**
  * Aggregate data for multiple entities, e.g. the sum of the gross price of all products.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'aggregations': [
            { 'name': 'sumOfPrices', 'type': 'sum', 'field': 'price.gross' }
        ]
    } %}

    {% set sumResult = services.repository.aggregate('product', criteria).get('sumOfPrices') %}

    {% do page.addArrayExtension('myProductAggregations', {
        'sum': sumResult.getSum
    }) %}
    ```

***

## [services.store (`Shopware\Core\Framework\DataAbstractionLayer\Facade\SalesChannelRepositoryFacade`)](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Facade/SalesChannelRepositoryFacade.php) {#saleschannelrepositoryfacade}

The `store` service can be used to access publicly available `store-api` data.
As the data is publicly available your app does not need any additional permissions to use this service,
however querying data and also loading associations is restricted to the entities that are also available through the `store-api`.

Notice that the returned entities are already processed for the storefront,
this means that e.g. product prices are already calculated based on the current context.

### search()

* The `search()` method allows you to search for Entities that match a given criteria.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Search\EntitySearchResult`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Search/EntitySearchResult.php)

  A `EntitySearchResult` including all entities that matched your criteria.

* **Arguments:**
  * *`string`* **entityName**: The name of the Entity you want to search for, e.g. `product` or `media`.
  * *`array`* **criteria**: The criteria used for your search.

* **Examples:**
  * Load a single storefront product.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'ids': [ hook.productId ]
    } %}

    {% set product = services.store.search('product', criteria).first %}

    {% do page.addExtension('myProduct', product) %}
    ```

  * Filter the search result.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'filter': [
            { 'field': 'productNumber', 'type': 'equals', 'value': 'p1' }
        ]
    } %}

    {% set product = services.store.search('product', criteria).first %}

    {% do page.addExtension('myProduct', product) %}
    ```

  * Add associations that should be included in the result.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'ids': [ hook.productId ],
        'associations': {
            'manufacturer': {}
        }
    } %}

    {% set product = services.store.search('product', criteria).first %}

    {% do page.addExtension('myProduct', product) %}
    {% do page.addExtension('myManufacturer', product.manufacturer) %}
    ```

### ids()

* The `ids()` method allows you to search for the Ids of Entities that match a given criteria.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Search\IdSearchResult`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Search/IdSearchResult.php)

  A `IdSearchResult` including all entity-ids that matched your criteria.

* **Arguments:**
  * *`string`* **entityName**: The name of the Entity you want to search for, e.g. `product` or `media`.
  * *`array`* **criteria**: The criteria used for your search.

* **Examples:**
  * Get the Ids of products with the given ProductNumber.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'filter': [
            { 'field': 'productNumber', 'type': 'equals', 'value': 'p1' }
        ]
    } %}

    {% set productIds = services.store.ids('product', criteria).ids %}

    {% do page.addArrayExtension('myProductIds', {
        'ids': productIds
    }) %}
    ```

### aggregate()

* The `aggregate()` method allows you to execute aggregations specified in the given criteria.

* **Returns** [`Shopware\Core\Framework\DataAbstractionLayer\Search\AggregationResult\AggregationResultCollection`](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/DataAbstractionLayer/Search/AggregationResult/AggregationResultCollection.php)

  A `AggregationResultCollection` including the results of the aggregations you specified in the criteria.

* **Arguments:**
  * *`string`* **entityName**: The name of the Entity you want to aggregate data on, e.g. `product` or `media`.
  * *`array`* **criteria**: The criteria that define your aggregations.

* **Examples:**
  * Aggregate data for multiple entities, e.g. the sum of the children of all products.

    ```twig
    {% set page = hook.page %}
    {# @var page \Shopware\Storefront\Page\Page #}

    {% set criteria = {
        'aggregations': [
            { 'name': 'sumOfChildren', 'type': 'sum', 'field': 'childCount' }
        ]
    } %}

    {% set sumResult = services.store.aggregate('product', criteria).get('sumOfChildren') %}

    {% do page.addArrayExtension('myProductAggregations', {
        'sum': sumResult.getSum
    }) %}
    ```

***

---

---
url: /docs/guides/hosting/infrastructure/database.md
---

# Database

This guide explains how to operate Shopware with a reliable database setup.
It covers cluster-based scaling for read traffic and connection handling for long-running PHP worker environments.

## Cluster Setup

::: info
We recommend the usage of [ProxySQL](https://proxysql.com/) as a proxy for the database cluster instead of configuring the application to connect to different database servers directly.
ProxySQL allows you to manage the database cluster more efficiently and provides additional features like query caching, connection pooling, load balancing, and failover.
:::

To scale Shopware even further, we recommend using a database cluster.
A database cluster consists of multiple read-only servers managed by a single primary instance.

Shopware already splits read and write SQL queries by default.
When a write  [`INSERT`/`UPDATE`/`DELETE`/...](https://github.com/shopware/shopware/blob/v6.4.11.1/src/Core/Profiling/Doctrine/DebugStack.php#L48) query is executed, the query is delegated to the primary server, and the current connection uses only the primary node for subsequent calls.
This is ensured by the `executeStatement` method in the [DebugStack decoration](https://github.com/shopware/shopware/blob/v6.4.11.1/src/Core/Profiling/Doctrine/DebugStack.php#L48).
That way, Shopware can ensure read-write consistency for records within the same request.
However, it doesn't take into account that read-only child nodes might not be in sync with the primary node.
This is left to the database replication process.

### Preparing Shopware

We suggest following the steps below to make the splitting the most effective.

#### Using the optimal MySQL configuration

By default, Shopware does not set specific MySQL configurations that make sure the database is optimized for Shopware usage.
These variables are set in cluster mode only on the read-only server.
To make sure that Shopware works flawlessly, these configurations must be configured directly on the MySQL server so these variables are set on any server.

The following options should be set:

* Make sure that `group_concat_max_len` is by default higher or equal to `320000`
* Make sure that `sql_mode` doesn't contain `ONLY_FULL_GROUP_BY`

After this change, you can set also `SQL_SET_DEFAULT_SESSION_VARIABLES=0` in the `.env` file so Shopware does not check for those variables at runtime.

### Configure the database cluster

To use the MySQL cluster, you have to configure the following in the `.env` file:

* `DATABASE_URL` is the connection string for the MySQL primary.
* `DATABASE_REPLICA_x_URL` (e.g `DATABASE_REPLICA_0_URL`, `DATABASE_REPLICA_1_URL`) - is the connection string for the MySQL read-only server.

## SSL/TLS Connection

Many cloud database providers and production environments require encrypted connections.
Shopware supports TLS for MySQL/MariaDB connections through the `DATABASE_SSL_*` environment
variables.

### Using DATABASE\_SSL\_\* environment variables

Shopware's `MySQLFactory` automatically reads these environment variables and applies them
to the Doctrine database connection. No additional configuration is needed — just set the
variables in your `.env.local` file:

```dotenv
DATABASE_URL="mysql://username:password@host:3306/dbname"
DATABASE_SSL_CA="/etc/ssl/certs/db-ca.pem"
DATABASE_SSL_CERT="/etc/ssl/certs/db-client-cert.pem"
DATABASE_SSL_KEY="/etc/ssl/certs/db-client-key.pem"
# DATABASE_SSL_DONT_VERIFY_SERVER_CERT=1  # Uncomment to skip verification (non-production only)
```

The following table describes the available `DATABASE_SSL_*` variables.

| Variable                               | Description                                                                                 |
|----------------------------------------|---------------------------------------------------------------------------------------------|
| `DATABASE_SSL_CA`                      | Path to the Certificate Authority file (PEM) used for server certificate verification       |
| `DATABASE_SSL_CERT`                    | Path to the client certificate file (PEM) for mutual TLS                                    |
| `DATABASE_SSL_KEY`                     | Path to the client private key file (PEM) for mutual TLS                                    |
| `DATABASE_SSL_DONT_VERIFY_SERVER_CERT` | Set to `1` to skip server certificate verification (non-production only); requires PHP 8.2+ |

> \[!NOTE]
> `DATABASE_SSL_DONT_VERIFY_SERVER_CERT` requires PHP 8.2 or later and the `PDO\MySQL`
> class available in `ext-pdo_mysql`. For a full list of available environment variables,
> see the [Environment Variables reference](../configurations/shopware/environment-variables.md).

#### Force SSL without a CA certificate

If your database server requires TLS, but you don't have the CA certificate handy
(for example, on a managed cloud database), you can force an encrypted connection
without certificate verification:

```dotenv
DATABASE_SSL_CA=true
DATABASE_SSL_DONT_VERIFY_SERVER_CERT=1
```

This tells MySQL to use SSL for the connection but skip certificate validation.
Only use this in development or staging — never in production without a proper CA.

### Persistent connections (`DATABASE_PERSISTENT_CONNECTION`)

When enabled, the database connection is kept open and reused
across requests instead of opening a new one every time. This avoids the overhead of
the TLS handshake and MySQL authentication on each request.

**Use cases:**

* Long-running PHP worker processes (FrankenPHP worker mode, CLI message consumers),
  where reconnecting on every job is wasteful
* High-traffic environments where connection churn dominates request time

**When to avoid:**

* Database clusters using read replicas: persistent connections can pin requests to the
  wrong node, breaking read/write splitting
* Horizontally scaled web servers with many PHP-FPM children: MySQL has a finite
  `max_connections` limit, and idle persistent connections from every FPM child can
  quickly exhaust it
* Development environments where frequent restarts are expected

:::warning
Only enable this on dedicated worker servers. On web servers with many FPM
children connecting to a database cluster, persistent connections can cause
connection exhaustion and unpredictable replica routing.
:::

### Protocol compression (`DATABASE_PROTOCOL_COMPRESSION`)

When enabled, MySQL wire protocol traffic is compressed
before transmission. This reduces network bandwidth usage at the cost of a small
CPU overhead for compression and decompression.

**Use cases:**

* Bandwidth-constrained environments (for example, cloud databases with metered
  egress, or connections over the public internet)
* Large result sets or high throughput workloads where the network link is
  saturated before CPU

**Trade-off:** The compression itself adds a small latency penalty, but this is
usually negligible compared to the benefit of avoiding a network bottleneck.
If your LAN port is at 100% utilization, compression will improve effective
throughput more than it costs in CPU.

### Amazon RDS / Aurora

AWS RDS and Aurora enforce TLS by default. Download the [AWS RDS CA bundle](https://truststore.pki.rds.amazonaws.com/global/global-bundle.pem)
and reference it in your connection:

```dotenv
DATABASE_URL="mysql://username:password@your-cluster.rds.amazonaws.com:3306/dbname"
DATABASE_SSL_CA="/etc/ssl/certs/rds-ca-bundle.pem"
```

### Verify the TLS connection

To confirm that TLS is active, run this SQL query via the Shopware CLI or your MySQL client:

```sql
SHOW STATUS LIKE 'Ssl_cipher';
```

A non-empty value (for example, `TLS_AES_256_GCM_SHA384`) confirms the connection is encrypted.

## Setup for long-running environments

When running Shopware in long-lived PHP worker environments such as FrankenPHP worker mode, database connections can stay open long enough to exceed MySQL's `wait_timeout`.
This can lead to `MySQL server has gone away` errors on later requests.

Shopware does not install a reconnect package by default, but you can enable this behavior yourself with [`facile-it/doctrine-mysql-come-back`](https://github.com/facile-it/doctrine-mysql-come-back):

```bash
composer require facile-it/doctrine-mysql-come-back
```

Configure the wrapper class on `DATABASE_URL` with `Facile\DoctrineMySQLComeBack\Doctrine\DBAL\Connection`:

```dotenv
DATABASE_URL="mysql://username:password@localhost:3306/dbname?wrapperClass=?wrapperClass=Facile\DoctrineMySQLComeBack\Doctrine\DBAL\Connection&driverOptions[x_reconnect_attempts]=3"
```

If you are using Shopware with read replicas, use `Facile\DoctrineMySQLComeBack\Doctrine\DBAL\Connections\PrimaryReadReplicaConnection` instead:

```dotenv
DATABASE_URL="mysql://username:password@localhost:3306/dbname?wrapperClass=Facile\DoctrineMySQLComeBack\Doctrine\DBAL\Connections\PrimaryReadReplicaConnection&driverOptions[x_reconnect_attempts]=3"
DATABASE_REPLICA_0_URL="mysql://username:password@replica:3306/dbname"
```

---

---
url: /docs/guides/plugins/plugins/database.md
---

# Database

Plugins can extend or interact with the Shopware database using migrations, entities, and custom fields.

This section covers:

* How to create and manage database migrations
* How to generate migrations from entity definitions
* How to work with custom fields (e.g., media custom fields)

Use migrations for schema changes and structural updates. Use custom fields to extend existing entities without modifying the core schema.

---

---
url: /docs/v6.5/guides/hosting/infrastructure/database-cluster.md
---

# Database Cluster

::: info
This functionality is available starting with Shopware 6.4.12.0.
:::

To scale Shopware even further, we recommend using a database cluster. A database cluster consists of multiple read-only servers managed by a single primary instance.

Shopware already splits read and write SQL queries by default. When a write  [`INSERT`/`UPDATE`/`DELETE`/...](https://github.com/shopware/shopware/blob/v6.4.11.1/src/Core/Profiling/Doctrine/DebugStack.php#L48) query is executed, the query is delegated to the primary server, and the current connection uses only the primary node for subsequent calls. This is ensured by the `executeStatement` method in the [DebugStack decoration](https://github.com/shopware/shopware/blob/v6.4.11.1/src/Core/Profiling/Doctrine/DebugStack.php#L48).
That way, Shopware can ensure read-write consistency for records within the same request. However, it doesn't take into account that read-only child nodes might not be in sync with the primary node. This is left to the database replication process.

## Preparing Shopware

We suggest following the steps below to make the splitting the most effective.

### Using the optimal MySQL configuration

By default, Shopware does not set specific MySQL configurations that make sure the database is optimized for Shopware usage.
These variables are set in cluster mode only on the read-only server. To make sure that Shopware works flawlessly, these configurations must be configured directly on the MySQL server so these variables are set on any server.

The following options should be set:

* Make sure that `group_concat_max_len` is by default higher or equal to `320000`
* Make sure that `sql_mode` doesn't contain `ONLY_FULL_GROUP_BY`

After this change, you can set also `SQL_SET_DEFAULT_SESSION_VARIABLES=0` in the `.env` file so Shopware does not check for those variables at runtime.

### Cart in Redis

As we learned in the beginning, Shopware queries a read-only MySQL server until the first write attempt. To maximize this behavior, it is highly recommended to outsource as many write operations as possible from the database. One of the easiest solutions is to use the Redis as storage for store carts.
To use Redis, add the following snippet to `config/packages/cart.yml`

```yaml
shopware:
    cart:
        redis_url: 'redis://localhost:6379/0?persistent=1'
```

It is recommended to use a persistent Redis connection to avoid connection issues in high-load scenarios. There is also a `cart:migrate` command to migrate the existing carts between MySQL and Redis, so the migration does not influence end-user experience.

## Configure the database cluster

To use the MySQL cluster, you have to configure the following in the `.env` file:

* `DATABASE_URL` is the connection string for the MySQL primary.
* `DATABASE_REPLICA_x_URL` (e.g `DATABASE_REPLICA_0_URL`, `DATABASE_REPLICA_1_URL`) - is the connection string for the MySQL read-only server.

---

---
url: /docs/v6.6/guides/hosting/infrastructure/database-cluster.md
---

# Database Cluster

::: info
This functionality is available starting with Shopware 6.4.12.0.
:::

To scale Shopware even further, we recommend using a database cluster. A database cluster consists of multiple read-only servers managed by a single primary instance.

Shopware already splits read and write SQL queries by default. When a write  [`INSERT`/`UPDATE`/`DELETE`/...](https://github.com/shopware/shopware/blob/v6.4.11.1/src/Core/Profiling/Doctrine/DebugStack.php#L48) query is executed, the query is delegated to the primary server, and the current connection uses only the primary node for subsequent calls. This is ensured by the `executeStatement` method in the [DebugStack decoration](https://github.com/shopware/shopware/blob/v6.4.11.1/src/Core/Profiling/Doctrine/DebugStack.php#L48).
That way, Shopware can ensure read-write consistency for records within the same request. However, it doesn't take into account that read-only child nodes might not be in sync with the primary node. This is left to the database replication process.

## Preparing Shopware

We suggest following the steps below to make the splitting the most effective.

### Using the optimal MySQL configuration

By default, Shopware does not set specific MySQL configurations that make sure the database is optimized for Shopware usage.
These variables are set in cluster mode only on the read-only server. To make sure that Shopware works flawlessly, these configurations must be configured directly on the MySQL server so these variables are set on any server.

The following options should be set:

* Make sure that `group_concat_max_len` is by default higher or equal to `320000`
* Make sure that `sql_mode` doesn't contain `ONLY_FULL_GROUP_BY`

After this change, you can set also `SQL_SET_DEFAULT_SESSION_VARIABLES=0` in the `.env` file so Shopware does not check for those variables at runtime.

### Cart in Redis

As we learned in the beginning, Shopware queries a read-only MySQL server until the first write attempt. To maximize this behavior, it is highly recommended to outsource as many write operations as possible from the database. One of the easiest solutions is to use the Redis as storage for store carts.
To use Redis, add the following snippet to `config/packages/cart.yml`

```yaml
shopware:
    cart:
        redis_url: 'redis://localhost:6379/0?persistent=1'
```

It is recommended to use a persistent Redis connection to avoid connection issues in high-load scenarios. There is also a `cart:migrate` command to migrate the existing carts between MySQL and Redis, so the migration does not influence end-user experience.

For a detailed explanation refer to the cart storage docs:


## Configure the database cluster

To use the MySQL cluster, you have to configure the following in the `.env` file:

* `DATABASE_URL` is the connection string for the MySQL primary.
* `DATABASE_REPLICA_x_URL` (e.g `DATABASE_REPLICA_0_URL`, `DATABASE_REPLICA_1_URL`) - is the connection string for the MySQL read-only server.

---

---
url: /docs/guides/plugins/plugins/database/database-migrations.md
---

# Database Migrations

Migrations are PHP classes used to manage incremental database schema changes. Shopware comes with a pre-built migration system to take away most of the work for you. Throughout this guide, you will find the `$` symbol representing your command line.

## Prerequisites

To add your own database migrations for your plugin, you first need a plugin as a base. Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide.md).

::: info
Refer to this video on **[Database migrations](https://www.youtube.com/watch?v=__pWwaK6lxw)**. Also, available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

## File structure

By default, Shopware 6 is looking for migration files in a directory called `Migration` relative to your plugin's base class.

```text
└── plugins
    └── SwagBasicExample
        └── src
            ├── Migration
            │   └── Migration1546422281ExampleDescription.php
            └── SwagBasicExample.php
```

As you can see, there is one file in the `<plugin root>/src/Migration` directory. Below you'll find a breakdown of what each part of its name means.

| File Name Snippet  | Meaning                                         |
|:-------------------|:------------------------------------------------|
| Migration          | Each migration file has to start with Migration |
| 1546422281         | A Timestamp used to make migrations incremental |
| ExampleDescription | A descriptive name for your migration           |

## Generate migration skeleton

To generate the boilerplate code for your migration, you have to open your Shopware root directory in your terminal and execute the command `database:create-migration`. Below you can see the command used in this example to create the migration seen above in the file structure.

```bash
$ ./bin/console database:create-migration -p SwagBasicExample --name ExampleDescription
```

Below you'll find a breakdown of the command.

| Command Snippet                | Meaning                                                          |
|:-------------------------------|:-----------------------------------------------------------------|
| ./bin/console                  | Calls the executable Symfony console application                 |
| database:create-migration      | The command to create a new migration                            |
| -p your\_plugin\_name          | -p creates a new migration for the plugin with the name provided |
| --name your\_descriptive\_name | Appends the provided string after the timestamp                  |

*Note: If you create a new migration yourself, the timestamp will vary.*

If you take a look at your created migration, it should look similar to this:

```php
// <plugin root>/src/Migration/Migration1611740369ExampleDescription.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Framework\Migration\MigrationStep;

/**
 * @internal
 */
class Migration1611740369ExampleDescription extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1611740369;
    }

    public function update(Connection $connection): void
    {
        // implement update
    }
}
```

As you can see, your migration contains two methods:

* `getCreationTimestamp()`
* `update()`

There is no need to change `getCreationTimestamp()`, it returns the timestamp that's also part of the file name. Implement **all** schema and data changes for the plugin in `update()`. That method is what Shopware runs automatically when the plugin is installed or updated.

::: info
There is no migration rollback. You do not add instructions to reverse your migrations inside the migration class. Cleaning up the database when the plugin is removed belongs in the plugin lifecycle method `uninstall`, as explained in the [Plugin Lifecycle guide](../plugin-fundamentals/plugin-lifecycle.md#uninstall).
:::

::: warning
`MigrationStep` also defines an optional `updateDestructive()` method. Shopware core uses it for delayed, major-version destructive changes. **Plugin install and update never run `updateDestructive()`.** In practice, merchants and platforms also do not run `database:migrate-destructive` for plugins. Put every change your plugin needs into `update()`, and handle uninstall cleanup in `uninstall()`.
:::

Here's an example of a migration creating a new table:

```php
// <plugin root>/src/Migration/Migration1611740369ExampleDescription.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Framework\Migration\MigrationStep;

/**
 * @internal
 */
class Migration1611740369ExampleDescription extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1611740369;
    }

    public function update(Connection $connection): void
    {
        $query = <<<SQL
CREATE TABLE IF NOT EXISTS `swag_basic_example_general_settings` (
    `id`                INT             NOT NULL,
    `example_setting`   VARCHAR(255)    NOT NULL,
    PRIMARY KEY (id)
)
    ENGINE = InnoDB
    DEFAULT CHARSET = utf8mb4
    COLLATE = utf8mb4_unicode_ci;
SQL;

        $connection->executeStatement($query);
    }
}
```

## Generating a complete migration for an entity

Shopware can also generate the complete migration, including the SQL statements for you, based on the entity definitions.

```bash
$ ./bin/console dal:migration:create --bundle=SwagBasicExample --entities=your_entity,your_other_entity
```

This command will generate a new migration file including the `CREATE TABLE` or `ALTER TABLE` statements to get the DB schema into a state that matches the entity definitions.

| Option     | Meaning                                                                                                              |
|:-----------|:---------------------------------------------------------------------------------------------------------------------|
| --bundle   | The name of the plugin, when not provided the command will generate a migration in the core                          |
| --entities | Comma-separated list of the entities it should create migrations for; it will generate one migration file per entity |

*Note: Your plugin has to be activated, otherwise your custom entity definition cannot be found.*

## Execute migration

When you install your plugin, the migration directory is added to a MigrationCollection and all migrations' `update()` methods are executed. Also, when you update a plugin via the Plugin Manager, all **new** migrations are executed the same way. If you want to perform a migration manually as part of your development process, simply create it after installing your plugin. This way, your plugin migration directory will already be registered during the installation process and you can run any newly created migration by hand:

```bash
$ ./bin/console database:migrate SwagBasicExample --all
```

::: warning
When updating a plugin, do not change a migration that was already executed, since every migration is only run once.
:::

| Command          | Arguments               | Usage                                                |
|:-----------------|:------------------------|:-----------------------------------------------------|
| database:migrate | identifier (optional) | Calls the `update()` methods of unhandled migrations |

The identifier argument decides which migrations should be executed. Per default, the identifier is set to run Shopware Core migrations. To run your plugin migrations, set the identifier argument to your plugin's bundle name, in this example `SwagBasicExample`.

## Advanced migration control

Once you have become familiar with the migration process and the development flow, you may want to have finer control over the migrations performed during the installation and update. In this case the `MigrationCollection` which is only filled with your specific migrations, can be accessed via the `InstallContext` and all its subclasses (`UpdateContext`, `ActivateContext`, ...). A plugin must reject the automatic execution of migrations in order to have control over the migrations that are executed.

Therefore, a typical update method might look more like this:

```php
    public function update(UpdateContext $updateContext): void
    {
        $updateContext->setAutoMigrate(false); // disable auto migration execution

        $migrationCollection = $updateContext->getMigrationCollection();

        // execute all UPDATE migrations until and including 2019-12-12T09:30:51+00:00
        $migrationCollection->migrateInPlace(1576143014);
    }
```

If you don't use the Shopware migration system, an empty collection (`NullObject`) will be in the context.

### Customizing the migration path / namespace

Most plugins should keep the default `src/Migration` directory — the tooling and examples in this guide assume it. If you have a specific reason to relocate your migrations, you can choose another namespace for them by overwriting your plugin's `getMigrationNamespace()` method in the plugin base class:

```php
public function getMigrationNamespace(): string
{
    return 'Swag\BasicExample\MyMigrationNamespace';
}
```

Since the path is read from the namespace, your Migration directory would have to be named `MyMigrationNamespace` now.

---

---
url: /docs/v6.5/guides/plugins/plugins/plugin-fundamentals/database-migrations.md
---

# Database Migrations

## Overview

In this guide, you'll learn what migrations are and how to use them. Migrations are PHP classes used to manage incremental and reversible database schema changes. Shopware comes with a pre-built Migration System, to take away most of the work for you. Throughout this guide, you will find the `$` symbol representing your command line.

## Prerequisites

In order to add your own database migrations for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide).

::: info
Refer to this video on **[Database migrations](https://www.youtube.com/watch?v=__pWwaK6lxw)**. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

## File structure

By default, Shopware 6 is looking for migration files in a directory called `Migration` relative to your plugin's base class.

```text
└── plugins
    └── SwagBasicExample
        └── src
            ├── Migration
            │   └── Migration1546422281ExampleDescription.php
            └── SwagBasicExample.php
```

As you can see there is one file in the `<plugin root>/src/Migration` directory. Below you find a break down of what each part of its name means.

| File Name Snippet | Meaning |
| :--- | :--- |
| Migration | Each migration file has to start with Migration |
| 1546422281 | A Timestamp used to make migrations incremental |
| ExampleDescription | A descriptive name for your migration |

### Customizing the migration path / namespace

You are also able to change the migration directory. This is done by choosing another namespace for your migrations, which can be changed by overwriting your plugin's `getMigrationNamespace()` method in the plugin base class:

```php
public function getMigrationNamespace(): string
{
    return 'Swag\BasicExample\MyMigrationNamespace';
}
```

Since the path is read from the namespace, your Migration directory would have to be named `MyMigrationNamespace` now.

## Create migration

To create a new migration, you have to open your Shopware root directory in your terminal and execute the command `database:create-migration`. Below you can see the command used in this example to create the migration seen above in the file structure.

```bash
$ ./bin/console database:create-migration -p SwagBasicExample --name ExampleDescription
```

Below you'll find a break down of the command.

| Command Snippet | Meaning |
| :--- | :--- |
| ./bin/console | Calls the executable Symfony console application |
| database:create-migration | The command to create a new migration |
| -p your\_plugin\_name | -p creates a new migration for the plugin with the name provided |
| --name your\_descriptive\_name | Appends the provided string after the timestamp |

*Note: If you create a new migration yourself, the timestamp will vary.*

If you take a look at your created migration it should look similar to this:

```php
// <plugin root>/src/Migration/Migration1611740369ExampleDescription.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Framework\Migration\MigrationStep;

class Migration1611740369ExampleDescription extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1611740369;
    }

    public function update(Connection $connection): void
    {
        // implement update
    }

    public function updateDestructive(Connection $connection): void
    {
        // implement update destructive
    }
}
```

As you can see your migration contains 3 methods:

* getCreationTimestamp()
* update()
* updateDestructive()

There is no need to change `getCreationTimestamp()`, it returns the timestamp that's also part of the file name. In the `update()` method you implement non-destructive changes which should always be **reversible**. The `updateDestructive()` method is the follow up step, that is run after `update()` and used for **destructive none reversible changes**, like dropping columns or tables. Destructive migrations are only executed explicitly.

::: info
You do not add instructions to revert your migrations within the migration class itself. `updateDestructive` is not meant to revert instructions in `update`. Reverting changes in the database is done explicitly in plugin lifecycle method `uninstall`. Read more about [it here](./plugin-lifecycle#uninstall).
:::

Here's an example of a non-destructive migration, creating a new table:

```php
// <plugin root>/src/Migration/Migration1611740369ExampleDescription.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Framework\Migration\MigrationStep;

class Migration1611740369ExampleDescription extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1611740369;
    }

    public function update(Connection $connection): void
    {
        $query = <<<SQL
CREATE TABLE IF NOT EXISTS `swag_basic_example_general_settings` (
    `id`                INT             NOT NULL,
    `example_setting`   VARCHAR(255)    NOT NULL,
    PRIMARY KEY (id)
)
    ENGINE = InnoDB
    DEFAULT CHARSET = utf8mb4
    COLLATE = utf8mb4_unicode_ci;
SQL;

        $connection->executeStatement($query);
    }

    public function updateDestructive(Connection $connection): void
    {
    }
}
```

## SQL schema

If you want to create a migration for your new custom entity, you could execute the following command. This command selects all active entities and saves it into `platform/src/schema`.

```bash
$ ./bin/console dal:create:schema
```

*Note: Your plugin has to be activated, otherwise your custom entity definition will not be considered. The queries are outputted into /schema.*

## Execute migration

When you install your plugin, the migration directory is added to a MigrationCollection and all migrations are executed. Also, when you update a plugin via the Plugin Manager, all **new** migrations are executed. If you want to perform a migration manually as part of your development process, simply create it after installing your plugin. This way, your plugin migration directory will already be registered during the installation process and you can run any newly created migration by hand using one of the following commands.

::: warning
When updating a plugin, do not change a migration that was already executed, since every migration is only run once.
:::

| Command | Arguments | Usage |
| :--- | :--- | :--- |
| database:migrate | identifier (optional) | Calls the update() methods of unhandled migrations |
| database:migrate-destructive | identifier (optional) | Calls the updateDestructive() methods of unhandled migrations |

The identifier argument is used to decide which migrations should be executed. Per default, the identifier is set to run Shopware Core migrations. To run your plugin migrations, set the identifier argument to your plugin's bundle name, in this example `SwagBasicExample`.

```bash
$ ./bin/console database:migrate SwagBasicExample --all
```

## Advanced migration control

Once you have become familiar with the migration process and the development flow, you may want to have finer control over the migrations performed during the installation and update. In this case the `MigrationCollection` which is only filled with your specific migrations, can be accessed via the `InstallContext` and all its subclasses (UpdateContext, ActivateContext, ...). A plugin must reject the automatic execution of migrations in order to have control over the migrations that are executed.

Therefore a typical update method might look more like this:

```php
    public function update(UpdateContext $updateContext): void
    {
        $updateContext->setAutoMigrate(false); // disable auto migration execution

        $migrationCollection = $updateContext->getMigrationCollection();

        // execute all DESTRUCTIVE migrations until and including 2019-11-01T00:00:00+00:00
        $migrationCollection->migrateDestructiveInPlace(1572566400);

        // execute all UPDATE migrations until and including 2019-12-12T09:30:51+00:00
        $migrationCollection->migrateInPlace(1576143014);
    }
```

If you don't use the Shopware migration system, an empty collection (NullObject) will be in the context.

---

---
url: /docs/v6.6/guides/plugins/plugins/plugin-fundamentals/database-migrations.md
---

# Database Migrations

## Overview

In this guide, you'll learn what migrations are and how to use them. Migrations are PHP classes used to manage incremental and reversible database schema changes. Shopware comes with a pre-built Migration System, to take away most of the work for you. Throughout this guide, you will find the `$` symbol representing your command line.

## Prerequisites

In order to add your own database migrations for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide).

::: info
Refer to this video on **[Database migrations](https://www.youtube.com/watch?v=__pWwaK6lxw)**. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma).
:::

## File structure

By default, Shopware 6 is looking for migration files in a directory called `Migration` relative to your plugin's base class.

```text
└── plugins
    └── SwagBasicExample
        └── src
            ├── Migration
            │   └── Migration1546422281ExampleDescription.php
            └── SwagBasicExample.php
```

As you can see there is one file in the `<plugin root>/src/Migration` directory. Below you find a break down of what each part of its name means.

| File Name Snippet | Meaning |
| :--- | :--- |
| Migration | Each migration file has to start with Migration |
| 1546422281 | A Timestamp used to make migrations incremental |
| ExampleDescription | A descriptive name for your migration |

### Customizing the migration path / namespace

You are also able to change the migration directory. This is done by choosing another namespace for your migrations, which can be changed by overwriting your plugin's `getMigrationNamespace()` method in the plugin base class:

```php
public function getMigrationNamespace(): string
{
    return 'Swag\BasicExample\MyMigrationNamespace';
}
```

Since the path is read from the namespace, your Migration directory would have to be named `MyMigrationNamespace` now.

## Create migration

To create a new migration, you have to open your Shopware root directory in your terminal and execute the command `database:create-migration`. Below you can see the command used in this example to create the migration seen above in the file structure.

```bash
$ ./bin/console database:create-migration -p SwagBasicExample --name ExampleDescription
```

Below you'll find a break down of the command.

| Command Snippet | Meaning |
| :--- | :--- |
| ./bin/console | Calls the executable Symfony console application |
| database:create-migration | The command to create a new migration |
| -p your\_plugin\_name | -p creates a new migration for the plugin with the name provided |
| --name your\_descriptive\_name | Appends the provided string after the timestamp |

*Note: If you create a new migration yourself, the timestamp will vary.*

If you take a look at your created migration it should look similar to this:

```php
// <plugin root>/src/Migration/Migration1611740369ExampleDescription.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Framework\Migration\MigrationStep;

class Migration1611740369ExampleDescription extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1611740369;
    }

    public function update(Connection $connection): void
    {
        // implement update
    }

    public function updateDestructive(Connection $connection): void
    {
        // implement update destructive
    }
}
```

As you can see your migration contains 3 methods:

* getCreationTimestamp()
* update()
* updateDestructive()

There is no need to change `getCreationTimestamp()`, it returns the timestamp that's also part of the file name. In the `update()` method you implement non-destructive changes which should always be **reversible**. The `updateDestructive()` method is the follow up step, that is run after `update()` and used for **destructive none reversible changes**, like dropping columns or tables. Destructive migrations are only executed explicitly.

::: info
You do not add instructions to revert your migrations within the migration class itself. `updateDestructive` is not meant to revert instructions in `update`. Reverting changes in the database is done explicitly in plugin lifecycle method `uninstall`. Read more about [it here](./plugin-lifecycle#uninstall).
:::

Here's an example of a non-destructive migration, creating a new table:

```php
// <plugin root>/src/Migration/Migration1611740369ExampleDescription.php
<?php declare(strict_types=1);

namespace Swag\BasicExample\Migration;

use Doctrine\DBAL\Connection;
use Shopware\Core\Framework\Migration\MigrationStep;

class Migration1611740369ExampleDescription extends MigrationStep
{
    public function getCreationTimestamp(): int
    {
        return 1611740369;
    }

    public function update(Connection $connection): void
    {
        $query = <<<SQL
CREATE TABLE IF NOT EXISTS `swag_basic_example_general_settings` (
    `id`                INT             NOT NULL,
    `example_setting`   VARCHAR(255)    NOT NULL,
    PRIMARY KEY (id)
)
    ENGINE = InnoDB
    DEFAULT CHARSET = utf8mb4
    COLLATE = utf8mb4_unicode_ci;
SQL;

        $connection->executeStatement($query);
    }

    public function updateDestructive(Connection $connection): void
    {
    }
}
```

## SQL schema

If you want to create a migration for your new custom entity, you could execute the following command. This command selects all active entities and saves it into `platform/src/schema`.

```bash
$ ./bin/console dal:create:schema
```

*Note: Your plugin has to be activated, otherwise your custom entity definition will not be considered. The queries are outputted into /schema.*

## Execute migration

When you install your plugin, the migration directory is added to a MigrationCollection and all migrations are executed. Also, when you update a plugin via the Plugin Manager, all **new** migrations are executed. If you want to perform a migration manually as part of your development process, simply create it after installing your plugin. This way, your plugin migration directory will already be registered during the installation process and you can run any newly created migration by hand using one of the following commands.

::: warning
When updating a plugin, do not change a migration that was already executed, since every migration is only run once.
:::

| Command | Arguments | Usage |
| :--- | :--- | :--- |
| database:migrate | identifier (optional) | Calls the update() methods of unhandled migrations |
| database:migrate-destructive | identifier (optional) | Calls the updateDestructive() methods of unhandled migrations |

The identifier argument is used to decide which migrations should be executed. Per default, the identifier is set to run Shopware Core migrations. To run your plugin migrations, set the identifier argument to your plugin's bundle name, in this example `SwagBasicExample`.

```bash
$ ./bin/console database:migrate SwagBasicExample --all
```

## Advanced migration control

Once you have become familiar with the migration process and the development flow, you may want to have finer control over the migrations performed during the installation and update. In this case the `MigrationCollection` which is only filled with your specific migrations, can be accessed via the `InstallContext` and all its subclasses (UpdateContext, ActivateContext, ...). A plugin must reject the automatic execution of migrations in order to have control over the migrations that are executed.

Therefore a typical update method might look more like this:

```php
    public function update(UpdateContext $updateContext): void
    {
        $updateContext->setAutoMigrate(false); // disable auto migration execution

        $migrationCollection = $updateContext->getMigrationCollection();

        // execute all DESTRUCTIVE migrations until and including 2019-11-01T00:00:00+00:00
        $migrationCollection->migrateDestructiveInPlace(1572566400);

        // execute all UPDATE migrations until and including 2019-12-12T09:30:51+00:00
        $migrationCollection->migrateInPlace(1576143014);
    }
```

If you don't use the Shopware migration system, an empty collection (NullObject) will be in the context.

---

---
url: /docs/products/paas/shopware/resources/databases.md
---

# Databases

## Introduction

Shopware PaaS Native provides a managed MySQL cluster for each application created where we handle: automatic backups and recovery, high availability, performance monitoring and metrics, resource scaling (CPU, RAM, storage), automatic encryption of data at rest and in transit.

## Connecting to Database Cluster

To connect to your database via CLI:

```sh
sw-paas open service --service database --port 3306
```

Database access is provided through the CLI tunnel. Direct public database exposure is not supported.

### Note

Please check the [known issues](../known-issues.md) regarding network considerations when running this command.

---

---
url: >-
  /docs/products/extensions/migration-assistant/concept/dataselection-and-dataset.md
---

# DataSelection and DataSet

These are the fundamental data structures for defining what to migrate. Each `DataSelection` consists of one or more `DataSets`:

* ProductDataSelection (position: 100)
  * MediaFolderDataSet
  * ProductAttributeDataSet
  * ProductPriceAttributeDataSet
  * ManufacturerAttributeDataSet
  * ProductDataSet
  * PropertyGroupOptionDataSet
  * ProductOptionRelationDataSet
  * ProductPropertyRelationDataSet
  * TranslationDataSet
  * CrossSellingDataSet
* MediaDataSelection (position: 300)
  * MediaFolderDataSet
  * MediaDataSet

The order of the `DataSets` in the `DataSelection` class is important and specifies the processing order. `DataSelection` also holds a position specifying the order applied when migrating (lower numbers are migrated earlier). The `getDataSetsRequiredForCount()` method returns an array of all `DataSets`. Its count should be displayed in the Administration.

Please take a look at the `DataSelection` example:

```php
// SwagMigrationAssistant\Profile\Shopware\DataSelection\ProductDataSelection

class ProductDataSelection implements DataSelectionInterface
{
    public const IDENTIFIER = 'products';

    public function supports(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof ShopwareProfileInterface;
    }

    public function getData(): DataSelectionStruct
    {
        return new DataSelectionStruct(
            self::IDENTIFIER,
            $this->getDataSets(),
            $this->getDataSetsRequiredForCount(),
            'swag-migration.index.selectDataCard.dataSelection.products', // Snippet name
            100, // The position of the dataSelection
            true, // Is process-media needed (to download / copy images for example),
            DataSelectionStruct::BASIC_DATA_TYPE, // specify the type of data (core data or plugin data)
            false // Is the selection required for every migration? (the user can't unselect this data selection)
        );
    }

    public function getDataSets(): array
    {
        return [
            // The order matters!
            new MediaFolderDataSet(),
            new ProductAttributeDataSet(),
            new ProductPriceAttributeDataSet(),
            new ManufacturerAttributeDataSet(),
            new ProductDataSet(),
            new PropertyGroupOptionDataSet(),
            new ProductOptionRelationDataSet(),
            new ProductPropertyRelationDataSet(),
            new TranslationDataSet(),
            new CrossSellingDataSet(),
            new MainVariantRelationDataSet(),
        ];
    }

    public function getDataSetsRequiredForCount(): array
    {
        return [
            new ProductDataSet(),
        ];
    }
}
```

Here's a `DataSet` example:

```php
// SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ProductDataSet

class ProductDataSet extends DataSet
{
    public static function getEntity(): string
    {
        return DefaultEntities::PRODUCT;
    }

    public function supports(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof ShopwareProfileInterface;
    }
}
```

The `DataSelections` are registered the following way:

```php
$services->set(ProductDataSelection::class)
    ->tag('shopware.migration.data_selection');
```

It is also possible to specify the same `DataSets` in multiple `DataSelections` (this should only be done if no other options are available). Have a look at the `ProductReviewDataSelection`:

::: info
There are duplicate `DataSets` from `ProductDataSelection`, because they are also required if the user does not select the product `DataSelection`. If the user selects both, these `DataSets` are only migrated once (with their first occurrence).
:::

```php
// SwagMigrationAssistant\Profile\Shopware\DataSelection\ProductReviewDataSelection

class ProductReviewDataSelection implements DataSelectionInterface
{
    public const IDENTIFIER = 'productReviews';

    // ...

    public function getDataSets(): array
    {
        return [
            new MediaFolderDataSet(),
            new ProductAttributeDataSet(),
            new ProductPriceAttributeDataSet(),
            new ManufacturerAttributeDataSet(),
            new ProductDataSet(),
            new PropertyGroupOptionDataSet(),
            new ProductOptionRelationDataSet(),
            new ProductPropertyRelationDataSet(),
            new TranslationDataSet(),
            new CrossSellingDataSet(),
            new CustomerAttributeDataSet(),
            new CustomerDataSet(),
            new ProductReviewDataSet(),
        ];
    }
}
```

---

---
url: >-
  /docs/v6.5/products/extensions/migration-assistant/concept/dataselection-and-dataset.md
---

# DataSelection and DataSet

These are the fundamental data structures for defining what to migrate. Each `DataSelection` consists of one or more `DataSets`:

* ProductDataSelection (position: 100)
  * MediaFolderDataSet
  * ProductAttributeDataSet
  * ProductPriceAttributeDataSet
  * ManufacturerAttributeDataSet
  * ProductDataSet
  * PropertyGroupOptionDataSet
  * ProductOptionRelationDataSet
  * ProductPropertyRelationDataSet
  * TranslationDataSet
  * CrossSellingDataSet
* MediaDataSelection (position: 300)
  * MediaFolderDataSet
  * MediaDataSet

The order of the `DataSets` in the `DataSelection` class is important and specifies the processing order. `DataSelection` also holds a position specifying the order applied when migrating (lower numbers are migrated earlier). The `getDataSetsRequiredForCount` method returns an array of all DataSets. Its count should be displayed in the Administration.

Please take a look at the `DataSelection` example:

```php
<?php declare(strict_types=1);

namespace SwagMigrationAssistant\Profile\Shopware\DataSelection;

use SwagMigrationAssistant\Migration\DataSelection\DataSelectionInterface;
use SwagMigrationAssistant\Migration\DataSelection\DataSelectionStruct;
use SwagMigrationAssistant\Migration\MigrationContextInterface;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\CrossSellingDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ManufacturerAttributeDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\MediaFolderDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ProductAttributeDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ProductDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ProductOptionRelationDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ProductPriceAttributeDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ProductPropertyRelationDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\PropertyGroupOptionDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\TranslationDataSet;
use SwagMigrationAssistant\Profile\Shopware\ShopwareProfileInterface;

class ProductDataSelection implements DataSelectionInterface
{
    public const IDENTIFIER = 'products';

    public function supports(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof ShopwareProfileInterface;
    }

    public function getData(): DataSelectionStruct
    {
        return new DataSelectionStruct(
            self::IDENTIFIER,
            $this->getDataSets(),
            $this->getDataSetsRequiredForCount(),
            'swag-migration.index.selectDataCard.dataSelection.products', // Snippet name
            100, // The position of the dataSelection
            true, // Is process-media needed (to download / copy images for example),
            DataSelectionStruct::BASIC_DATA_TYPE, // specify the type of data (core data or plugin data)
            false // Is the selection required for every migration? (the user can't unselect this data selection)
        );
    }

    public function getDataSets(): array
    {
        return [
            // The order matters!
            new MediaFolderDataSet(),
            new ProductAttributeDataSet(),
            new ProductPriceAttributeDataSet(),
            new ManufacturerAttributeDataSet(),
            new ProductDataSet(),
            new PropertyGroupOptionDataSet(),
            new ProductOptionRelationDataSet(),
            new ProductPropertyRelationDataSet(),
            new TranslationDataSet(),
            new CrossSellingDataSet(),
        ];
    }

    public function getDataSetsRequiredForCount(): array
    {
        return [
            new ProductDataSet(),
        ];
    }
}
```

Here's a `DataSet` example:

```php
<?php declare(strict_types=1);

namespace SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet;

use SwagMigrationAssistant\Migration\DataSelection\DataSet\DataSet;
use SwagMigrationAssistant\Migration\DataSelection\DefaultEntities;
use SwagMigrationAssistant\Migration\MigrationContextInterface;
use SwagMigrationAssistant\Profile\Shopware\ShopwareProfileInterface;

class ProductDataSet extends DataSet
{
    public static function getEntity(): string
    {
        return DefaultEntities::PRODUCT;
    }

    public function supports(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof ShopwareProfileInterface;
    }
}
```

The `dataSelections` are registered the following way:

```html
<service id="SwagMigrationAssistant\Profile\Shopware\DataSelection\ProductDataSelection">
    <tag name="shopware.migration.data_selection"/>
</service>
```

It is also possible to specify the same `DataSets` in multiple `DataSelections` (this should only be done if no other options are available). Have a look at the `ProductReviewDataSelection`:

```php
<?php declare(strict_types=1);

namespace SwagMigrationAssistant\Profile\Shopware\DataSelection;

use SwagMigrationAssistant\Migration\DataSelection\DataSelectionInterface;
use SwagMigrationAssistant\Migration\DataSelection\DataSelectionStruct;
use SwagMigrationAssistant\Migration\MigrationContextInterface;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\CrossSellingDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\CustomerAttributeDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\CustomerDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ManufacturerAttributeDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\MediaFolderDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ProductAttributeDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ProductDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ProductOptionRelationDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ProductPriceAttributeDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ProductPropertyRelationDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ProductReviewDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\PropertyGroupOptionDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\TranslationDataSet;
use SwagMigrationAssistant\Profile\Shopware\ShopwareProfileInterface;

class ProductReviewDataSelection implements DataSelectionInterface
{
    public const IDENTIFIER = 'productReviews';

    public function supports(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof ShopwareProfileInterface;
    }

    public function getData(): DataSelectionStruct
    {
        return new DataSelectionStruct(
            self::IDENTIFIER,
            $this->getDataSets(),
            $this->getDataSetsRequiredForCount(),
            'swag-migration.index.selectDataCard.dataSelection.productReviews',
            250,
            true
        );
    }

    /**
     * {@inheritdoc}
     */
    public function getDataSets(): array
    {
        return [
            new MediaFolderDataSet(),
            new ProductAttributeDataSet(),
            new ProductPriceAttributeDataSet(),
            new ManufacturerAttributeDataSet(),
            new ProductDataSet(),
            new PropertyGroupOptionDataSet(),
            new ProductOptionRelationDataSet(),
            new ProductPropertyRelationDataSet(),
            new TranslationDataSet(),
            new CrossSellingDataSet(),
            new CustomerAttributeDataSet(),
            new CustomerDataSet(),
            new ProductReviewDataSet(),
        ];
    }

    public function getDataSetsRequiredForCount(): array
    {
        return [
            new ProductReviewDataSet(),
        ];
    }
}
```

::: info
There are duplicate DataSets from the `ProductDataSelection`, because they are also required if the user does not select the product `DataSelection`. If the user selects both, this `DataSets` will be only migrated once (with their first occurrence).
:::

---

---
url: >-
  /docs/v6.6/products/extensions/migration-assistant/concept/dataselection-and-dataset.md
---

# DataSelection and DataSet

These are the fundamental data structures for defining what to migrate. Each `DataSelection` consists of one or more `DataSets`:

* ProductDataSelection (position: 100)
  * MediaFolderDataSet
  * ProductAttributeDataSet
  * ProductPriceAttributeDataSet
  * ManufacturerAttributeDataSet
  * ProductDataSet
  * PropertyGroupOptionDataSet
  * ProductOptionRelationDataSet
  * ProductPropertyRelationDataSet
  * TranslationDataSet
  * CrossSellingDataSet
* MediaDataSelection (position: 300)
  * MediaFolderDataSet
  * MediaDataSet

The order of the `DataSets` in the `DataSelection` class is important and specifies the processing order. `DataSelection` also holds a position specifying the order applied when migrating (lower numbers are migrated earlier). The `getDataSetsRequiredForCount` method returns an array of all DataSets. Its count should be displayed in the Administration.

Please take a look at the `DataSelection` example:

```php
<?php declare(strict_types=1);

namespace SwagMigrationAssistant\Profile\Shopware\DataSelection;

use SwagMigrationAssistant\Migration\DataSelection\DataSelectionInterface;
use SwagMigrationAssistant\Migration\DataSelection\DataSelectionStruct;
use SwagMigrationAssistant\Migration\MigrationContextInterface;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\CrossSellingDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ManufacturerAttributeDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\MediaFolderDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ProductAttributeDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ProductDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ProductOptionRelationDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ProductPriceAttributeDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ProductPropertyRelationDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\PropertyGroupOptionDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\TranslationDataSet;
use SwagMigrationAssistant\Profile\Shopware\ShopwareProfileInterface;

class ProductDataSelection implements DataSelectionInterface
{
    public const IDENTIFIER = 'products';

    public function supports(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof ShopwareProfileInterface;
    }

    public function getData(): DataSelectionStruct
    {
        return new DataSelectionStruct(
            self::IDENTIFIER,
            $this->getDataSets(),
            $this->getDataSetsRequiredForCount(),
            'swag-migration.index.selectDataCard.dataSelection.products', // Snippet name
            100, // The position of the dataSelection
            true, // Is process-media needed (to download / copy images for example),
            DataSelectionStruct::BASIC_DATA_TYPE, // specify the type of data (core data or plugin data)
            false // Is the selection required for every migration? (the user can't unselect this data selection)
        );
    }

    public function getDataSets(): array
    {
        return [
            // The order matters!
            new MediaFolderDataSet(),
            new ProductAttributeDataSet(),
            new ProductPriceAttributeDataSet(),
            new ManufacturerAttributeDataSet(),
            new ProductDataSet(),
            new PropertyGroupOptionDataSet(),
            new ProductOptionRelationDataSet(),
            new ProductPropertyRelationDataSet(),
            new TranslationDataSet(),
            new CrossSellingDataSet(),
        ];
    }

    public function getDataSetsRequiredForCount(): array
    {
        return [
            new ProductDataSet(),
        ];
    }
}
```

Here's a `DataSet` example:

```php
<?php declare(strict_types=1);

namespace SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet;

use SwagMigrationAssistant\Migration\DataSelection\DataSet\DataSet;
use SwagMigrationAssistant\Migration\DataSelection\DefaultEntities;
use SwagMigrationAssistant\Migration\MigrationContextInterface;
use SwagMigrationAssistant\Profile\Shopware\ShopwareProfileInterface;

class ProductDataSet extends DataSet
{
    public static function getEntity(): string
    {
        return DefaultEntities::PRODUCT;
    }

    public function supports(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof ShopwareProfileInterface;
    }
}
```

The `dataSelections` are registered the following way:

```html
<service id="SwagMigrationAssistant\Profile\Shopware\DataSelection\ProductDataSelection">
    <tag name="shopware.migration.data_selection"/>
</service>
```

It is also possible to specify the same `DataSets` in multiple `DataSelections` (this should only be done if no other options are available). Have a look at the `ProductReviewDataSelection`:

```php
<?php declare(strict_types=1);

namespace SwagMigrationAssistant\Profile\Shopware\DataSelection;

use SwagMigrationAssistant\Migration\DataSelection\DataSelectionInterface;
use SwagMigrationAssistant\Migration\DataSelection\DataSelectionStruct;
use SwagMigrationAssistant\Migration\MigrationContextInterface;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\CrossSellingDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\CustomerAttributeDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\CustomerDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ManufacturerAttributeDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\MediaFolderDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ProductAttributeDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ProductDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ProductOptionRelationDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ProductPriceAttributeDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ProductPropertyRelationDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\ProductReviewDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\PropertyGroupOptionDataSet;
use SwagMigrationAssistant\Profile\Shopware\DataSelection\DataSet\TranslationDataSet;
use SwagMigrationAssistant\Profile\Shopware\ShopwareProfileInterface;

class ProductReviewDataSelection implements DataSelectionInterface
{
    public const IDENTIFIER = 'productReviews';

    public function supports(MigrationContextInterface $migrationContext): bool
    {
        return $migrationContext->getProfile() instanceof ShopwareProfileInterface;
    }

    public function getData(): DataSelectionStruct
    {
        return new DataSelectionStruct(
            self::IDENTIFIER,
            $this->getDataSets(),
            $this->getDataSetsRequiredForCount(),
            'swag-migration.index.selectDataCard.dataSelection.productReviews',
            250,
            true
        );
    }

    /**
     * {@inheritdoc}
     */
    public function getDataSets(): array
    {
        return [
            new MediaFolderDataSet(),
            new ProductAttributeDataSet(),
            new ProductPriceAttributeDataSet(),
            new ManufacturerAttributeDataSet(),
            new ProductDataSet(),
            new PropertyGroupOptionDataSet(),
            new ProductOptionRelationDataSet(),
            new ProductPropertyRelationDataSet(),
            new TranslationDataSet(),
            new CrossSellingDataSet(),
            new CustomerAttributeDataSet(),
            new CustomerDataSet(),
            new ProductReviewDataSet(),
        ];
    }

    public function getDataSetsRequiredForCount(): array
    {
        return [
            new ProductReviewDataSet(),
        ];
    }
}
```

::: info
There are duplicate DataSets from the `ProductDataSelection`, because they are also required if the user does not select the product `DataSelection`. If the user selects both, this `DataSets` will be only migrated once (with their first occurrence).
:::

---

---
url: /frontends/resources/troubleshooting/CORS.md
---
# Dealing with CORS in Your Project

## Introduction

[SOP](https://developer.mozilla.org/en-US/docs/Web/Security/Same-origin_policy) (Same-Origin Policy) and [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) (Cross-Origin Resource Sharing) are both security mechanisms in web development, but they serve different purposes and work together to control how web pages interact with resources from different origins.

| Feature             | SOP (Same-Origin Policy)                  | CORS (Cross-Origin Resource Sharing)                    |
| ------------------- | ----------------------------------------- | ------------------------------------------------------- |
| Purpose             | Restricts cross-origin requests           | Allows controlled cross-origin requests                 |
| Default Behavior    | Blocks requests between different origins | Allows if explicitly permitted by the server            |
| Enforcement         | Enforced by browsers automatically        | Implemented by servers using HTTP headers               |
| Example Restriction | JavaScript from A.com cannot access B.com | Server B.com can allow access to A.com via CORS headers |

In headless architecture, the frontend and backend are decoupled, and the frontend is hosted on a different domain than the backend. This architecture is common in modern web development, but it can cause issues with SOP and CORS like:

* **Blocked requests**: The browser blocks requests from the frontend to the backend due to SOP.
* **Blocked resources**: The browser blocks resources like fonts, images, and scripts from different origins due to CORS.
* **Blocked cookies**: The browser blocks cookies from different origins due to SOP.
* **Blocked API requests**: The browser blocks API requests from the frontend to the backend due to CORS (preflight requests, OPTIONS requests, sending credentials, custom headers, HTTP methods).

In this guide, you will learn how to deal with CORS issues in your project.

## Headless setup

* Your Nuxt.js frontend is hosted at https://nuxtfrontend.com.
* Your Shopware 6 Store API is hosted at https://shopware.com/store-api.

By default, the browser blocks requests due to SOP (Same-Origin Policy) unless the API explicitly allows it by relaxing the SOP restrictions using CORS.

### Enabling cross-origin requests

To enable cross-origin requests, the server must send the following CORS headers:

* `Access-Control-Allow-Origin`: The origin that is allowed to access the resource.
* `Access-Control-Allow-Methods`: The HTTP methods that are allowed to access the resource.
* `Access-Control-Allow-Headers`: The headers that are allowed to access the resource.

In case of Shopware 6 itself, the API is already configured to allow cross-origin requests from any origin.

The setup can be similar as follows:

| CORS Header                    | Default Configuration                                                                                                                                                | Description                                                                                       |
| ------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `Access-Control-Allow-Origin`  | `*`                                                                                                                                                                  | Allows requests from any origin, though specifying origins explicitly is recommended for security |
| `Access-Control-Allow-Methods` | `GET,POST,PUT,PATCH,DELETE`                                                                                                                                          | HTTP methods permitted for cross-origin requests                                                  |
| `Access-Control-Allow-Headers` | `Content-Type,Authorization,sw-context-token,sw-access-key,sw-language-id,sw-version-id,sw-inheritance,indexing-behavior,sw-include-seo-urls,sw-context-token-alias` | Headers that can be used in requests to the API                                                   |

As we can see, the Shopware 6 API allows cross-origin requests from any origin, also any method and the set of Shopware specific headers, like `sw-context-token` and `sw-access-key` - both known from [API Client](https://www.npmjs.com/package/@shopware/api-client#:~:text=Store%20API%20client%20setup) setup.

That enables the frontend project to communicate with the Shopware 6 API without any additional configuration for CORS.

## CORS issues

### Preflight OPTIONS requests

A browser knows that requests used to communicate between frontend app and Shopware 6 API aren't [simple](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS#simple_requests). Thus There is no way to avoid such requests in the browser due to additional headers or credentials needed by Shopware 6 API. To work around this see the next section.

### Any other problem

Eliminate the browser's CORS restrictions by using a server-side proxy or a custom API middleware (don't do any requests in the browser side):

* **If you control the backend:** Use **Reverse Proxy (NGINX)** or **update Shopware's CORS settings**.
* **If it's a SaaS API:** Use **Nuxt SSR** (don't load any external data in the browser) or **a custom API middleware**.
* **For best performance:** Avoid CORS entirely by using **server-side proxying**.

## 🔹 Best Practice Summary

| Solution                     | CORS-Free? | Performance | Setup Effort | When to Use?                         |
| ---------------------------- | ---------- | ----------- | ------------ | ------------------------------------ |
| **Reverse Proxy (NGINX)**    | ✅ Yes     | 🚀 Fast     | 🔧 Medium    | Self-hosted, best performance        |
| **Nuxt SSR Mode**            | ✅ Yes     | ⚡ Fast     | 🛠 Easy       | Works for APIs without CORS settings |
| **Modify Shopware API CORS** | ❌ No      | 🚀 Fast     | 🛠 Easy       | When you control the API             |
| **Custom API Middleware**    | ✅ Yes     | 🐢 Slower   | 🛠 Hard       | When API CORS cannot be changed      |

---

---
url: /docs/guides/hosting/infrastructure/elasticsearch/elasticsearch-debugging.md
---

# Debugging and Troubleshooting Elasticsearch

## Overview

This guide shows you how to debug the status and indexing process of your Elasticsearch environment. Use this guide when Elasticsearch indexing, aliases, queues, or search results are not behaving as expected.

Ensure that the Debug-Mode is activated in your *.env* file.

## Shopware 6 CLI commands

### Cache clear

`cache:clear` clears the cache

```bash
bin/console cache:clear
```

**> Output:**

```bash
// Clearing the cache for the dev environment with debug
// true
​[OK] Cache for the "dev" environment (debug=true) was successfully cleared.
```

### ES index

`es:index` creates only the index for ES

```bash
bin/console es:index // Creates only the index for ES
```

**> No Output**

### ES create alias

`es:create:alias`  will create an alias linking to the index after `es:index` is done. Normally this is done automatically. In the older version, this has to be done.

```bash
bin/console es:create:alias
```

**> No Output**

### DAL refresh index

`dal:refresh:index --use-queue` creates a complete reindex from the Shopware DAL (ES/SEO/Media/Sitemap...) **ALWAYS** "`--use-queue`" since big request can outperform the server!

```bash
bin/console dal:refresh:index --use-queue
```

**> Output:**

```bash
[landing_page.indexer]
1/1 [============================] 100% < 1 sec/< 1 sec 38.5 MiB
​
[product.indexer]
22/22 [============================] 100% < 1 sec/< 1 sec 40.5 MiB
​
[customer.indexer]
2/2 [============================] 100% < 1 sec/< 1 sec 40.5 MiB
​
[sales_channel.indexer]
2/2 [============================] 100% < 1 sec/< 1 sec 40.5 MiB
​
[category.indexer]
9/9 [============================] 100% < 1 sec/< 1 sec 40.5 MiB
​
[...]
```

### Messenger consume

`messenger:consume -vv` starts a message consumer working on all tasks. This could be started *X* times. When using more than 3 message consumers, you will need something like RabbitMq to handle the data.

```bash
bin/console messenger:consume -vv
```

**> Output:**

```bash
[OK] Consuming messages from transports "default".
​​
// The worker will automatically exit once it has received a stop signal via the messenger:stop-workers command.
​
// Quit the worker with CONTROL-C.
​
09:47:28 INFO      [messenger] Received message Shopware\Elasticsearch\Framework\Indexing\ElasticsearchIndexingMessage ["message" => Shopware\Elasticsearch\Framework\Indexing\ElasticsearchIndexingMessage^ { …},"class" => "Shopware\Elasticsearch\Framework\Indexing\ElasticsearchIndexingMessage"]
​
[...]
```

### Index cleanup

`es:index:cleanup` to remove unused indices, because each indexing will generate a new Elasticsearch index.

```bash
bin/console es:index:cleanup
```

## Helpful Elasticsearch REST APIs

```bash
curl -XGET 'http://elasticsearch:9200/?pretty'
```

**> Output:**

```bash
{
  "name" : "TZzynG6",
  "cluster_name" : "docker-cluster",
  "cluster_uuid" : "tHklOFWPSwm-j8Yn-8PRoQ",
  "version" : {
    "number" : "6.8.1",
    "build_flavor" : "default",
    "build_type" : "docker",
    "build_hash" : "1fad4e1",
    "build_date" : "2019-06-18T13:16:52.517138Z",
    "build_snapshot" : false,
    "lucene_version" : "7.7.0",
    "minimum_wire_compatibility_version" : "5.6.0",
    "minimum_index_compatibility_version" : "5.0.0"
  },
  "tagline" : "You Know, for Search"
}
```

### API for cluster health

Returns the health status of a cluster:

```bash
curl -XGET 'http://elasticsearch:9200/_cluster/health?pretty'
```

**> Output:**

```bash
{
  "cluster_name" : "docker-cluster",
  "status" : "yellow",
  "timed_out" : false,
  "number_of_nodes" : 1,
  "number_of_data_nodes" : 1,
  "active_primary_shards" : 1210,
  "active_shards" : 1210,
  "relocating_shards" : 0,
  "initializing_shards" : 0,
  "unassigned_shards" : 1210,
  "delayed_unassigned_shards" : 0,
  "number_of_pending_tasks" : 0,
  "number_of_in_flight_fetch" : 0,
  "task_max_waiting_in_queue_millis" : 0,
  "active_shards_percent_as_number" : 50.0
}
```

### API for cat indices

Returns high-level information about indices in a cluster, including backing indices for data streams:​

```bash
curl -XGET 'http://elasticsearch:9200/_cat/indices/?pretty'
```

**> Output:**

```bash
yellow open sw1_manufacturer_20210906113224 AYKMT4NJS7eZgU29ww7z6Q 5 1  3 0  33.2kb  33.2kb
yellow open sw1_emotion_20210903165112      he19OP_UR3mMIAKI7ry2mg 5 1  1 0  11.6kb  11.6kb
yellow open sw1_emotion_20210903171353      jBzApKujRPu73CkKA79F7w 5 1  1 0  11.6kb  11.6kb
yellow open sw1_synonym_20210903175037      EexqHsXyTK202XsalUednQ 5 1  1 0     6kb     6kb
yellow open sw1_synonym_20210903170128      NRjlZZ3AQ0Wat1ILB_9L8Q 5 1  0 0   1.2kb   1.2kb
​
[...]
```

### API to delete the index

With `_all` it will delete all indices.

```bash
curl -X DELETE 'elasticsearch:9200/_all'
```

**> Output:**

```bash
{"acknowledged":true}
```

## Show the indexing status in the database

Returns the status of your indexing:

```sql
select * from message_queue_stats mqs ;
select count(*) from enqueue e ;
select count(*) from dead_message dm ;
```

The number of entries in the enqueue should match the sum of the size values in the `message_queue_stats`. As long as there are entries in your `enqueue`, the indexing is in process and your message consumer has to work those messages.

## Reset the indexing in the database

Sometimes you want to reset the indexing in your database because your indexing is stuck or you run into an error.
If the database queue is used, third-party services will differ. You can do so with the following queries.

```sql
truncate enqueue ;
truncate dead_message ;
truncate message_queue_stats ;
update scheduled_task set status = 'scheduled' where status = 'queued';
```

## Completely reset your Elasticsearch and reindex

This is mainly for debugging purposes and is only meant for testing and staging environments.
First, execute the database reset (only working for the database queue):

```sql
truncate enqueue ;
truncate dead_message ;
truncate message_queue_stats ;
update scheduled_task set status = 'scheduled' where status = 'queued';
```

Now delete the old Elasticsearch index, clear your cache, reindex and ensure that the indexing process is finished:

```bash
curl -X DELETE 'elasticsearch:9200/_all'
bin/console cache:clear
bin/console es:index
bin/console messenger:consume -vv
```

After the last message has been processed, your index should be found in your Storefront else execute:

```bash
bin/console es:create:alias
```

## Logfiles and tips

You can usually find the Elasticsearch logfiles at [`/var/log/elasticsearch`](https://www.elastic.co/guide/en/elasticsearch/reference/master/settings.html#_config_file_format) to check for any issues when indexing.
Also, tools like [Kibana](https://www.elastic.co/kibana) or [Cerebro](https://help.profihost.com/hc/de/articles/18918050563729-Cerebro) can help you better understand what is happening in your Elasticsearch.

---

---
url: >-
  /docs/v6.5/guides/hosting/infrastructure/elasticsearch/elasticsearch-debugging.md
---

# Debugging Elasticsearch

## Overview

This article shows you how to debug the status and indexing process of your Elasticsearch environment. Ensure that the [Debug-Mode](./elasticsearch-debugging) is activated in your *.env* file.

## Shopware 6 CLI commands

### Cache clear

`cache:clear` clears the cache

```bash
bin/console cache:clear
```

**> Output:**

```bash
// Clearing the cache for the dev environment with debug
// true
​[OK] Cache for the "dev" environment (debug=true) was successfully cleared.
```

### ES index

`es:index` creates only the index for ES

```bash
bin/console es:index // Creates only the index for ES
```

**> No Output**

### ES create alias

`es:create:alias`  will create an alias linking to the index after `es:index` is done. Normally this is done automatically. In the older version, this has to be done.

```bash
bin/console es:create:alias 
```

**> No Output**

### DAL refresh index

`dal:refresh:index --use-queue` creates a complete reindex from the Shopware DAL (ES/SEO/Media/Sitemap...) **ALWAYS** "`--use-queue`" since big request can outperform the server!

```bash
bin/console dal:refresh:index --use-queue
```

**> Output:**

```bash
[landing_page.indexer]
1/1 [============================] 100% < 1 sec/< 1 sec 38.5 MiB
​
[product.indexer]
22/22 [============================] 100% < 1 sec/< 1 sec 40.5 MiB
​
[customer.indexer]
2/2 [============================] 100% < 1 sec/< 1 sec 40.5 MiB
​
[sales_channel.indexer]
2/2 [============================] 100% < 1 sec/< 1 sec 40.5 MiB
​
[category.indexer]
9/9 [============================] 100% < 1 sec/< 1 sec 40.5 MiB
​
[...]
```

### Messenger consume

`messenger:consume -vv` starts a message consumer working on all tasks. This could be started *X* times. When using more than 3 message consumers, you will need something like RabbitMq to handle the data.

```bash
bin/console messenger:consume -vv
```

**> Output:**

```bash
[OK] Consuming messages from transports "default".
​​
// The worker will automatically exit once it has received a stop signal via the messenger:stop-workers command.
​
// Quit the worker with CONTROL-C.
​
09:47:28 INFO      [messenger] Received message Shopware\Elasticsearch\Framework\Indexing\ElasticsearchIndexingMessage ["message" => Shopware\Elasticsearch\Framework\Indexing\ElasticsearchIndexingMessage^ { …},"class" => "Shopware\Elasticsearch\Framework\Indexing\ElasticsearchIndexingMessage"]
​
[...]
```

### Index cleanup

`es:index:cleanup` to remove unused indices, because each indexing will generate a new Elasticsearch index.

```bash
bin/console es:index:cleanup
```

## Helpful Elasticsearch REST APIs

```bash
curl -XGET 'http://elasticsearch:9200/?pretty'
```

**> Output:**

```bash
{
  "name" : "TZzynG6",
  "cluster_name" : "docker-cluster",
  "cluster_uuid" : "tHklOFWPSwm-j8Yn-8PRoQ",
  "version" : {
    "number" : "6.8.1",
    "build_flavor" : "default",
    "build_type" : "docker",
    "build_hash" : "1fad4e1",
    "build_date" : "2019-06-18T13:16:52.517138Z",
    "build_snapshot" : false,
    "lucene_version" : "7.7.0",
    "minimum_wire_compatibility_version" : "5.6.0",
    "minimum_index_compatibility_version" : "5.0.0"
  },
  "tagline" : "You Know, for Search"
}
```

### API for cluster health

Returns the health status of a cluster:

```bash
curl -XGET 'http://elasticsearch:9200/_cluster/health?pretty'
```

**> Output:**

```bash
{
  "cluster_name" : "docker-cluster",
  "status" : "yellow",
  "timed_out" : false,
  "number_of_nodes" : 1,
  "number_of_data_nodes" : 1,
  "active_primary_shards" : 1210,
  "active_shards" : 1210,
  "relocating_shards" : 0,
  "initializing_shards" : 0,
  "unassigned_shards" : 1210,
  "delayed_unassigned_shards" : 0,
  "number_of_pending_tasks" : 0,
  "number_of_in_flight_fetch" : 0,
  "task_max_waiting_in_queue_millis" : 0,
  "active_shards_percent_as_number" : 50.0
}
```

### API for cat indices

Returns high-level information about indices in a cluster, including backing indices for data streams:​

```bash
curl -XGET 'http://elasticsearch:9200/_cat/indices/?pretty'
```

**> Output:**

```bash
yellow open sw1_manufacturer_20210906113224 AYKMT4NJS7eZgU29ww7z6Q 5 1  3 0  33.2kb  33.2kb
yellow open sw1_emotion_20210903165112      he19OP_UR3mMIAKI7ry2mg 5 1  1 0  11.6kb  11.6kb
yellow open sw1_emotion_20210903171353      jBzApKujRPu73CkKA79F7w 5 1  1 0  11.6kb  11.6kb
yellow open sw1_synonym_20210903175037      EexqHsXyTK202XsalUednQ 5 1  1 0     6kb     6kb
yellow open sw1_synonym_20210903170128      NRjlZZ3AQ0Wat1ILB_9L8Q 5 1  0 0   1.2kb   1.2kb
​
[...]
```

### API to delete the index

With `_all` it will delete all indices.

```bash
curl -X DELETE 'elasticsearch:9200/_all'
```

**> Output:**

```bash
{"acknowledged":true}
```

## Show the indexing status in the database

Returns the status of your indexing:

```sql
select * from message_queue_stats mqs ; 
select count(*) from enqueue e ; 
select count(*) from dead_message dm ; 
```

The number of entries in the enqueue should match the sum of the size values in the `message_queue_stats`. As long as there are entries in your `enqueue`, the indexing is in process and your message consumer has to work those messages.

## Reset the indexing in the database

Sometimes you want to reset the indexing in your database because your indexing is stuck or you run into an error.
If the database queue is used, third-party services will differ. You can do so with the following queries.

```sql
truncate enqueue ; 
truncate dead_message ;
truncate message_queue_stats ;
update scheduled_task set status = 'scheduled' where status = 'queued';
```

## Completely reset your Elasticsearch and reindex

This is mainly for debugging purposes and is only meant for testing and staging environments.
First, execute the database reset (only working for the database queue):

```sql
truncate enqueue ; 
truncate dead_message ;
truncate message_queue_stats ;
update scheduled_task set status = 'scheduled' where status = 'queued';
```

Now delete the old Elasticsearch index, clear your cache, reindex and ensure that the indexing process is finished:

```bash
curl -X DELETE 'elasticsearch:9200/_all'
bin/console cache:clear
bin/console es:index
bin/console messenger:consume -vv
```

After the last message has been processed, your index should be found in your Storefront else execute:

```bash
bin/console es:create:alias
```

## Logfiles and tipps

You can usually find the Elasticsearch logfiles at [`/var/log/elasticsearch`](https://www.elastic.co/guide/en/elasticsearch/reference/master/settings.html#_config_file_format) to check for any issues when indexing.
Also, tools like [Kibana](https://www.elastic.co/kibana) or [Cerebro](https://wissen.profihost.com/wissen/artikel/cerebro/) can help you better understand what is happening in your Elasticsearch.

---

---
url: >-
  /docs/v6.6/guides/hosting/infrastructure/elasticsearch/elasticsearch-debugging.md
---

# Debugging Elasticsearch

## Overview

This article shows you how to debug the status and indexing process of your Elasticsearch environment. Ensure that the [Debug-Mode](./elasticsearch-debugging) is activated in your *.env* file.

## Shopware 6 CLI commands

### Cache clear

`cache:clear` clears the cache

```bash
bin/console cache:clear
```

**> Output:**

```bash
// Clearing the cache for the dev environment with debug
// true
​[OK] Cache for the "dev" environment (debug=true) was successfully cleared.
```

### ES index

`es:index` creates only the index for ES

```bash
bin/console es:index // Creates only the index for ES
```

**> No Output**

### ES create alias

`es:create:alias`  will create an alias linking to the