diff --git a/.gitbook.yaml b/.gitbook.yaml
index 02df71575f..b433b194c8 100644
--- a/.gitbook.yaml
+++ b/.gitbook.yaml
@@ -91,6 +91,7 @@ redirects:
products/plugins/commercial/: products/extensions/commercial/
guides/installation/devenv.html: guides/installation/setups/devenv.html
products/cli/extension-commands/validation.html: products/cli/validation.html
+ products/cli/project-commands/remote-extension-managment.html: products/cli/project-commands/remote-extension-management.html
products/paas/: products/paas/index.html
products/paas/cli-setup.html: products/paas/shopware-paas/cli-setup.html
products/paas/repository.html: products/paas/shopware-paas/repository.html
@@ -136,7 +137,6 @@ redirects:
products/paas/shopware/CLI/repository.html: products/paas/shopware/guides/setting-up-repository-access.html
products/paas/shopware/setup-shopware-for-paas.html: products/paas/shopware/get-started/prepare-codebase.html
products/paas/shopware/project_setup.html: products/paas/shopware/get-started/quickstart.html
- guides/plugins/plugins/testing/end-to-end-testing.html: guides/plugins/plugins/testing/cypress/cypress-end-to-end-testing.html
resources/guidelines/testing/cypress-best-practices.html: guides/plugins/plugins/testing/cypress/cypress-best-practises.html
resources/guidelines/trouble-shoting.html: resources/guidelines/troubleshooting.html
products/extensions/subscriptions/guides/event.html: products/extensions/subscriptions/guides/separate-checkout.html
@@ -160,6 +160,17 @@ redirects:
guides/plugins/plugins/administration/system-updates/vite.html: guides/upgrades-migrations/administration/vite.html
guides/plugins/plugins/administration/system-updates/vue-migration-build.html: guides/upgrades-migrations/administration/vue-migration-build.html
guides/plugins/plugins/administration/system-updates/vue-native.html: guides/upgrades-migrations/administration/vue-native.html
+ guides/plugins/plugins/testing/end-to-end-testing.html: guides/plugins/plugins/testing/cypress/cypress-end-to-end-testing.html
+ guides/plugins/themes/add-assets-to-theme.html: guides/plugins/themes/assets/add-assets-to-theme.html
+ guides/plugins/themes/add-css-js-to-theme.html: guides/plugins/themes/styling/add-css-js-to-theme.html
+ guides/plugins/themes/add-icons.html: guides/plugins/themes/assets/add-icons.html
+ guides/plugins/themes/add-theme-inheritance-without-resources.html: guides/plugins/themes/inheritance/add-theme-inheritance-without-resources.html
+ guides/plugins/themes/add-theme-inheritance.html: guides/plugins/themes/inheritance/add-theme-inheritance.html
+ guides/plugins/themes/differences-plugins-and-apps-vs-themes.html: guides/plugins/themes/index.html
+ guides/plugins/themes/override-bootstrap-variables-in-a-theme.html: guides/plugins/themes/styling/override-bootstrap-variables-in-a-theme.html
+ guides/plugins/themes/override-theme-breakpoints.html: guides/plugins/themes/styling/override-theme-breakpoints.html
+ guides/plugins/themes/theme-configuration.html: guides/plugins/themes/configuration/theme-configuration.html
+ guides/plugins/themes/theme-inheritance-configuration.html: guides/plugins/themes/configuration/theme-inheritance-configuration.html
resources/references/upgrades/core/translation/extension-translation.html: guides/upgrades-migrations/extension-translation.html
resources/references/upgrades/core/translation/language-pack-migration.html: guides/upgrades-migrations/language-pack-migration.html
resources/references/upgrades/administration/: guides/upgrades-migrations/administration/
@@ -176,6 +187,10 @@ redirects:
resources/guidelines/testing/store/quality-guidelines-plugins/: guides/development/testing/testing-guidelines.html
resources/guidelines/testing/store/quality-guidelines-apps/: guides/development/testing/testing-guidelines.html
resources/guidelines/testing/store/quality-guidelines-plugins/#the-way-we-test-apps-based-on-the-plugin-system: guides/development/testing/testing-guidelines.html
+ resources/guidelines/troubleshooting/index.html: guides/development/troubleshooting/index.html
+ resources/guidelines/troubleshooting/elasticsearch.html: guides/hosting/infrastructure/elasticsearch/elasticsearch.html
+ resources/guidelines/troubleshooting/performance.html: guides/hosting/performance/performance.html
+ resources/guidelines/troubleshooting/phpstan.html: guides/development/troubleshooting/phpstan.html
guides/integrations-api/general-concepts/: guides/development/integrations-api/
guides/integrations-api/general-concepts/api-versioning.html: guides/development/integrations-api/request-headers.html#sw-version-id
guides/integrations-api/general-concepts/request-headers.html: guides/development/integrations-api/request-headers.html
@@ -205,7 +220,6 @@ redirects:
guides/plugins/plugins/testing/cypress/cypress-best-practises.html: guides/development/testing/legacy/cypress/cypress-best-practises.html
guides/plugins/plugins/testing/cypress/cypress-end-to-end-testing/: guides/development/testing/legacy/cypress/
guides/resources/references/core-reference/dal-reference/filters-reference.html: resources/references/core-reference/dal-reference/filters-reference.html
- resources/guidelines/code/core/database-migations.html: resources/guidelines/code/core/database-migrations.html
resources/guidelines/code/core/final-and-internal.html: guides/development/extensions/architecture/final-and-internal.html
resources/guidelines/code/core/internal.html: guides/development/extensions/architecture/internal.html
resources/guidelines/code/core/extendability.html: guides/development/extensions/architecture/extendability.html
diff --git a/concepts/framework/data-abstraction-layer.md b/concepts/framework/data-abstraction-layer.md
index 3435e5e93e..e094ae9d7c 100644
--- a/concepts/framework/data-abstraction-layer.md
+++ b/concepts/framework/data-abstraction-layer.md
@@ -16,7 +16,7 @@ The DAL is implemented with the specific needs of Shopware in mind and lets deve
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.
+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.
@@ -55,7 +55,7 @@ $services->set(Swag\ExamplePlugin\Service\DalExampleService::class)
You can read more about dependency injection and service registration in Shopware in the services guides:
-
+
### Translations
diff --git a/concepts/framework/elasticsearch.md b/concepts/framework/elasticsearch.md
index 01ad814b24..86bfc2f1b8 100644
--- a/concepts/framework/elasticsearch.md
+++ b/concepts/framework/elasticsearch.md
@@ -9,7 +9,7 @@ nav:
Elasticsearch is a NoSQL Database focused on search capabilities to act as a search engine.
The Shopware implementation of Elasticsearch provides an integrated way to improve the performance of product and category searches.
-To use Elasticsearch for your shop, take a look at our [Elasticsearch guide](../../guides/hosting/infrastructure/elasticsearch/elasticsearch-setup)
+To use Elasticsearch for your shop, take a look at our [Elasticsearch guide](../../guides/hosting/infrastructure/elasticsearch/index.md).
## Concept
@@ -89,4 +89,4 @@ The command `es:test:analyzer` runs an Elasticsearch analyzer on your indices. F
## Customize the Elasticsearch integration
-To customize the Elasticsearch integration or add your own fields and entities, refer to the [Elasticsearch extension guide](../../guides/plugins/plugins/elasticsearch/add-product-entity-extension-to-elasticsearch)
+To customize the Elasticsearch integration or add your own fields and entities, refer to the [Elasticsearch extension guide](../../guides/plugins/plugins/integrations/elasticsearch/add-product-entity-extension-to-elasticsearch.md)
diff --git a/concepts/translations/built-in-translation-system.md b/concepts/translations/built-in-translation-system.md
index 4b2a8e8117..d50a2a724e 100644
--- a/concepts/translations/built-in-translation-system.md
+++ b/concepts/translations/built-in-translation-system.md
@@ -8,7 +8,7 @@ It provides the same set of translations as the **Language Pack** plugin and is
> **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][migration-guide] for instructions
+> the [Migration guide](../../guides/upgrades-migrations/language-pack-migration.md) for instructions
> on switching to the new system.
## Where do the translations come from?
@@ -19,7 +19,7 @@ This repository is managed using [Crowdin](https://crowdin.com/project/shopware6
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?
+## How to install and update translations?
To use the built-in translation system, you can use the following console commands:
@@ -75,7 +75,7 @@ When loading translations, the system follows a defined priority order to resolv
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](./../../concepts/translations/fallback-language-selection).
+ 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](../../concepts/translations/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
@@ -225,5 +225,4 @@ 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.
-[migration-guide]: ../../resources/references/upgrades/core/translation/language-pack-migration.md
-[language-layer-docs]: TODO
+More information is available in the [Migration Guide](../../guides/upgrades-migrations/language-pack-migration.md).
diff --git a/concepts/translations/fallback-language-selection.md b/concepts/translations/fallback-language-selection.md
index 7d638cda45..cbd854c357 100644
--- a/concepts/translations/fallback-language-selection.md
+++ b/concepts/translations/fallback-language-selection.md
@@ -50,7 +50,7 @@ The command supports several options:
## Implementation guidelines for extension developers
-For detailed instructions, see the [Extension Translation Migration](./../../resources/references/upgrades/core/translation/extension-translation) guide. In short:
+For detailed instructions, see the [Extension Translation Migration](../../guides/upgrades-migrations/extension-translation.md) guide. In short:
- **Create a complete base file** (`messages..base.json`) for each supported language.
- **Add patch files only when needed** – keep them minimal.
@@ -62,4 +62,4 @@ For detailed instructions, see the [Extension Translation Migration](./../../res
## Conclusion
The country-independent snippet layer streamlines translation maintenance by consolidating common strings into a neutral fallback file and isolating regional vocabulary into small patch files.
-For further examples, refer to [Built-in Translation Handling](./built-in-translation-system) and [Extension Translation Migration](./../../resources/references/upgrades/core/translation/extension-translation).
+For further examples, refer to [Built-in Translation Handling](built-in-translation-system.md) and [Extension Translation Migration](../../guides/upgrades-migrations/extension-translation.md).
diff --git a/guides/development/accessibility/storefront-accessibility.md b/guides/development/accessibility/storefront-accessibility.md
index 7d04ee4c17..eec49b3229 100644
--- a/guides/development/accessibility/storefront-accessibility.md
+++ b/guides/development/accessibility/storefront-accessibility.md
@@ -6,12 +6,12 @@ nav:
# Accessibility in the Storefront
-At Shopware, we are committed to creating inclusive and barrier-free shopping experiences for our merchants and their customers.
+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/).
+ * 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.
diff --git a/guides/development/extensions/architecture/extendability.md b/guides/development/extensions/architecture/extendability.md
index d4cb68a088..cb0760589b 100644
--- a/guides/development/extensions/architecture/extendability.md
+++ b/guides/development/extensions/architecture/extendability.md
@@ -12,7 +12,9 @@ This document represents core guidelines and has been mirrored from the core in
Find the original version [here](https://github.com/shopware/shopware/blob/trunk/coding-guidelines/core/extendability.md)
:::
-The Extendability of our software and its features is an essential part of development. Enabling external companies, as well as ourselves, to customize our software so it can be adapted to different business cases is the foundation of our software's success.
+## Overview
+
+The extendability of our software and its features is an essential part of development. Enabling external companies, as well as ourselves, to customize our software so it can be adapted to different business cases is the foundation of our software's success.
Regarding software extendability, different business cases and requirements must be considered, and we must also build the software architecture accordingly.
@@ -67,7 +69,7 @@ All the above requirements and approaches are based on different design patterns
With the Decoration pattern, we can replace or extend certain areas of Shopware completely. We often use this pattern for our Store API routes to provide more functionality in the Store API. Another use case is the **functional replacement market** case, where we can completely replace features with other technologies or external libraries.
-An example Store API route is the CategoryRoute. For this route, there is an [Abstract class](https://github.com/shopware/shopware/blob/v6.4.12.0/src/Core/Content/Category/SalesChannel/AbstractCategoryRoute.php) to which we type behind a [Concrete implementation](https://github.com/shopware/shopware/blob/v6.4.12.0/src/Core/Content/Category/SalesChannel/CategoryRoute.php) and a [Cache decorator](https://github.com/shopware/shopware/blob/v6.4.12.0/src/Core/Content/Category/SalesChannel/CachedCategoryRoute.php)
+An example Store API route is the CategoryRoute. For this route, there is an [Abstract class](https://github.com/shopware/shopware/blob/v6.4.12.0/src/Core/Content/Category/SalesChannel/AbstractCategoryRoute.php) to which we type behind a [Concrete implementation](https://github.com/shopware/shopware/blob/v6.4.12.0/src/Core/Content/Category/SalesChannel/CategoryRoute.php) and a [Cache decorator](https://github.com/shopware/shopware/blob/v6.4.12.0/src/Core/Content/Category/SalesChannel/CachedCategoryRoute.php).
### Factory
diff --git a/guides/development/extensions/architecture/final-and-internal.md b/guides/development/extensions/architecture/final-and-internal.md
index f8016d1693..f8e52ad806 100644
--- a/guides/development/extensions/architecture/final-and-internal.md
+++ b/guides/development/extensions/architecture/final-and-internal.md
@@ -5,13 +5,15 @@ nav:
---
-# Final and internal annotation
+# Final and Internal Annotation
::: 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/final-and-internal.md)
:::
+## Overview
+
We use `@final` and `@internal` annotations to mark classes as final or internal. This allows us to mark services and classes as public or private API and to define which breaking changes can be expected.
## Final
diff --git a/guides/development/extensions/architecture/index.md b/guides/development/extensions/architecture/index.md
index d5913ee836..2d7d04ba53 100644
--- a/guides/development/extensions/architecture/index.md
+++ b/guides/development/extensions/architecture/index.md
@@ -6,6 +6,8 @@ nav:
# Extension Architecture
+## Overview
+
This section defines the architectural principles that govern how Shopware can be extended. It describes extension contracts, subsystem boundaries, and public API guarantees that apply to all extension types:
* Plugins
diff --git a/guides/development/extensions/architecture/internal.md b/guides/development/extensions/architecture/internal.md
index ac81c84b37..16d41259a4 100644
--- a/guides/development/extensions/architecture/internal.md
+++ b/guides/development/extensions/architecture/internal.md
@@ -12,6 +12,8 @@ This document represents core guidelines and has been mirrored from the core in
You can find the original version [here](https://github.com/shopware/shopware/blob/trunk/coding-guidelines/core/internal.md)
:::
+## Overview
+
All classes and elements (methods, properties, constants) that are defined as protected or public are initially considered part of the Public API for third-party developers.
The Shopware Public API must be kept compatible with each release. This means that the following must not change for third-party developers in a minor release:
diff --git a/guides/development/extensions/code-structure.md b/guides/development/extensions/code-structure.md
index e2793bedd3..de25d3128d 100644
--- a/guides/development/extensions/code-structure.md
+++ b/guides/development/extensions/code-structure.md
@@ -15,18 +15,19 @@ nav:
## Choose the right extension type
-* **Custom project/bundle**: Fit 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.
-* **Private/custom plugin**: 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.
-* **Store plugin**: Same plugin layout, but hardened for Store review: strict metadata, no project-only hacks, testability, and BC guarantees.
+* **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)).
+* 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 (custom and Store)
+## 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.
@@ -35,7 +36,7 @@ nav:
## App structure
-* Keep the manifest minimal and explicit: permissions, webhooks, actions, and extensions should match the documented entrypoints ([app base guide](../../plugins/apps/app-base-guide.md)).
+* 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.
diff --git a/guides/development/extensions/index.md b/guides/development/extensions/index.md
index f7027a1841..4ce24cf74f 100644
--- a/guides/development/extensions/index.md
+++ b/guides/development/extensions/index.md
@@ -17,10 +17,10 @@ Shopware offers two extension types:
Plugins and apps are installed and activated for the whole Shopware instance.
:::info
-Before choosing an extension type, review the recommended [Code structure](code-structure.md). Following the standard structure reduces upgrade friction and prevents long-term maintenance issues.
+Before choosing an extension type, review the recommended [Code structure](code-structure.md) to proactively reduce upgrade friction and prevent long-term maintenance issues.
:::
-A storefront theme is *not* a separate extension type, but a stripped-down plugin consisting of a customized storefront UI. In Cloud environments, storefront themes are delivered via apps.
+A storefront theme is *not* a distinct extension type, but a stripped-down plugin consisting of a customized storefront UI. In Cloud environments, storefront themes are delivered via apps.
## Monetization
diff --git a/guides/development/monetization/index.md b/guides/development/monetization/index.md
index 89c886eb8c..cab69347f3 100644
--- a/guides/development/monetization/index.md
+++ b/guides/development/monetization/index.md
@@ -9,7 +9,7 @@ nav:
Shopware provides multiple ways to monetize your extension in the Store. Choose the model that fits your business strategy and target audience.
-All monetized extensions must comply with our [quality guidelines](../testing/store/quality-guidelines) and avoid [Common Store Review Errors](./store-review-errors).
+All monetized extensions must comply with our [quality guidelines](../testing/store/quality-guidelines.md) and avoid [Common Store Review Errors](../../development/testing/store/store-review-errors.md).
## Paid extensions
@@ -17,8 +17,8 @@ Sell your extension with a one-time purchase or subscription model via the Shopw
## In-App Purchases (IAP)
-[In-App Purchases](./in-app-purchases) enable locking specific features behind additional purchases within the same extension. Available since Shopware 6.6.9.0.
+[In-App Purchases](./in-app-purchases.md) enable locking specific features behind additional purchases within the same extension. Available since Shopware 6.6.9.0.
## Commission-based integrations
-If your extension integrates external services and generates revenue (e.g., transaction-based fees), a Shopware Technology Partner (STP) agreement may be required. See the [quality guidelines](../testing/store/quality-guidelines) for details.
+If your extension integrates external services and generates revenue (e.g., transaction-based fees), a Shopware Technology Partner (STP) agreement may be required. See the [quality guidelines](../testing/store/quality-guidelines.md) for details.
diff --git a/guides/development/testing/ci.md b/guides/development/testing/ci.md
index 55335a1081..9686bf23ed 100644
--- a/guides/development/testing/ci.md
+++ b/guides/development/testing/ci.md
@@ -1,13 +1,13 @@
---
nav:
- title: CI
+ title: Continuous Integration
position: 10
---
-# CI
+# Continuous Integration
-CI 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.
+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.
diff --git a/guides/development/testing/testing-guidelines.md b/guides/development/testing/testing-guidelines.md
index 34d1535bc3..2846f3fc41 100644
--- a/guides/development/testing/testing-guidelines.md
+++ b/guides/development/testing/testing-guidelines.md
@@ -1,6 +1,6 @@
---
nav:
- title: Testing guidelines for extensions
+ title: Testing Guidelines for Extensions
position: 10
---
diff --git a/guides/development/testing/unit/jest-admin.md b/guides/development/testing/unit/jest-admin.md
index 6125244e5e..af46834363 100644
--- a/guides/development/testing/unit/jest-admin.md
+++ b/guides/development/testing/unit/jest-admin.md
@@ -1,6 +1,6 @@
---
nav:
- title: Jest unit tests in Shopware's administration
+ title: Jest Unit Tests in Shopware's Administration
position: 20
---
diff --git a/guides/development/testing/unit/jest-storefront.md b/guides/development/testing/unit/jest-storefront.md
index 887c54698d..22c7ed47ee 100644
--- a/guides/development/testing/unit/jest-storefront.md
+++ b/guides/development/testing/unit/jest-storefront.md
@@ -1,6 +1,6 @@
---
nav:
- title: Jest unit tests in Shopware's storefront
+ title: Jest Unit Tests in Shopware's Storefront
position: 30
---
@@ -51,7 +51,7 @@ Please note that in this example, `` is a placeholder for the envir
## Writing a basic test
-When writing Jest unit tests in the Storefront, you will soon realize that it's not that much different from writing Jest unit tests in general. Unlike the [Jest unit tests in the Administration](jest-admin), you basically don't need to go the extra mile to write your unit tests. Services, helpers, and isolated ECMAScript modules are well testable because you can import them directly without mocking or stubbing dependencies. They can be used in isolation, making them easy to test.
+When writing Jest unit tests in the Storefront, you will soon realize that it's not that much different from writing Jest unit tests in general. Unlike the [Jest unit tests in the Administration](jest-admin.md), you basically don't need to go the extra mile to write your unit tests. Services, helpers, and isolated ECMAScript modules are well testable because you can import them directly without mocking or stubbing dependencies. They can be used in isolation, making them easy to test.
Let's start from scratch with a simple example: imagine we want to write a test for a helper class, e.g., the `feature.helper` of our Storefront, that handles feature flag usage. We want to test whether our feature helper can indeed handle active feature flags.
diff --git a/guides/development/testing/unit/php-unit.md b/guides/development/testing/unit/php-unit.md
index 7b1154bdf6..1a80ef447a 100644
--- a/guides/development/testing/unit/php-unit.md
+++ b/guides/development/testing/unit/php-unit.md
@@ -205,7 +205,7 @@ To execute a specific test class or method of a testsuite, pass the argument `--
## Flex template
-To run PHPunit tests install the flex template [dev-tools](../../../../guides/installation/template.md#how-do-i-migrate-from-production-template-to-symfony-flex) package via composer.
+To run PHPunit tests install the flex template [dev-tools](../../../installation/project-overview.md#project-template) package via Composer.
```shell
composer require --dev dev-tools
diff --git a/guides/development/troubleshooting/dal-reference/fields-reference/enum-field.md b/guides/development/troubleshooting/dal-reference/fields-reference/enum-field.md
index cae816b5f0..aa507c9283 100644
--- a/guides/development/troubleshooting/dal-reference/fields-reference/enum-field.md
+++ b/guides/development/troubleshooting/dal-reference/fields-reference/enum-field.md
@@ -1,15 +1,15 @@
---
nav:
- title: EnumField reference
+ title: EnumField Reference
position: 100
---
-# EnumField reference
+# EnumField Reference
## Usage
-The `EnumField` can be used to restrict `string` or `int` values to a fixed set.
+The `EnumField` can be used to restrict `string` or `int` values to a fixed set.
Define a `\BackedEnum` class, use them in an Entity and restrict the values in your RDBMS.
diff --git a/guides/development/troubleshooting/dal-reference/index.md b/guides/development/troubleshooting/dal-reference/index.md
index 159516530c..ee57262312 100644
--- a/guides/development/troubleshooting/dal-reference/index.md
+++ b/guides/development/troubleshooting/dal-reference/index.md
@@ -8,3 +8,12 @@ nav:
# 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`.
diff --git a/resources/guidelines/troubleshooting/phpstan.md b/guides/development/troubleshooting/phpstan.md
similarity index 90%
rename from resources/guidelines/troubleshooting/phpstan.md
rename to guides/development/troubleshooting/phpstan.md
index a2805e736c..fdcd6694fc 100644
--- a/resources/guidelines/troubleshooting/phpstan.md
+++ b/guides/development/troubleshooting/phpstan.md
@@ -6,11 +6,11 @@ nav:
# PHPStan
-## Common PHPStan Issues in Shopware Code
+This guide covers common PHPStan issues in Shopware code and shows how to fix them with proper DAL typing and null-safe patterns.
-### EntityRepository Should Define a Generic Type
+## EntityRepository should define a generic type
-**Problem**: Repository returns EntityCollection without type information.
+**Problem**: Repository returns `EntityCollection` without type information.
```php
$products = $this->productRepository->search($criteria, $context)->getEntities();
@@ -48,7 +48,7 @@ Be aware that the `EntityRepository` class is a generic class, which gets an Ent
This might sound counter-intuitive and different to other well-known repository classes, which take the Entity class as the generic type.
But it was the easiest technical solution to get PHPStan to understand the type of the collection returned by the search method.
-### Null Safety with First method and Associations
+## Null safety with first method and associations
**Problem**: Calling `first` could return `null`, also entity associations can be `null` if not loaded.
@@ -83,7 +83,7 @@ Or use the null-safe operators:
$manufacturerName = $product?->getManufacturer()?->getName() ?? 'Unknown';
```
-### Missing Generic Type for EntityCollection
+## Missing generic type for `EntityCollection`
**Problem**: Custom EntityCollection does not have a generic type.
diff --git a/guides/development/troubleshooting/rules-reference.md b/guides/development/troubleshooting/rules-reference.md
index 9cbccab760..a0b1f24fd3 100644
--- a/guides/development/troubleshooting/rules-reference.md
+++ b/guides/development/troubleshooting/rules-reference.md
@@ -1,7 +1,7 @@
---
nav:
title: Rules Reference
- position: 30
+ position: 40
---
diff --git a/guides/hosting/infrastructure/elasticsearch/elasticsearch-debugging.md b/guides/hosting/infrastructure/elasticsearch/elasticsearch-debugging.md
index 3ec8b03983..e3dcce49b6 100644
--- a/guides/hosting/infrastructure/elasticsearch/elasticsearch-debugging.md
+++ b/guides/hosting/infrastructure/elasticsearch/elasticsearch-debugging.md
@@ -1,15 +1,17 @@
---
nav:
- title: Debugging Elasticsearch
+ title: Debugging and Troubleshooting Elasticsearch
position: 20
---
-# Debugging Elasticsearch
+# Debugging and Troubleshooting 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.
+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
@@ -251,7 +253,7 @@ After the last message has been processed, your index should be found in your St
bin/console es:create:alias
```
-## Logfiles and tipps
+## 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.
diff --git a/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md b/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md
index ed5a32fd6f..6e9f1ad219 100644
--- a/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md
+++ b/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md
@@ -18,20 +18,20 @@ Currently, the implementation for Elasticsearch/Opensearch works in the same way
## Requirements
- [A supported OpenSearch (or Elasticsearch) server](../../../hosting/index.md#recommended-stack-and-supported-versions)
-- [Running message queue workers in the background](../message-queue)
+- [Running message queue workers in the background](../message-queue.md)
## Server basics
Elasticsearch installation and configuration greatly depend on your operating system and hosting provider. You will find extensive documentation online regarding the installation and configuration of Elasticsearch on most common Linux distributions. Some hosting providers might also provide specific documentation regarding this subject. Installation on macOS or Windows is also possible but not officially supported.
-The current Shopware 6 integration is designed to work with the out-of-the-box configuration of Elasticsearch. This does not mean, of course, that these are the best settings for a production environment. Although they will affect performance and security, the settings you choose to use on your Elasticsearch setup will be mostly transparent to your Shopware installation. The best setting constellation for your shop will greatly depend on your server setup, the number, and structure of products, and replication requirements, to name a few. In this document, we can't give you specific examples for your setup, but provide you with hints and basics you might need to choose your perfect setup. More detailed information can be found on the official [Elasticsearch](https://www.elastic.co/guide/index.html) documentation page.
+The current Shopware 6 integration is designed to work with the out-of-the-box configuration of Elasticsearch. This does not mean, of course, that these are the best settings for a production environment. Although they will affect performance and security, the settings you choose to use on your Elasticsearch setup will be mostly transparent to your Shopware installation. The best setting constellation for your shop will greatly depend on your server setup, the number, and structure of products, and replication requirements, to name a few. In this document, we can't give you specific examples for your setup, but provide you with hints and basics you might need to choose your perfect setup. More detailed information can be found on the official [Elasticsearch](https://www.elastic.co/docs) documentation page.
### Elasticsearch server setup
Elasticsearch is meant to be used as a cluster setup so it can scale properly and provide you with reliability.
In this cluster, you can choose how many nodes you want to use and which different type each node in the cluster shall have.
A one-node cluster should only be used for development or test environments, because it can't scale and does not provide additional reliability.
-Reliability is given when you have at least three nodes because of the process of election of the master node. This is further explained in more detail in the [Master Node](#master-node) section.
+Reliability is given when you have at least three nodes because of the process of election of the master node. This is further explained in more detail in the [Master Node](elasticsearch-setup.md#master-nodes) section.
From our experience, the best way is to have a cluster with five nodes. You can have the three needed master-eligible nodes and 2 nodes which are data nodes and do not proceed in the election process.
Which cluster is really needed in your setup and fits your needs best is up to you.
@@ -161,13 +161,13 @@ Before indexing, you might want to clear your cache with `bin/console cache:clea
Normally, you can index by executing the command `bin/console es:index`.
::: info
-For additional support with common Elasticsearch errors and more tips please refer to [elasticsearch troubleshooting](https://developer.shopware.com/docs/resources/guidelines/troubleshooting/elasticsearch.html).
+For additional support with common Elasticsearch errors and more tips please refer to [Elasticsearch troubleshooting](../elasticsearch/elasticsearch-debugging.md).
:::
### Indexing the whole shop
Sometimes you want to reindex your whole shop, including Elasticsearch, SEO-URLs, product index, and more.
-For a reindex of the whole shop, you can use the command `bin/console dal:refresh:index --use-queue`. Use the `--use-queue` option because you will have too many products to index without the [message queue](../message-queue) involved.
+For a reindex of the whole shop, you can use the command `bin/console dal:refresh:index --use-queue`. Use the `--use-queue` option because you will have too many products to index without the [message queue](../message-queue.md) involved.
### Alias creation
@@ -181,10 +181,10 @@ If a messenger process is active, the entries of that table are processed one by
In case a message runs into an error, it is written into the `dead_messages` table and will be processed again after a specific time frame.
You can start multiple messenger consumer processes by using the command `bin/console messenger:consume` and also add output to the processed messages by adding the parameter `bin/console messenger:consume -vv`.
-In a production environment, you want to deactivate the admin messenger which is started automatically when opening a session in your Administration view by following this [documentation](../../../../guides/hosting/infrastructure/message-queue#admin-worker).
+In a production environment, you want to deactivate the admin messenger which is started automatically when opening a session in your Administration view by following this [documentation](../message-queue.md#admin-worker).
Our experience has shown that up to three worker processes are normal and useful for a production environment.
-If you want more than that, a tool like [RabbitMQ](../message-queue#message-queue-on-production-systems) to handle the queue is needed so your database will not become a bottleneck.
+If you want more than that, a tool like [RabbitMQ](../message-queue.md#message-queue-on-production-systems) to handle the queue is needed so your database will not become a bottleneck.
## Configuration
@@ -215,7 +215,7 @@ bin/console es:admin:test
```
::: info
-Advanced admin users can refer to [elasticsearch reference guide](https://www.elastic.co/docs/reference/query-languages/query-dsl/query-dsl-simple-query-string-query) for complex search queries.
+Advanced admin users can refer to [Elasticsearch reference guide](https://www.elastic.co/docs/reference/query-languages/query-dsl/query-dsl-simple-query-string-query) for complex search queries.
:::
### Apply OpenSearch globally in Admin API
diff --git a/resources/guidelines/troubleshooting/elasticsearch.md b/guides/hosting/infrastructure/elasticsearch/elasticsearch.md
similarity index 75%
rename from resources/guidelines/troubleshooting/elasticsearch.md
rename to guides/hosting/infrastructure/elasticsearch/elasticsearch.md
index e7a5ff6c73..2d33607f74 100644
--- a/resources/guidelines/troubleshooting/elasticsearch.md
+++ b/guides/hosting/infrastructure/elasticsearch/elasticsearch.md
@@ -6,28 +6,30 @@ nav:
# Elasticsearch
+This guide covers Elasticsearch integration and configuration in Shopware, including error handling and search indexing behavior.
+
+## Related guides
+
+* [Debugging and Troubleshooting Elasticsearch](./elasticsearch-debugging.md)
+
## Common Error Handling
### Enabling `SHOPWARE_ES_THROW_EXCEPTION`
-It is recommended to set the environment variable `SHOPWARE_ES_THROW_EXCEPTION=0` in **production environments** and enable it (`=1`) in **development environments**.
-This setting helps prevent unexpected interruptions to other processes caused by Elasticsearch or OpenSearch issues.
+It is recommended to set the environment variable `SHOPWARE_ES_THROW_EXCEPTION=0` in **production environments** and enable it (`=1`) in **development environments**. This setting helps prevent unexpected interruptions to other processes caused by Elasticsearch or OpenSearch issues.
Some common scenarios include:
-- **Search server is not reachable**:
+* ***Search server is not reachable**:
If the OpenSearch or Elasticsearch server is temporarily unavailable, keeping this option disabled (`=0`) allows Shopware to automatically fall back to the default MySQL-based search. This ensures that search functionality remains available.
A similar fallback also applies when updating products in the Administration, where data synchronization with the search server might fail intermittently.
-- **System updates causing expected errors**:
+* **System updates causing expected errors**:
During updates—whether through the web UI or via the CLI (`bin/console system:update:finish`)—index mappings may change, requiring a reindex. These expected errors should not block system updates in production, which is why exceptions should remain disabled in such environments.
----
-
-## Adjusting N-gram Settings for Search Precision
+## Adjusting N-gram Settings for search precision
-When a search field is marked as *searchable* and the **“Split search term”** option is enabled, Shopware uses an **n-gram tokenizer** to index and search that field.
-By default, Shopware uses the following configuration:
+When a search field is marked as *searchable* and the **“Split search term”** option is enabled, Shopware uses an **n-gram tokenizer** to index and search that field. By default, Shopware uses the following configuration:
```bash
SHOPWARE_ES_NGRAM_MIN_GRAM=4
diff --git a/guides/hosting/infrastructure/elasticsearch/index.md b/guides/hosting/infrastructure/elasticsearch/index.md
index 0170b3b1d8..b75a254cd1 100644
--- a/guides/hosting/infrastructure/elasticsearch/index.md
+++ b/guides/hosting/infrastructure/elasticsearch/index.md
@@ -1,12 +1,12 @@
---
nav:
title: Elasticsearch
- position: 5
+ position: 5
---
# Elasticsearch
-Elasticsearch is a robust search engine that can be integrated into Shopware to provide advanced search capabilities. It also supports AND/OR operations.
+[Elasticsearch](https://www.elastic.co/elasticsearch) is a robust search engine that can be integrated into Shopware to provide advanced search capabilities. It also supports AND/OR operations.
The following sections will help you to set up, configure, debug, resolve indexing issues, and optimize performance. By following these steps, you can leverage Elasticsearch to enhance search functionality in your Shopware store.
diff --git a/guides/hosting/infrastructure/filesystem.md b/guides/hosting/infrastructure/filesystem.md
index f702eaa777..ddd98894e1 100644
--- a/guides/hosting/infrastructure/filesystem.md
+++ b/guides/hosting/infrastructure/filesystem.md
@@ -1,7 +1,7 @@
---
nav:
title: Filesystem
- position: 10
+ position: 40
---
diff --git a/guides/hosting/infrastructure/index.md b/guides/hosting/infrastructure/index.md
index 5ec07a316c..013a72d1da 100644
--- a/guides/hosting/infrastructure/index.md
+++ b/guides/hosting/infrastructure/index.md
@@ -1,7 +1,7 @@
---
nav:
title: Infrastructure
- position: 40
+ position: 10
---
diff --git a/guides/hosting/infrastructure/message-queue.md b/guides/hosting/infrastructure/message-queue.md
index ff5d5296a8..95c64d136b 100644
--- a/guides/hosting/infrastructure/message-queue.md
+++ b/guides/hosting/infrastructure/message-queue.md
@@ -1,7 +1,7 @@
---
nav:
title: Message Queue
- position: 20
+ position: 50
---
@@ -142,7 +142,7 @@ If a message fails, it will be moved to the failed transport. The failed transpo
## Changing the transport
-By default, Shopware uses the Doctrine transport. This is simple transport that stores the messages in the database. This is a good choice for development, but not recommended for production systems. You can change the transport to another system like [RabbitMQ](https://www.rabbitmq.com/). This would, relieve the database and, on the other hand, use a much more specialized service for handling message queues. The following are examples of the steps needed.
+By default, Shopware uses the Doctrine transport. This is simple transport that stores the messages in the database. This is a good choice for development, but not recommended for production systems. You can change the transport to another system like [RabbitMQ](https://www.rabbitmq.com/). This would relieve the database and, on the other hand, use a much more specialized service for handling message queues. The following are examples of the steps needed.
You can find all available transport options in the Symfony Messenger documentation:
@@ -182,7 +182,7 @@ For more information on this check the [Symfony docs](https://symfony.com/doc/cu
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.
+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:
diff --git a/guides/hosting/infrastructure/optional-packages.md b/guides/hosting/infrastructure/optional-packages.md
new file mode 100644
index 0000000000..68854461a5
--- /dev/null
+++ b/guides/hosting/infrastructure/optional-packages.md
@@ -0,0 +1,35 @@
+---
+nav:
+ title: Optional Packages
+ position: 60
+---
+
+# Optional Packages
+
+The minimal project template is intentionally small and does not include additional infrastructure integrations or developer tooling by default.
+
+Extend a project with optional packages as needed.
+
+## Symfony development tools
+
+Install Symfony’s profiler and related development tools:
+
+```bash
+composer require --dev shopware/dev-tools
+```
+
+## PaaS integration
+
+Install the Platform-as-a-Service integration:
+
+```bash
+composer require shopware/paas-meta --ignore-platform-req=ext-amqp
+```
+
+## Fastly integration
+
+Install Fastly support:
+
+```bash
+composer require shopware/fastly-meta
+```
diff --git a/guides/hosting/infrastructure/rate-limiter.md b/guides/hosting/infrastructure/rate-limiter.md
index 68af7f3ed7..5bb536a774 100644
--- a/guides/hosting/infrastructure/rate-limiter.md
+++ b/guides/hosting/infrastructure/rate-limiter.md
@@ -1,7 +1,7 @@
---
nav:
title: Rate Limiter
- position: 10
+ position: 70
---
diff --git a/guides/hosting/infrastructure/redis.md b/guides/hosting/infrastructure/redis.md
index e7a088ea59..b16cfe212f 100644
--- a/guides/hosting/infrastructure/redis.md
+++ b/guides/hosting/infrastructure/redis.md
@@ -1,7 +1,7 @@
---
nav:
title: Redis
- position: 7
+ position: 80
---
diff --git a/guides/hosting/infrastructure/reverse-http-cache.md b/guides/hosting/infrastructure/reverse-http-cache.md
index 81a40d6294..7980d53580 100644
--- a/guides/hosting/infrastructure/reverse-http-cache.md
+++ b/guides/hosting/infrastructure/reverse-http-cache.md
@@ -1,7 +1,7 @@
---
nav:
title: Reverse HTTP Cache
- position: 40
+ position: 90
---
@@ -10,7 +10,7 @@ nav:
## Overview
A reverse HTTP cache is a cache server placed before the web shop.
-If you are not familiar with HTTP caching, please refer to the [HTTP cache](../../../concepts/framework/http_cache) concept.
+If you are not familiar with HTTP caching, please refer to the [HTTP cache](../../../concepts/framework/http_cache.md) concept.
The reverse http cache needs the following capabilities to function fully with Shopware:
* Able to differentiate the request with multiple cookies
diff --git a/guides/hosting/infrastructure/scheduled-task.md b/guides/hosting/infrastructure/scheduled-task.md
index a78a26d1b5..a8da3628e5 100644
--- a/guides/hosting/infrastructure/scheduled-task.md
+++ b/guides/hosting/infrastructure/scheduled-task.md
@@ -1,11 +1,11 @@
---
nav:
title: Scheduled Task
- position: 30
+ position: 100
---
-# Scheduled task
+# Scheduled Task
## What are scheduled tasks?
@@ -93,7 +93,7 @@ You can run scheduled tasks as part of your queue workers with the help of the s
bin/console messenger:consume scheduler_shopware
```
-On startup of this command reads the `scheduled_task` database table and applies the stored intervals, an entry in this table is optional. In the event that these intervals are modified in the database, it is necessary to restart the command for the updated intervals to take effect.
+On startup of this command reads the `scheduled_task` database table and applies the stored intervals, an entry in this table is optional. In the event that these intervals are modified in the database, it is necessary to restart the command for the updated intervals to take effect.
To deactivate tasks, set status to `Shopware\Core\Framework\MessageQueue\ScheduledTask\ScheduledTaskDefinition::STATUS_INACTIVE` in this table, and restart the `consume` command.
diff --git a/guides/hosting/installation-updates/deployments/build-w-o-db.md b/guides/hosting/installation-updates/deployments/build-w-o-db.md
index 63ec620013..78e1848824 100644
--- a/guides/hosting/installation-updates/deployments/build-w-o-db.md
+++ b/guides/hosting/installation-updates/deployments/build-w-o-db.md
@@ -1,11 +1,11 @@
---
nav:
- title: Building without Database
+ title: Building Without Database
position: 20
---
-# Building assets of Administration and Storefront without a Database
+# 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`.
@@ -22,7 +22,7 @@ Using this, you can dump the plugins for the Administration with the new file wi
## 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.
+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.
diff --git a/guides/hosting/installation-updates/deployments/deployment-with-deployer.md b/guides/hosting/installation-updates/deployments/deployment-with-deployer.md
index 811d4f7c7e..cb64d806a2 100644
--- a/guides/hosting/installation-updates/deployments/deployment-with-deployer.md
+++ b/guides/hosting/installation-updates/deployments/deployment-with-deployer.md
@@ -19,7 +19,7 @@ This article explains the fundamental steps to deploy Shopware 6 to a certain in
## Prerequisites
-Please make sure you already have a working Shopware 6 instance running and that your repository is based on the [Symfony Flex template](../../../installation/template) because this article relies on some scripts to exist in your repository.
+Please make sure you already have a working Shopware 6 instance running and that your repository is based on the [Symfony Flex template](../../../installation/project-overview.md#project-template) because this article relies on some scripts to exist in your repository.
### Preparations before the first deployment
@@ -40,7 +40,7 @@ The structure looks like this:
Suppose you haven't used such a structure yet, it is recommended to move the current document root contents to a different location because you will have to copy some existing files into the `shared` folder after your first deployment with [Deployer](https://deployer.org/).
-For more information, refer to [Migrating existing instance to Deployer structure](deployment-with-deployer#migrating-existing-instance-to-deployer-structure).
+For more information, refer to [Migrating existing instance to Deployer structure](deployment-with-deployer.md#migrating-existing-instance-to-deployer-structure).
### Webserver configuration
@@ -83,7 +83,7 @@ We use Shopware CLI, which simplifies the installation of the dependencies and b
### 3. Transferring the workspace
-For transferring the files to the target server, please configure at least one host in the [`deploy.php`](deployment-with-deployer#deploy-php):
+For transferring the files to the target server, please configure at least one host in the [`deploy.php`](deployment-with-deployer.md#deployphp):
```php
host('SSH-HOSTNAME')
@@ -97,7 +97,7 @@ host('SSH-HOSTNAME')
->set('writable_mode', 'chmod');
```
-This step is defined in the `deploy:update_code` job in the [`deploy.php`](deployment-with-deployer#deploy-php):
+This step is defined in the `deploy:update_code` job in the [`deploy.php`](deployment-with-deployer.md#deployphp):
```php
task('deploy:update_code')->setCallback(static function () {
@@ -119,7 +119,7 @@ The migrations need to be applied on the target server.
If you are deploying to a cluster with multiple web servers, please make sure to run the migrations only on one of the servers.
:::
-This step is defined in the `sw:deployment:helper` job in the [`deploy.php`](deployment-with-deployer#deploy-php), which is part of the `sw:deploy` task group:
+This step is defined in the `sw:deployment:helper` job in the [`deploy.php`](deployment-with-deployer.md#deployphp), which is part of the `sw:deploy` task group:
```php
task('sw:deployment:helper', static function() {
@@ -131,7 +131,7 @@ task('sw:deployment:helper', static function() {
Before putting the new version live, ensure to create an empty file `install.lock` in the root of the build workspace. Otherwise, Shopware will redirect every request to the Shopware installer because it assumes that Shopware isn't installed yet.
-This task is defined in the `sw:touch_install_lock` job in the [`deploy.php`](deployment-with-deployer#deploy-php), which is part of the `sw:deploy` task group:
+This task is defined in the `sw:touch_install_lock` job in the [`deploy.php`](deployment-with-deployer.md#deployphp), which is part of the `sw:deploy` task group:
```php
task('sw:touch_install_lock', static function () {
@@ -155,7 +155,7 @@ task('sw:health_checks', static function () {
After all the steps are done, Deployer will switch the symlinks destination to the new release.
-This task is defined in the `deploy:symlink` default job in the [`deploy.php`](deployment-with-deployer#deploy-php).
+This task is defined in the `deploy:symlink` default job in the [`deploy.php`](deployment-with-deployer.md#deployphp).
## Deployer output
@@ -186,9 +186,9 @@ After the very first deployment with Deployer, you have to copy some files and d
Let's agree on the following two paths for the examples:
1. You have copied your existing Shopware instance to `/var/www/shopware_backup`.
-2. You have set the `deploy_path` in the [`deploy.php`](deployment-with-deployer#deploy-php) to `/var/www/shopware`.
+2. You have set the `deploy_path` in the [`deploy.php`](deployment-with-deployer.md#deployphp) to `/var/www/shopware`.
-Now, look at the `shared_files` and `shared_dirs` configurations in the [`deploy.php`](deployment-with-deployer#deploy-php). Simply copy all the paths into `/var/www/shopware/shared`. For the configuration of the `deploy.php` the commands would be the following:
+Now, look at the `shared_files` and `shared_dirs` configurations in the [`deploy.php`](deployment-with-deployer.md#deployphp). Simply copy all the paths into `/var/www/shopware/shared`. For the configuration of the `deploy.php` the commands would be the following:
```bash
cp /var/www/shopware_backup/.env.local /var/www/shopware/shared/.env.local
diff --git a/guides/hosting/installation-updates/deployments/index.md b/guides/hosting/installation-updates/deployments/index.md
index f02ded2d86..a81f4fa366 100644
--- a/guides/hosting/installation-updates/deployments/index.md
+++ b/guides/hosting/installation-updates/deployments/index.md
@@ -13,7 +13,7 @@ The following guides outline the core principles and practical steps for deployi
Successful deployments are predictable, repeatable, and reversible:
-- Build artifacts once in CI and deploy those artifacts.
+- Build artifacts once in [CI](../../../development/testing/ci.md) and deploy those artifacts.
- Keep configuration and secrets outside the codebase.
- Make database changes predictable.
- Wherever possible, clearly separate build-time concerns from runtime concerns to ensure consistency across environments.
diff --git a/guides/hosting/installation-updates/performing-updates.md b/guides/hosting/installation-updates/performing-updates.md
index 7ff97d8162..e780332f5d 100644
--- a/guides/hosting/installation-updates/performing-updates.md
+++ b/guides/hosting/installation-updates/performing-updates.md
@@ -30,7 +30,7 @@ Before any update, check if the installed extensions are compatible with the new
shopware-cli project upgrade-check
```
-This command checks your installed extensions against the target Shopware version. If an extension is not compatible, check with the extension developer if an update is available. If you don't have shopware-cli installed, see the [installation guide](../../../products/cli/installation.md).
+This command checks your installed extensions against the target Shopware version. If an extension is not compatible, check with the extension developer if an update is available. If you don't have the Shopware CLI installed, see the [installation guide](../../../products/cli/index.md).
Managing all extensions through Composer is the best way to ensure compatibility. It simplifies the update process as Composer automatically resolves the correct versions of the extensions.
@@ -54,7 +54,7 @@ bin/console sales-channel:maintenance:enable --all
For major updates, consider the following additional preparations:
-- **Update PHP version**: Update the PHP version to the minimum required version for the new Shopware version *before* updating Shopware. Shopware versions always support an overlapping PHP version, so this is safe to do beforehand. You can find the minimum required PHP version in the [System Requirements](../../installation/requirements.md).
+- **Update PHP version**: Update the PHP version to the minimum required version for the new Shopware version *before* updating Shopware. Shopware versions always support an overlapping PHP version, so this is safe to do beforehand. You can find the minimum required PHP version in the [System Requirements guide](../../installation/system-requirements.md).
- **Check upgrade changes**: Review the [UPGRADE.md](https://github.com/search?q=repo%3Ashopware%2Fshopware+UPGRADE-6+language%3AMarkdown+NOT+path%3A%2F%5Eadr%5C%2F%2F+NOT+path%3A%2F%5Echangelog%5C%2F%2F&type=code&l=Markdown) for all breaking changes and migration instructions.
- **Update extensions first**: Update all extensions to their latest versions before updating Shopware to ensure a smooth transition. After updating Shopware, update all extensions again to get versions compatible with the new Shopware version.
diff --git a/guides/hosting/performance/lock-store.md b/guides/hosting/performance/lock-store.md
index ac2109343b..b575e41069 100644
--- a/guides/hosting/performance/lock-store.md
+++ b/guides/hosting/performance/lock-store.md
@@ -5,14 +5,14 @@ nav:
---
-# Lock store
+# Lock Storage
Shopware uses [Symfony's lock component](https://symfony.com/doc/5.x/lock.html) to implement locking functionality.
By default, Symfony will use a local lock store. This means in multi-machine (cluster) setups, naive file locks will break the system; therefore, it is highly recommended to use one of the [supported remote stores](https://symfony.com/doc/5.x/components/lock.html#available-stores).
## Using Redis as a lock store
-As Redis can already be used for [caching](./caches), [increment store](./increment), and [session storage](./session), you can also use that Redis host as a remote lock store.
+As Redis can already be used for [caching](caches.md), [increment store](increment.md), and [session storage](session.md), you can also use that Redis host as a remote lock store.
To use Redis, configure the lock store to use a Redis DSN. Create a `config/packages/lock.yaml` file with the following content:
```yaml
diff --git a/resources/guidelines/troubleshooting/performance.md b/guides/hosting/performance/performance.md
similarity index 92%
rename from resources/guidelines/troubleshooting/performance.md
rename to guides/hosting/performance/performance.md
index c384260613..8d58c43918 100644
--- a/resources/guidelines/troubleshooting/performance.md
+++ b/guides/hosting/performance/performance.md
@@ -1,11 +1,11 @@
---
nav:
- title: Performance
- position: 20
+ title: Troubleshooting
+ position: 80
---
-# Performance
+# Troubleshooting
## Common Performance Considerations
@@ -15,7 +15,7 @@ When you use a `contains` filter in dynamic product groups (especially when you
The reason is that the underlying SQL query is not and cannot be optimized for this kind of filter.
When you use OpenSearch instead of relying on the DB for searching, this issue should be resolved.
Alternatively, for using `contains` on custom fields, it should be preferred to create individual bool custom fields for the different values and check those instead.
-When contains on usual fields is used and slow, it should help to add a [custom field](../../../guides/plugins/plugins/framework/custom-field/index) and manually manage that.
+When contains on usual fields is used and slow, it should help to add a [custom field](../../plugins/plugins/framework/custom-field/index.md) and manually manage that.
Alternatively, [tags](https://docs.shopware.com/en/shopware-6-en/settings/tags) can be used for this purpose.
### Cache is invalided too often
@@ -36,7 +36,7 @@ If the `APP_ENV` is set to `dev` Shopware keeps many objects for debugging purpo
If the memory usage issue persists after setting `APP_ENV` to `prod`, check if you are using the [sync API](https://shopware.stoplight.io/docs/admin-api/faf8f8e4e13a0-bulk-payloads).
Also consider changing the `indexing-behavior` to your needs if you need to sync many entities.
Another reason for high memory usage might be the logging within the application.
-See the logging section in the [performance guide](../../../guides/hosting/performance/performance-tweaks#logging) for more information.
+See the logging section in the [performance guide](../../../guides/hosting/performance/performance-tweaks.md#logging) for more information.
After all, you still can make use of tools like blackfire.io to find the root cause of the memory usage.
### Session Deadlocks with file-based sessions
@@ -49,7 +49,7 @@ Symptoms include:
* PHP processes stuck in "waiting" state
* Issues appearing only under concurrent requests
-The recommended solution is to [use Redis for sessions](../../../guides/hosting/performance/session), which eliminates the file-based locking conflict.
+The recommended solution is to [use Redis for sessions](../../../guides/hosting/performance/session.md), which eliminates the file-based locking conflict.
If Redis is not available in your environment, you can work around the issue by disabling cache stampede protection (option available since Shopware 6.7.7.0).
```yaml
diff --git a/guides/installation/legacy-setups/devenv-setup.md b/guides/installation/legacy-setups/devenv-setup.md
index daa4c3969e..2627c3d0bd 100644
--- a/guides/installation/legacy-setups/devenv-setup.md
+++ b/guides/installation/legacy-setups/devenv-setup.md
@@ -21,9 +21,9 @@ Devenv provides project-local PHP, Node, Composer, and services via Nix, so you
On the host, you only need a minimal toolchain:
-- [Nix package manager](https://nixos.org/download.html)
-- Git
-- Docker Engine, only if you plan to run additional containerized services alongside Devenv (Optional)
+* [Nix package manager](https://nixos.org/download.html)
+* Git
+* Docker Engine, only if you plan to run additional containerized services alongside Devenv (Optional)
See the [Shopware 6 requirements](../system-requirements.md) for general system requirements and supported versions. Devenv will provide the exact runtime versions per project.
@@ -205,8 +205,8 @@ Once installation completes, open `http://localhost:8000/admin` in your browser.
The default credentials are:
-- User: `admin`
-- Password: `shopware`
+* User: `admin`
+* Password: `shopware`
::: info
On Windows with WSL2, change the default sales channel domain to `http://localhost:8000`. Use *http*, not https.
@@ -355,8 +355,8 @@ export LANG=en_US.UTF-8
Default credentials:
-- User: `shopware`
-- Password: `shopware`
+* User: `shopware`
+* Password: `shopware`
### Mailhog
@@ -421,4 +421,4 @@ Do not commit service tokens or credentials to version control. Store secrets in
## Detailed configurations
-You can find more detailed configurations for your devenv setup in the [Additional Devenv Options](devenv-options) article.
+You can find more detailed configurations for your devenv setup in the [Additional Devenv Options](devenv-options.md) article.
diff --git a/guides/installation/legacy-setups/migrate-zip-to-composer-project.md b/guides/installation/legacy-setups/migrate-zip-to-composer-project.md
new file mode 100644
index 0000000000..30e9dc6ee8
--- /dev/null
+++ b/guides/installation/legacy-setups/migrate-zip-to-composer-project.md
@@ -0,0 +1,151 @@
+---
+nav:
+ title: Migrate Zip Installation to Composer Project
+ position: 100
+---
+
+# Migrate from Zip Installation to Composer Project Template
+
+:::info
+This guide only applies to legacy Shopware installations created before version 6.5 using the deprecated zip distribution. For new projects, use the recommended [CLI installation with Docker setup](../../installation/index.md).
+:::
+
+## Background
+
+Before Shopware 6.5, Shopware was distributed for installation as a zip archive containing all required dependencies. This approach has been replaced by a Composer-based project template using Symfony Flex.
+
+The modern setup provides:
+
+* Proper dependency management
+* Cleaner configuration handling
+* Symfony Flex integration
+* Easier CI/CD workflows
+* Better extension management
+
+## Automatic migration (Recommended)
+
+With Shopware CLI, automatic migration is possible:
+
+```bash
+shopware-cli project autofix flex
+```
+
+This converts the installation to a Symfony Flex-based project structure.
+
+## Manual migration
+
+If automatic migration is not possible, follow these steps.
+
+### 1. Create a Backup
+
+Before making any changes:
+
+* Ensure a clean Git state
+* Either stash everything, or create a full backup of files and database
+
+### 2. Adjust Root `composer.json`
+
+Add the Symfony Flex configuration:
+
+First, adjust your root `composer.json`. Add the following lines to your `composer.json`:
+
+```json
+"extra": {
+ "symfony": {
+ "allow-contrib": true,
+ "endpoint": [
+ "https://raw.githubusercontent.com/shopware/recipes/flex/main/index.json",
+ "flex://defaults"
+ ]
+ }
+}
+```
+
+Next, replace all the existing scripts:
+
+```json
+"scripts": {
+ "auto-scripts": [],
+ "post-install-cmd": [
+ "@auto-scripts"
+ ],
+ "post-update-cmd": [
+ "@auto-scripts"
+ ]
+}
+```
+
+Finally, remove any fixed PHP platform configuration as it will now be determined by the required packages:
+
+```diff
+"config": {
+ "optimize-autoloader": true,
+- "platform": {
+- "php": "7.4.3"
+- },
+ "sort-packages": true,
+ "allow-plugins": {
+ "composer/package-versions-deprecated": true
+ }
+},
+```
+
+### 3. Clean up legacy template files
+
+After installing the new Composer packages, remove obsolete files:
+
+```bash
+rm -r .dockerignore \
+ .editorconfig \
+ .env.dist \
+ .github \
+ .gitlab-ci \
+ .gitlab-ci.yml \
+ Dockerfile \
+ docker-compose.yml \
+ easy-coding-standard.php \
+ PLATFORM_COMMIT_SHA \
+ artifacts \
+ bin/deleted_files_vendor.sh \
+ bin/entrypoint.sh \
+ bin/package.sh \
+ config/etc \
+ src \
+ config/secrets \
+ config/services \
+ config/services.xml \
+ config/services_test.xml \
+ license.txt \
+ phpstan.neon \
+ phpunit.xml.dist \
+ psalm.xml
+```
+
+Create a fresh environment file:
+
+```bash
+touch .env
+```
+
+### 4. Install required Composer packages
+
+Ensure Composer is installed before proceeding. Follow the [official documentation](https://getcomposer.org/doc/00-intro.md#installation-linux-unix-macos) for instructions.
+
+To install Symfony Flex, run the following commands and allow both new Composer plugins:
+
+```bash
+composer require "symfony/flex:*" "symfony/runtime:*"
+
+composer recipe:install --force --reset
+```
+
+### 5. Update environment variables
+
+Adjusting environment variables may be necessary as the names have changed:
+
+| **Old name** | **New name** |
+|-------------------|----------------|
+| MAILER_URL | MAILER_DSN |
+| SHOPWARE_ES_HOSTS | OPENSEARCH_URL |
+
+After reviewing the changes, commit them to the Git repository. All upcoming config changes can be applied with `composer recipes:update`.
diff --git a/guides/plugins/apps/administration/add-cms-element-via-admin-sdk.md b/guides/plugins/apps/administration/add-cms-element-via-admin-sdk.md
index 126fc9c59f..5051ad43a9 100644
--- a/guides/plugins/apps/administration/add-cms-element-via-admin-sdk.md
+++ b/guides/plugins/apps/administration/add-cms-element-via-admin-sdk.md
@@ -7,6 +7,8 @@ nav:
# 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.
@@ -14,7 +16,7 @@ This guide explains how to create a new CMS element using the Meteor Admin SDK.
* 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](/resources/admin-extension-sdk/getting-started/installation)
+* Understanding of the [Meteor Admin SDK](meteor-admin-sdk.md)
::: info
This example uses TypeScript, which is recommended but not required to develop Shopware.
@@ -145,7 +147,7 @@ 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 recommended to take a look at the documentation of the
-[Meteor Admin SDK](/resources/admin-extension-sdk/concepts/locations) to learn more about its concepts.
+[Meteor Admin SDK](meteor-admin-sdk.md) 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`.
@@ -366,12 +368,11 @@ export default Vue.extend({
## 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:
+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:
+
`/Resources/views/storefront/element/.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
+For more details, see the guide on [CMS element development for plugins](../../plugins/content/cms/add-cms-element.md). Below is an example of how your Storefront template
(`swag-dailymotion/Resources/views/storefront/element/cms-element-swag-dailymotion.html.twig`) could look:
```twig
diff --git a/guides/plugins/apps/administration/add-custom-action-button.md b/guides/plugins/apps/administration/add-custom-action-button.md
index 4f9b790a51..f6549d4436 100644
--- a/guides/plugins/apps/administration/add-custom-action-button.md
+++ b/guides/plugins/apps/administration/add-custom-action-button.md
@@ -7,11 +7,11 @@ nav:
# 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](meteor-admin-sdk.md) is recommended. It has many more features and is more flexible.
+## 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:
@@ -334,4 +334,4 @@ And then add the corresponding app script that should be executed when the user
{% 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).
+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).
diff --git a/guides/plugins/apps/administration/add-custom-modules.md b/guides/plugins/apps/administration/add-custom-modules.md
index 26833115a5..c3d778adfd 100644
--- a/guides/plugins/apps/administration/add-custom-modules.md
+++ b/guides/plugins/apps/administration/add-custom-modules.md
@@ -1,17 +1,17 @@
---
nav:
- title: Add custom module
+ title: Add Custom Module
position: 20
---
-# Add custom module
+# Add Custom Module
+
+## Overview
-:::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](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
@@ -19,8 +19,6 @@ You should be familiar with the concept of Apps, especially their registration f
-## 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 `` 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 `` elements to your manifest.
@@ -120,7 +118,7 @@ class ModuleController {
## 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.
+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() {
diff --git a/guides/plugins/apps/app-base-guide.md b/guides/plugins/apps/app-base-guide.md
index a8aae09a3c..ea343c469f 100644
--- a/guides/plugins/apps/app-base-guide.md
+++ b/guides/plugins/apps/app-base-guide.md
@@ -7,6 +7,8 @@ nav:
# 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:
diff --git a/guides/plugins/apps/app-scripts/add-api-endpoint.md b/guides/plugins/apps/app-scripts/add-api-endpoint.md
index 64ea8e4318..3c7b3f13bd 100644
--- a/guides/plugins/apps/app-scripts/add-api-endpoint.md
+++ b/guides/plugins/apps/app-scripts/add-api-endpoint.md
@@ -1,16 +1,18 @@
---
nav:
- title: Starter Guide - Add an API endpoint
+ title: Add an API endpoint
position: 20
---
-# Starter Guide - Add an API Endpoint
+# Add an API Endpoint
::: info
-Note that this guide relies on [App scripts](../app-scripts/), introduced from Shopware 6.4.8.0 version.
+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:
@@ -24,7 +26,7 @@ After reading, you will be able to:
* A Shopware cloud store
* Basic CLI usage (creating files, directories, running commands)
-* Installed and configured [shopware-cli](../../../../products/cli/) tools
+* Installed and configured [shopware-cli](../../../../products/cli/index.md) tools
* General knowledge of [Twig Syntax](https://twig.symfony.com/)
* A text editor
@@ -72,7 +74,7 @@ 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/).
+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:
@@ -86,7 +88,7 @@ The prefix for our API endpoint is one of the following and cannot be changed:
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)
+Learn more about the different endpoints in [custom endpoints](../app-scripts/custom-endpoints.md)
:::
### Directory structure
@@ -129,7 +131,7 @@ Let's start with a simple script to see it in action:
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/cli/installation) it first. Next, configure it using the `shopware-cli project config init` command.
+If this is your first time using the Shopware CLI, you have to [install](../../../../products/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.
@@ -223,9 +225,7 @@ In the following lines, we define a search criteria. The criteria contain a desc
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, follow the link below:
-
-[Search Criteria](../../../development/integrations-api/search-criteria.md)
+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:
@@ -325,6 +325,6 @@ In a proper app, you should consider the following points:
## Where to continue
-* More on adding [custom endpoints](../app-scripts/custom-endpoints)
-* See how you can use [Twig functions](../app-scripts/#extended-syntax) in app scripts
+* 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)
diff --git a/guides/plugins/apps/app-scripts/cart-manipulation.md b/guides/plugins/apps/app-scripts/cart-manipulation.md
index 8b8f1a6b1a..38361fee09 100644
--- a/guides/plugins/apps/app-scripts/cart-manipulation.md
+++ b/guides/plugins/apps/app-scripts/cart-manipulation.md
@@ -7,22 +7,21 @@ nav:
# Manipulate the Cart with App Scripts
-If your app needs to manipulate the cart, you can do so by using the [`cart`](../../../../resources/references/app-reference/script-reference/script-hooks-reference#cart) script hook.
+## Overview
+
+If your app needs to modify the cart, you can use the [`cart`](../../../../resources/references/app-reference/script-reference/script-hooks-reference.md#cart) script hook. App scripts extend the general [cart concept](../../../../concepts/commerce/checkout-concept/cart.md) by acting as another [cart processor](../../../../concepts/commerce/checkout-concept/cart.md#cart-processors---price-calculation-and-validation).
::: info
Note that app scripts were introduced in Shopware 6.4.8.0 and are not supported in previous versions.
:::
-## Overview
-
-The cart manipulation in app scripts expands on the general [cart concept](../../../../concepts/commerce/checkout-concept/cart). In that concept, your cart scripts act as another [cart processor](../../../../concepts/commerce/checkout-concept/cart#cart-processors---price-calculation-and-validation).
+Your `cart` scripts run whenever the cart is calculated. For example, they are executed when an item is added to the cart or when the selected shipping or payment method changes.
-Your `cart` scripts run whenever the cart is calculated, this means that the script will be executed when an item is added to the cart, when the selected shipping and payment methods change, etc.
-You have access to a `cart`-service that provides a [fluent API](https://www.martinfowler.com/bliki/FluentInterface.html) to get data from the cart or to manipulate the cart. For an overview of all data and services that are available, please refer to the [cart hook reference](../../../../resources/references/app-reference/script-reference/script-hooks-reference#cart).
+You have access to a `cart`-service that provides a [fluent API](https://www.martinfowler.com/bliki/FluentInterface.html) for reading data from the cart and modifying it. For an overview of all available data and services, see the [cart hook reference](../../../../resources/references/app-reference/script-reference/script-hooks-reference.md#cart).
## Prerequisites
-To get a better understanding of the cart, please make yourself familiar with the [cart concept](../../../../concepts/commerce/checkout-concept/cart) in general.
+To get a better understanding of the cart, please make yourself familiar with the [cart concept](../../../../concepts/commerce/checkout-concept/cart.md) in general.
We will expand on that concept and refer to ideas defined there in this guide.
## Calculating the cart
@@ -39,7 +38,7 @@ But if your script depends on updated and recalculated prices, you can recalcula
{% do services.cart.calculate() %}
```
-The `calculate()` call will recalculate the whole cart and update the total prices, etc. For this the complete [`process`-step](../../../../concepts/commerce/checkout-concept/cart#calculation) is executed again.
+The `calculate()` call will recalculate the whole cart and update the total prices, etc. For this the complete [`process`-step](../../../../concepts/commerce/checkout-concept/cart.md#calculation) is executed again.
::: warning
Note that by executing the `process` step, all properties of the cart (e.g. `products()`, `items()`, `price()`) are recreated and thus will return new instances.
@@ -93,7 +92,7 @@ In general, Shopware prices consist of gross and net prices and are currency dep
### Price fields inside custom fields
-You can define price fields for [custom fields](../custom-data/custom-fields)
+You can define price fields for [custom fields](../custom-data/custom-fields.md)
::: code-group
@@ -152,7 +151,7 @@ You can specify the `gross` and `net` prices for each currency.
### Prices inside the app config
-As described above, it is also possible to use price fields inside the [app configuration](../lifecycle/configuration.md). In your cart scripts, you can access those config values over the [`config` service](../../../../resources/references/app-reference/script-reference/miscellaneous-script-services-reference#SystemConfigFacade) and pass them to the same price factory as the manual definitions.
+As described above, it is also possible to use price fields inside the [app configuration](../lifecycle/configuration.md). In your cart scripts, you can access those config values over the [`config` service](../../../../resources/references/app-reference/script-reference/miscellaneous-script-services-reference.md#servicesconfig-shopwarecoresystemsystemconfigfacadesystemconfigfacade-systemconfigfacade) and pass them to the same price factory as the manual definitions.
```twig
// Resources/scripts/cart/my-cart-script.twig
diff --git a/guides/plugins/apps/app-scripts/custom-endpoints.md b/guides/plugins/apps/app-scripts/custom-endpoints.md
index 3a399b2752..47e5283a26 100644
--- a/guides/plugins/apps/app-scripts/custom-endpoints.md
+++ b/guides/plugins/apps/app-scripts/custom-endpoints.md
@@ -7,7 +7,9 @@ nav:
# 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.
+## 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
diff --git a/guides/plugins/apps/app-scripts/data-loading.md b/guides/plugins/apps/app-scripts/data-loading.md
index 2fa25c42c2..7627bff8b9 100644
--- a/guides/plugins/apps/app-scripts/data-loading.md
+++ b/guides/plugins/apps/app-scripts/data-loading.md
@@ -7,26 +7,27 @@ nav:
# Load Additional Data for the Storefront with App Scripts
-If your app needs additional data in your [customized Storefront templates](../../plugins/storefront/templates/customize-templates.md), you can load that data with app scripts and make it available to your template.
+## Overview
+
+If your app needs additional data in your [customized Storefront templates](../../plugins/storefront/templates/customize-templates.md), you can load that data with app scripts and make it available to your templates.
::: info
-Note that app scripts were introduced in Shopware 6.4.8.0 and are not supported in previous versions.
+App scripts were introduced in Shopware 6.4.8.0 and are not supported in previous versions.
:::
-## Overview
+## How data loading works
+
+The app script data-loading feature builds on the general [composite data-loading concept](../../../../concepts/framework/architecture/storefront-concept.md#composite-data-handling) of the Storefront.
-The app script data-loading feature builds on the general [composite data-loading concept](../../../../concepts/framework/architecture/storefront-concept.md#composite-data-handling) of the storefront.
-For each page that is rendered, a hook is triggered, giving access to the current `page` object. The `page` object provides access to all available data, lets you add data to it, and is passed directly to the templates.
+For each rendered page, a hook is triggered that gives you access to the current `page` object. The `page` object provides access to all available data, lets you add data, and is passed directly to the templates.
-For a list of all available script hooks that can be used to load additional data, take a look at the [script hook reference](../../../../resources/references/app-reference/script-reference/script-hooks-reference.md#data-loading).
+For a list of all available script hooks that can be used to load additional data, see the [script hook reference](../../../../resources/references/app-reference/script-reference/script-hooks-reference.md#data-loading).
::: info
-Note that all hooks that were triggered during a page rendering are also shown in the [Symfony toolbar](../app-scripts/index.md#developingdebugging-scripts).
-This may come in handy if you are searching for the right hook for your script.
+All hooks triggered during page rendering are also shown in the [Symfony toolbar](../app-scripts/index.md#developingdebugging-scripts). This can be useful when searching for the right hook for your script.
:::
-For example, if you want to enrich a storefront detail page with additional data, you just set it within a custom app script and attach it to the `page` object.
-.0
+For example, if you want to enrich a Storefront detail page with additional data, you can set that data in a custom app script and attach it to the `page` object:
```twig
// Resources/scripts/product-page-loaded/my-example-script.twig
diff --git a/guides/plugins/apps/app-scripts/index.md b/guides/plugins/apps/app-scripts/index.md
index b1230cf2ab..7feda38c0c 100644
--- a/guides/plugins/apps/app-scripts/index.md
+++ b/guides/plugins/apps/app-scripts/index.md
@@ -7,7 +7,7 @@ nav:
# 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.
+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.
@@ -23,7 +23,7 @@ See the [Hooks reference](../../../../resources/references/app-reference/script-
## 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.
+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.
diff --git a/guides/plugins/apps/app-sdks/index.md b/guides/plugins/apps/app-sdks/index.md
index 4f7f3d2653..5b5edcbcd5 100644
--- a/guides/plugins/apps/app-sdks/index.md
+++ b/guides/plugins/apps/app-sdks/index.md
@@ -8,3 +8,9 @@ nav:
# 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 |
diff --git a/guides/plugins/apps/app-sdks/symfony-bundle/index.md b/guides/plugins/apps/app-sdks/symfony-bundle/index.md
index a5886c97de..19db57705f 100644
--- a/guides/plugins/apps/app-sdks/symfony-bundle/index.md
+++ b/guides/plugins/apps/app-sdks/symfony-bundle/index.md
@@ -1,11 +1,11 @@
---
nav:
- title: Official Symfony bundle
+ title: Official Symfony Bundle
position: 10
---
-# App Bundle
+# Official Symfony Bundle
The App Bundle integrates the PHP App SDK with Symfony. The source repository is [app-bundle-symfony](https://github.com/shopware/app-bundle-symfony).
diff --git a/guides/plugins/apps/checkout/payment.md b/guides/plugins/apps/checkout/payment.md
index ba19963e96..8b3cf49ccb 100644
--- a/guides/plugins/apps/checkout/payment.md
+++ b/guides/plugins/apps/checkout/payment.md
@@ -7,6 +7,8 @@ nav:
# Payment
+## Overview
+
Starting with version `6.4.1.0`, Shopware also provides functionality for your app to be able to integrate payment providers.
You can choose between just a simple request for approval in the background \(synchronous payment\) and the customer being forwarded to a provider for payment \(asynchronous payment\).
You provide one or two endpoints, one for starting the payment and providing a redirect URL and one for finalization to check for the resulting status of the payment.
diff --git a/guides/plugins/apps/checkout/shipping-methods.md b/guides/plugins/apps/checkout/shipping-methods.md
index de221117b4..23feec5661 100644
--- a/guides/plugins/apps/checkout/shipping-methods.md
+++ b/guides/plugins/apps/checkout/shipping-methods.md
@@ -7,6 +7,8 @@ nav:
# Shipping Methods
+## Overview
+
Starting with version 6.5.7.0 as **experimental feature**. Shopware has introduced experimental functionality for adding shipping methods via the App Manifest to a shop. **The entire functionality and API are subject to change during the development process.**
## Prerequisites
diff --git a/guides/plugins/apps/checkout/tax-provider.md b/guides/plugins/apps/checkout/tax-provider.md
index 406ab4a07b..b172acf6aa 100644
--- a/guides/plugins/apps/checkout/tax-provider.md
+++ b/guides/plugins/apps/checkout/tax-provider.md
@@ -7,6 +7,8 @@ nav:
# Tax Provider
+## Overview
+
Tax calculations differ from country to country. Especially in the US, the sales tax calculation can be tedious, as the laws and regulations differ from state to state, country-wise, or even based on cities. Therefore, most shops use a third-party service (so-called tax provider) to calculate sales taxes.
With version 6.5.0.0, Shopware allows apps to integrate custom tax calculations, which could include an automatic tax calculation with a tax provider. An app has to provide an endpoint, which is called during the checkout to provide new tax rates. The requests and responses of all of your endpoints will be signed and featured as JSON content.
diff --git a/guides/plugins/apps/content/cms/add-custom-cms-blocks.md b/guides/plugins/apps/content/cms/add-custom-cms-blocks.md
index 896869fb4f..f28cafc734 100644
--- a/guides/plugins/apps/content/cms/add-custom-cms-blocks.md
+++ b/guides/plugins/apps/content/cms/add-custom-cms-blocks.md
@@ -1,30 +1,32 @@
---
nav:
- title: Add custom CMS blocks
+ title: Add Custom CMS Blocks
position: 10
---
-# Add custom CMS blocks
+# Add Custom CMS Blocks
::: info
This functionality is available starting with Shopware 6.4.4.0.
+::: info
-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.
-:::
+## Overview
-Didn't get in touch with Shopware's Shopping Experiences \(CMS\) yet? Check out the concept behind it first:
+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) and assumes you have already set up an app.
+This guide is based on our [App Base Guide](../../app-base-guide.md) and assumes you have already set up an app.
-## Overview
+## 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.
-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
@@ -47,9 +49,7 @@ The basic directory structure looks as follows:
└── 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`.
+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.
@@ -59,8 +59,7 @@ The Storefront representations of your blocks reside in `Resources/views/storefr
## 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:
+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
// /Resources/cms.xml
@@ -115,7 +114,7 @@ Let's have a look at how to configure a CMS block from your app's `cms.xml`:
`` : A **unique** technical name for your block.
-`` : 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).
+`` : 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).
`