From e062c8ecadc67cff4323f6d138824919597b328a Mon Sep 17 00:00:00 2001 From: LApple Date: Thu, 7 May 2026 18:24:41 +0200 Subject: [PATCH 01/39] chore: adds last changes from mega-PR --- .gitbook.yaml | 18 +- concepts/framework/data-abstraction-layer.md | 2 +- concepts/framework/elasticsearch.md | 2 +- .../built-in-translation-system.md | 3 +- .../fallback-language-selection.md | 4 +- .../accessibility/storefront-accessibility.md | 4 +- .../extensions/architecture/extendability.md | 4 +- .../architecture/final-and-internal.md | 4 +- .../extensions/architecture/index.md | 2 + .../extensions/architecture/internal.md | 2 + .../development/extensions/code-structure.md | 13 +- guides/development/extensions/index.md | 4 +- guides/development/monetization/index.md | 2 +- guides/development/testing/ci.md | 6 +- .../development/testing/testing-guidelines.md | 2 +- guides/development/testing/unit/jest-admin.md | 2 +- .../testing/unit/jest-storefront.md | 2 +- guides/development/testing/unit/php-unit.md | 2 +- .../fields-reference/enum-field.md | 6 +- .../troubleshooting/dal-reference/index.md | 9 + .../development}/troubleshooting/phpstan.md | 10 +- .../troubleshooting/rules-reference.md | 2 +- .../elasticsearch/elasticsearch-debugging.md | 10 +- .../elasticsearch/elasticsearch-setup.md | 2 +- .../elasticsearch}/elasticsearch.md | 20 +- .../infrastructure/elasticsearch/index.md | 4 +- guides/hosting/infrastructure/filesystem.md | 2 +- guides/hosting/infrastructure/index.md | 2 +- .../hosting/infrastructure/message-queue.md | 8 +- .../infrastructure/optional-packages.md | 35 +++ guides/hosting/infrastructure/rate-limiter.md | 2 +- guides/hosting/infrastructure/redis.md | 2 +- .../infrastructure/reverse-http-cache.md | 2 +- .../hosting/infrastructure/scheduled-task.md | 6 +- .../deployments/build-w-o-db.md | 4 +- .../deployments/deployment-with-deployer.md | 2 +- .../installation-updates/deployments/index.md | 2 +- .../performing-updates.md | 2 +- guides/hosting/performance/lock-store.md | 2 +- .../hosting/performance}/performance.md | 6 +- .../legacy-setups/devenv-setup.md | 6 +- .../migrate-zip-to-composer-project.md | 151 ++++++++++++ .../add-cms-element-via-admin-sdk.md | 2 + .../add-custom-action-button.md | 6 +- .../apps/administration/add-custom-modules.md | 10 +- guides/plugins/apps/app-base-guide.md | 2 + .../apps/app-scripts/add-api-endpoint.md | 8 +- .../apps/app-scripts/cart-manipulation.md | 2 + .../apps/app-scripts/custom-endpoints.md | 4 +- .../plugins/apps/app-scripts/data-loading.md | 2 + guides/plugins/apps/app-sdks/index.md | 6 + .../apps/app-sdks/symfony-bundle/index.md | 4 +- guides/plugins/apps/checkout/payment.md | 2 + .../plugins/apps/checkout/shipping-methods.md | 2 + guides/plugins/apps/checkout/tax-provider.md | 2 + .../apps/content/cms/add-custom-cms-blocks.md | 16 +- guides/plugins/apps/content/cms/index.md | 1 + guides/plugins/apps/create-admin-extension.md | 2 + .../apps/custom-data/custom-entities.md | 12 +- .../plugins/apps/custom-data/custom-fields.md | 9 +- ...add-custom-flow-actions-from-app-system.md | 2 + ...dd-custom-flow-triggers-from-app-system.md | 2 + .../in-app-purchase-gateway.md | 15 +- .../apps/lifecycle/app-registration-setup.md | 2 + .../lifecycle/app-signature-verification.md | 2 + .../lifecycle/clientside-to-app-backend.md | 2 + .../plugins/apps/lifecycle/configuration.md | 2 + .../apps/lifecycle/product-translator.md | 8 +- guides/plugins/apps/lifecycle/webhook.md | 4 +- .../add-custom-rule-conditions.md | 2 + .../plugins/apps/storefront/apps-as-themes.md | 7 +- .../apps/storefront/cookies-with-apps.md | 2 + .../apps/storefront/customize-templates.md | 2 +- .../administration-reference/directives.md | 2 +- .../administration-reference/mixins.md | 2 +- .../administration-reference/utils.md | 2 +- .../add-rule-assignment-configuration.md | 4 +- .../advanced-configuration/add-shortcuts.md | 2 +- ...fy-blacklist-for-dynamic-product-groups.md | 2 +- .../handling-media.md | 8 +- .../search-custom-data.md | 4 +- .../the-shopware-object.md | 4 +- .../using-custom-fields.md | 4 +- .../using-data-handling.md | 6 +- .../using-the-data-grid-component.md | 4 +- .../using-vuex-state.md | 8 + .../mixins-directives/using-mixins.md | 6 +- .../add-custom-component.md | 4 +- .../add-custom-field.md | 6 +- .../add-custom-module.md | 6 +- .../customizing-components.md | 6 +- .../customizing-modules.md | 4 +- .../module-component-management/index.md | 6 +- .../using-base-components.md | 6 +- .../add-acl-rules.md | 4 +- .../add-error-handling.md | 6 +- .../routing-navigation/add-custom-route.md | 6 +- .../routing-navigation/add-menu-entry.md | 4 +- .../routing-navigation/add-new-tab.md | 6 +- .../routing-navigation/overriding-routes.md | 4 +- .../services-utilities/add-filter.md | 8 +- .../services-utilities/extending-services.md | 6 +- .../services-utilities/injecting-services.md | 17 +- .../services-utilities/making-api-requests.md | 2 +- .../the-sanitizer-helper.md | 9 +- .../services-utilities/using-filter.md | 6 +- .../services-utilities/using-utils.md | 8 +- .../templates-styling/add-custom-styles.md | 4 +- .../adding-responsive-behavior.md | 6 +- guides/plugins/plugins/bundle.md | 40 ++-- .../cart/add-cart-processor-collector.md | 2 +- .../cart/customize-price-calculation.md | 2 + .../plugins/content/cms/add-cms-block.md | 6 +- .../plugins/content/cms/add-cms-element.md | 8 +- .../content/cms/add-data-to-cms-elements.md | 4 +- .../media/add-custom-file-extension.md | 2 + .../media/remote-thumbnail-generation.md | 2 + .../sitemap/add-custom-sitemap-entries.md | 4 +- .../content/sitemap/remove-sitemap-entries.md | 4 +- guides/plugins/plugins/creating-plugins.md | 219 ++++++++++++++++++ .../database/custom-fields-of-type-media.md | 4 +- .../plugins/database/database-migrations.md | 2 + .../dependencies/add-plugin-dependencies.md | 6 +- .../using-composer-dependencies.md | 4 +- .../dependencies/using-npm-dependencies.md | 2 +- .../plugins/framework/caching/index.md | 2 + .../data-handling/add-data-indexer.md | 6 +- .../data-handling/entities-via-attributes.md | 5 +- .../framework/data-handling/reading-data.md | 8 +- .../data-handling/using-database-events.md | 2 + .../framework/data-handling/using-flags.md | 4 +- .../data-handling/versioning-entities.md | 2 + .../framework/data-handling/writing-data.md | 2 + .../framework/event/listening-to-events.md | 2 + .../framework/filesystem/filesystem.md | 12 +- .../plugins/framework/filesystem/index.md | 6 +- .../framework/flow/action-transactions.md | 4 +- .../framework/flow/add-flow-builder-action.md | 2 +- .../flow/add-flow-builder-trigger.md | 6 +- guides/plugins/plugins/framework/index.md | 16 +- .../message-queue/add-message-handler.md | 4 +- .../message-queue/add-message-to-queue.md | 4 +- .../framework/message-queue/add-middleware.md | 2 +- .../add-rate-limiter-to-api-route.md | 2 + .../framework/rule/add-custom-rules.md | 2 +- .../plugins/framework/store-api/index.md | 30 ++- .../store-api/override-existing-route.md | 2 +- .../system-check/add-custom-check.md | 6 +- guides/plugins/plugins/index.md | 140 +++++++---- .../plugins/install-activate-plugin.md | 55 +++++ .../commercial/customer-specific-pricing.md | 4 +- .../plugins/integrations/commercial/index.md | 2 +- .../commercial/multi-inventory.md | 4 + ...oduct-entity-extension-to-elasticsearch.md | 2 +- guides/plugins/plugins/integrations/index.md | 15 ++ guides/plugins/plugins/plugin-base-guide.md | 213 ++--------------- .../add-custom-commands.md | 4 +- .../add-plugin-configuration.md | 43 ++-- .../plugin-fundamentals/add-scheduled-task.md | 4 +- .../plugins/plugin-fundamentals/logging.md | 7 + .../plugin-fundamentals/plugin-lifecycle.md | 157 +++++++------ .../use-plugin-configuration.md | 2 +- .../plugins/services/add-custom-service.md | 2 + .../plugins/services/adjusting-service.md | 2 +- .../plugins/services/dependency-injection.md | 2 +- .../plugins/storefront/advanced/index.md | 4 +- .../controllers/add-custom-controller.md | 2 + .../storefront/controllers/add-custom-page.md | 2 + .../controllers/add-custom-pagelet.md | 2 + .../add-data-to-storefront-page.md | 2 + .../add-dynamic-content-via-ajax-calls.md | 2 + .../plugins/storefront/controllers/index.md | 3 +- .../storefront/howto/add-custom-captcha.md | 2 + .../add-custom-sorting-product-listing.md | 2 + .../storefront/howto/add-listing-filters.md | 4 +- .../storefront/howto/use-media-thumbnails.md | 2 + .../storefront/howto/use-nested-line-items.md | 2 + .../storefront/howto/using-a-modal-window.md | 2 + .../howto/using-custom-fields-storefront.md | 2 + .../howto/using-the-datepicker-plugin.md | 2 + guides/plugins/plugins/storefront/index.md | 92 +++++++- .../javascript/add-custom-javascript.md | 2 + .../add-javascript-as-script-tag.md | 4 +- .../fetching-data-with-javascript.md | 2 + .../plugins/storefront/javascript/index.md | 12 +- .../override-existing-javascript.md | 2 + .../storefront/javascript/plugin-reference.md | 6 +- .../storefront/styling/add-custom-assets.md | 4 +- .../storefront/styling/add-custom-styling.md | 4 +- .../plugins/storefront/styling/add-icons.md | 5 +- .../add-scss-variables-via-subscriber.md | 2 + .../storefront/styling/add-scss-variables.md | 2 + .../storefront/styling/add-translations.md | 2 + .../templates/add-custom-twig-function.md | 2 + .../templates/customize-header-footer.md | 3 + .../templates/customize-templates.md | 6 +- .../plugins/storefront/templates/index.md | 6 +- .../templates/twig-function-reference.md | 14 +- .../{ => assets}/add-assets-to-theme.md | 8 +- .../plugins/themes/{ => assets}/add-icons.md | 3 +- guides/plugins/themes/assets/index.md | 14 ++ guides/plugins/themes/configuration/index.md | 16 ++ .../theme-configuration.md | 16 +- .../theme-inheritance-configuration.md | 6 +- guides/plugins/themes/create-a-theme.md | 97 +++++--- .../differences-plugins-and-apps-vs-themes.md | 22 -- guides/plugins/themes/index.md | 41 +++- ...add-theme-inheritance-without-resources.md | 8 +- .../add-theme-inheritance.md | 10 +- guides/plugins/themes/inheritance/index.md | 12 + .../{ => styling}/add-css-js-to-theme.md | 4 +- guides/plugins/themes/styling/index.md | 13 ++ ...override-bootstrap-variables-in-a-theme.md | 8 +- .../override-theme-breakpoints.md | 0 guides/plugins/themes/theme-base-guide.md | 14 +- .../extension-translation.md | 4 +- .../language-pack-migration.md | 2 +- index.md | 2 +- products/cli/extension-commands/build.md | 6 +- products/cli/project-commands/autofix.md | 4 +- products/cli/project-commands/mysql-dump.md | 4 +- ...ment.md => remote-extension-management.md} | 4 +- .../authentication.md | 8 +- products/digital-sales-rooms/index.md | 2 +- products/paas/shopware-paas/repository.md | 8 +- resources/guidelines/troubleshooting/index.md | 10 - resources/references/index.md | 41 +++- resources/references/security.md | 2 +- 228 files changed, 1621 insertions(+), 784 deletions(-) rename {resources/guidelines => guides/development}/troubleshooting/phpstan.md (90%) rename {resources/guidelines/troubleshooting => guides/hosting/infrastructure/elasticsearch}/elasticsearch.md (75%) create mode 100644 guides/hosting/infrastructure/optional-packages.md rename {resources/guidelines/troubleshooting => guides/hosting/performance}/performance.md (98%) create mode 100644 guides/installation/legacy-setups/migrate-zip-to-composer-project.md create mode 100644 guides/plugins/plugins/creating-plugins.md create mode 100644 guides/plugins/plugins/install-activate-plugin.md create mode 100644 guides/plugins/plugins/integrations/index.md rename guides/plugins/themes/{ => assets}/add-assets-to-theme.md (86%) rename guides/plugins/themes/{ => assets}/add-icons.md (90%) create mode 100644 guides/plugins/themes/assets/index.md create mode 100644 guides/plugins/themes/configuration/index.md rename guides/plugins/themes/{ => configuration}/theme-configuration.md (97%) rename guides/plugins/themes/{ => configuration}/theme-inheritance-configuration.md (94%) delete mode 100644 guides/plugins/themes/differences-plugins-and-apps-vs-themes.md rename guides/plugins/themes/{ => inheritance}/add-theme-inheritance-without-resources.md (85%) rename guides/plugins/themes/{ => inheritance}/add-theme-inheritance.md (88%) create mode 100644 guides/plugins/themes/inheritance/index.md rename guides/plugins/themes/{ => styling}/add-css-js-to-theme.md (95%) create mode 100644 guides/plugins/themes/styling/index.md rename guides/plugins/themes/{ => styling}/override-bootstrap-variables-in-a-theme.md (90%) rename guides/plugins/themes/{ => styling}/override-theme-breakpoints.md (100%) rename products/cli/project-commands/{remote-extension-managment.md => remote-extension-management.md} (93%) delete mode 100644 resources/guidelines/troubleshooting/index.md 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..db5619d5f6 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. diff --git a/concepts/framework/elasticsearch.md b/concepts/framework/elasticsearch.md index 01ad814b24..6fded4e6e7 100644 --- a/concepts/framework/elasticsearch.md +++ b/concepts/framework/elasticsearch.md @@ -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..229ae44c87 100644 --- a/concepts/translations/built-in-translation-system.md +++ b/concepts/translations/built-in-translation-system.md @@ -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..b39e1eeaf9 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) 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..db018c7a45 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. 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..41926da268 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. Se 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..ad3af3a746 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) and avoid [Common Store Review Errors](../../development/testing/store/store-review-errors.md). ## Paid extensions 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..1c920389b3 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 --- 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..b8459e872a 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..6f737dc2da 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](./elasticsearch-debugging) 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..c6b8bb37e9 100644 --- a/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md +++ b/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md @@ -161,7 +161,7 @@ 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 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..f53e6ad3f2 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 --- @@ -13,7 +13,7 @@ Shopware uses the Symfony Messenger component and Enqueue to handle asynchronous ## Message queue on production systems -On a production system, the message queue should be processed via the CLI instead of the browser in the Administration ([Admin worker](#admin-worker)). This way, tasks are also completed when no one is logged into the Administration and high CPU load due to multiple users in the admin is also avoided. Furthermore, 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. +On a production system, the message queue should be processed via the CLI instead of the browser in the Administration ([Admin worker](#admin-worker). This way, tasks are also completed when no one is logged into the Administration and high CPU load due to multiple users in the admin is also avoided. Furthermore, 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. It is recommended to run one or more `messenger:consume` workers. To automatically start the processes again after they stopped because of exceeding the given limits you can use a process control system like [systemd](https://www.freedesktop.org/wiki/Software/systemd/) or [supervisor](http://supervisord.org/running.html). Alternatively, you can configure a cron job that runs the command periodically. @@ -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..f8bbc1ea52 --- /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 symfony/profiler-pack +``` + +## PaaS integration + +Install the Platform-as-a-Service integration: + +```bash +composer require paas --ignore-platform-req=ext-amqp +``` + +## Fastly integration + +Install Fastly support: + +```bash +composer require fastly +``` 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..477aac2109 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 --- 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..e977fc14fd 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`. diff --git a/guides/hosting/installation-updates/deployments/deployment-with-deployer.md b/guides/hosting/installation-updates/deployments/deployment-with-deployer.md index 811d4f7c7e..8c5aac0c12 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 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..3242bab8bb 100644 --- a/guides/hosting/installation-updates/performing-updates.md +++ b/guides/hosting/installation-updates/performing-updates.md @@ -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](../../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..3f98ce7162 100644 --- a/guides/hosting/performance/lock-store.md +++ b/guides/hosting/performance/lock-store.md @@ -5,7 +5,7 @@ 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). diff --git a/resources/guidelines/troubleshooting/performance.md b/guides/hosting/performance/performance.md similarity index 98% rename from resources/guidelines/troubleshooting/performance.md rename to guides/hosting/performance/performance.md index c384260613..7158d318d1 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 diff --git a/guides/installation/legacy-setups/devenv-setup.md b/guides/installation/legacy-setups/devenv-setup.md index daa4c3969e..0b89eea9a5 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. 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..904cfed614 --- /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`. \ No newline at end of file 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..c405597a02 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. diff --git a/guides/plugins/apps/administration/add-custom-action-button.md b/guides/plugins/apps/administration/add-custom-action-button.md index 4f9b790a51..c5d0b5bb9d 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: diff --git a/guides/plugins/apps/administration/add-custom-modules.md b/guides/plugins/apps/administration/add-custom-modules.md index 26833115a5..8eb6777acc 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 @@ -120,7 +120,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..f9647f5e70 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/), 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: diff --git a/guides/plugins/apps/app-scripts/cart-manipulation.md b/guides/plugins/apps/app-scripts/cart-manipulation.md index 8b8f1a6b1a..07289035de 100644 --- a/guides/plugins/apps/app-scripts/cart-manipulation.md +++ b/guides/plugins/apps/app-scripts/cart-manipulation.md @@ -7,6 +7,8 @@ nav: # Manipulate the Cart with App Scripts +## Overview + 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. ::: info 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..4b84c35de8 100644 --- a/guides/plugins/apps/app-scripts/data-loading.md +++ b/guides/plugins/apps/app-scripts/data-loading.md @@ -7,6 +7,8 @@ nav: # Load Additional Data for the Storefront with App Scripts +## 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 template. ::: info diff --git a/guides/plugins/apps/app-sdks/index.md b/guides/plugins/apps/app-sdks/index.md index 4f7f3d2653..7998de67f6 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 PH](../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, but less explicitly productized around ops/security than Go | 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 productized feature | Not prominently surfaced | Not prominently surfaced | Symfony Bundle | Yes, via PSR Request/Response/HttpClient/Repository | +| [App SDK JS](../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, but thinner explicit ops/security story than Go SDK | 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..18c29d73de 100644 --- a/guides/plugins/apps/content/cms/add-custom-cms-blocks.md +++ b/guides/plugins/apps/content/cms/add-custom-cms-blocks.md @@ -1,16 +1,18 @@ --- nav: - title: Add custom CMS blocks + title: Add Custom CMS bBlocks position: 10 --- -# Add custom CMS blocks +# Add Custom CMS blocks ::: info This functionality is available starting with Shopware 6.4.4.0. -Alternatively, you can [add custom CMS blocks](../../../plugins/content/cms/add-cms-block) using the plugin system; however, these will not be available in Shopware cloud stores. +## Overview + +You can [add custom CMS blocks](../../../plugins/content/cms/add-cms-block) using the plugin system. However, these will not be available in Shopware cloud stores. ::: Didn't get in touch with Shopware's Shopping Experiences \(CMS\) yet? Check out the concept behind it first: @@ -25,6 +27,7 @@ This guide is based on our [App Base Guide](../../app-base-guide) and assumes yo 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 +50,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 +60,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 diff --git a/guides/plugins/apps/content/cms/index.md b/guides/plugins/apps/content/cms/index.md index 998374bd1c..116d0708e6 100644 --- a/guides/plugins/apps/content/cms/index.md +++ b/guides/plugins/apps/content/cms/index.md @@ -8,4 +8,5 @@ nav: Shopware allows you to extend the platform's content management capabilities by adding custom CMS blocks or elements from an app. By creating a custom app, you can define and integrate your own unique CMS blocks. These blocks can contain custom content, such as text, images, or HTML, and can be positioned within the CMS layout according to your requirements. + Once the app is installed and activated, the custom CMS block becomes available in the Shopware Administration, allowing you to create tailored content for your online store. diff --git a/guides/plugins/apps/create-admin-extension.md b/guides/plugins/apps/create-admin-extension.md index 14d104817b..eb83e29ae5 100644 --- a/guides/plugins/apps/create-admin-extension.md +++ b/guides/plugins/apps/create-admin-extension.md @@ -6,6 +6,8 @@ nav: # Build an Admin UI App Locally +## Overview + This guide shows how to create a Shopware app that adds an Administration module backed by a local frontend development server. Use this setup when you want to: - add a custom module to the Administration diff --git a/guides/plugins/apps/custom-data/custom-entities.md b/guides/plugins/apps/custom-data/custom-entities.md index 1bf6cb71cd..1ea10e714b 100644 --- a/guides/plugins/apps/custom-data/custom-entities.md +++ b/guides/plugins/apps/custom-data/custom-entities.md @@ -1,15 +1,17 @@ --- nav: - title: Custom entities + title: Custom Entities position: 20 --- -# Custom entities +# Custom Entities -In addition to [Custom fields](custom-fields), you can create completely own entities in the system, named custom entities. -Unlike [Custom fields](custom-fields), you can generate completely custom data structures with custom relations, which can then be maintained by the admin. -To make use of the custom entities register your entities in your `entities.xml` file, which is located in the `Resources` directory of your app. +## Overview + +In addition to [Custom fields](custom-fields), you can define entirely new entities in the system, called custom entities. Unlike [Custom fields](custom-fields), custom entities let you model fully customized data structures and relationships. These entities can then be managed directly in the Administration. + +To use custom entities, register them in your app's `Resources/entities.xml` file: ```xml // /Resources/entities.xml diff --git a/guides/plugins/apps/custom-data/custom-fields.md b/guides/plugins/apps/custom-data/custom-fields.md index 389e109973..e9d0bd0a0e 100644 --- a/guides/plugins/apps/custom-data/custom-fields.md +++ b/guides/plugins/apps/custom-data/custom-fields.md @@ -1,13 +1,16 @@ --- nav: - title: Custom fields + title: Custom Data Fields position: 10 --- -# Custom Data +# Custom Data Fields + +## Overview + +You can add custom fields to Shopware and thus add your own fields to extending data records. The user is able to modify this fields from within the Shopware Administration. -You can add custom fields to Shopware and thus add your own fields to extending data records. The user is able to modify this fields from within the Shopware Administration. To make use of the custom fields, register your custom field sets in your manifest file: <<< @/docs/snippets/config/app/custom-fields-simple.xml diff --git a/guides/plugins/apps/flow-builder/add-custom-flow-actions-from-app-system.md b/guides/plugins/apps/flow-builder/add-custom-flow-actions-from-app-system.md index f65dd8a230..c3afd101a2 100644 --- a/guides/plugins/apps/flow-builder/add-custom-flow-actions-from-app-system.md +++ b/guides/plugins/apps/flow-builder/add-custom-flow-actions-from-app-system.md @@ -11,6 +11,8 @@ nav: Custom flow actions in Shopware Apps are available starting with Shopware 6.4.10.0 and are not supported in previous versions. ::: +## Overview + Besides the default actions, developers can add custom, predefined, and configurable web hook actions to the flow builder. ![Custom flow action in Administration](../../../../assets/flow-builder-app-action-preview.png) diff --git a/guides/plugins/apps/flow-builder/add-custom-flow-triggers-from-app-system.md b/guides/plugins/apps/flow-builder/add-custom-flow-triggers-from-app-system.md index e985986d62..b5d14004e2 100644 --- a/guides/plugins/apps/flow-builder/add-custom-flow-triggers-from-app-system.md +++ b/guides/plugins/apps/flow-builder/add-custom-flow-triggers-from-app-system.md @@ -11,6 +11,8 @@ nav: The Shopware app custom flow triggers are only accessible from 6.5.3.0 and later versions. ::: +## Overview + In addition to the default triggers, you have the option to incorporate custom, pre-defined, and adjustable triggers into the flow builder. ![Custom flow trigger in Administration](../../../../assets/flow-builder-custom-trigger-preview.png) diff --git a/guides/plugins/apps/gateways/in-app-purchase/in-app-purchase-gateway.md b/guides/plugins/apps/gateways/in-app-purchase/in-app-purchase-gateway.md index 9f9c0a0e1f..39788b57f5 100644 --- a/guides/plugins/apps/gateways/in-app-purchase/in-app-purchase-gateway.md +++ b/guides/plugins/apps/gateways/in-app-purchase/in-app-purchase-gateway.md @@ -6,13 +6,13 @@ nav: # In-App Purchase Gateway -## Context - ::: info In-App Purchase is available since Shopware version 6.6.9.0 ::: -In-App Purchase Gateway was introduced to enhance flexibility in managing In-App Purchases. +## Overview + +The In-App Purchase Gateway enhances flexibility in managing In-App Purchases. The gateway enables app servers to restrict specific In-App Purchases based on advanced decision-making processes handled on the app server side. @@ -25,14 +25,14 @@ We aim to expand its functionality to include filtering entire lists of In-App P ## Prerequisites -You should be familiar with the concept of Apps, their registration flow as well as signing and verifying requests and responses between Shopware and the App backend server. +You should be familiar with the concept of Apps, their registration flow, and how to sign and verify requests and responses between Shopware and the App backend server. Your app server must be also accessible for the Shopware server. You can use a tunneling service like [ngrok](https://ngrok.com/) for development. -## Manifest Configuration +## Manifest configuration To indicate that your app leverages the In-App Purchase Gateway, include the `inAppPurchase` property within the `gateways` property in your app's `manifest.xml`. @@ -59,9 +59,8 @@ The app server will receive a list containing the single only In-App Purchase th ::: warning **Connection timeouts** -The Shopware shop will wait for a response for 5 seconds. -Be sure that your In-App Purchases gateway implementation on your app server responds in time, -otherwise Shopware will time out and drop the connection. +The Shopware shop will wait for a response for five seconds. +Be sure that your In-App Purchases gateway implementation on your app server responds in time, otherwise Shopware will time out and drop the connection. ::: diff --git a/guides/plugins/apps/lifecycle/app-registration-setup.md b/guides/plugins/apps/lifecycle/app-registration-setup.md index 41a5e42aae..75cc2f0941 100644 --- a/guides/plugins/apps/lifecycle/app-registration-setup.md +++ b/guides/plugins/apps/lifecycle/app-registration-setup.md @@ -7,6 +7,8 @@ nav: # App Registration & Backend Setup +## Overview + This page documents app setup (registration), permissions, validation, and changes to the shop URL for apps with a backend. ## Setup diff --git a/guides/plugins/apps/lifecycle/app-signature-verification.md b/guides/plugins/apps/lifecycle/app-signature-verification.md index 2342075820..4abef8f905 100644 --- a/guides/plugins/apps/lifecycle/app-signature-verification.md +++ b/guides/plugins/apps/lifecycle/app-signature-verification.md @@ -7,6 +7,8 @@ nav: # Signing & Verification in the App System +## Overview + To ensure secure communication between Shopware shops and your app server, Shopware signs all outgoing requests using a cryptographic signature. The signature is generated using [HMAC-SHA256](https://en.wikipedia.org/wiki/HMAC), hashing either the query string or the request body, depending on the request method, with your app secret. By verifying this signature on your server, you can confirm that the request originates from Shopware and remains unaltered during transmission. diff --git a/guides/plugins/apps/lifecycle/clientside-to-app-backend.md b/guides/plugins/apps/lifecycle/clientside-to-app-backend.md index b0bdbe8730..4d745ba9a2 100644 --- a/guides/plugins/apps/lifecycle/clientside-to-app-backend.md +++ b/guides/plugins/apps/lifecycle/clientside-to-app-backend.md @@ -6,6 +6,8 @@ nav: # Client-Side App Backend Communication +## Overview + Direct communication from the browser to the app backend involves generating a JSON Web Token (JWT). This token contains session-specific information, as [claims](#the-json-web-token), and is securely signed by the shop. This mechanism ensures a secure exchange of data between the client and the app backend. diff --git a/guides/plugins/apps/lifecycle/configuration.md b/guides/plugins/apps/lifecycle/configuration.md index af228d1b74..93dd14d8cc 100644 --- a/guides/plugins/apps/lifecycle/configuration.md +++ b/guides/plugins/apps/lifecycle/configuration.md @@ -11,6 +11,8 @@ nav: Configurations for apps adhere to the same schema as [Plugin Configurations](../../plugins/plugin-fundamentals/add-plugin-configuration.md). ::: +## Overview + To offer configuration possibilities to your users you can provide a `config.xml` file that describes your configuration options. You can find detailed information about the possibilities and the structure of the `config.xml` in the according documentation page. To include a `config.xml` file in your app put it into the `Resources/config` folder: ```text diff --git a/guides/plugins/apps/lifecycle/product-translator.md b/guides/plugins/apps/lifecycle/product-translator.md index f4257f8b4e..7d855a5590 100644 --- a/guides/plugins/apps/lifecycle/product-translator.md +++ b/guides/plugins/apps/lifecycle/product-translator.md @@ -1,13 +1,15 @@ --- nav: - title: Starter Guide - Read and write data + title: Read and write data position: 10 --- -# Starter Guide - Read and Write Data +# Read and Write Data -This guide will show you how to set up an app server with our [app bundle](https://github.com/shopware/app-bundle-symfony). +## Overview + +This guide covers how to set up an app server with our [app bundle](https://github.com/shopware/app-bundle-symfony). You will learn how to read and write data to the Shopware Admin API using an example of fetching dynamic translations for products when they are updated. ## Prerequisites diff --git a/guides/plugins/apps/lifecycle/webhook.md b/guides/plugins/apps/lifecycle/webhook.md index 5468ca6fdc..c4d7c86ab9 100644 --- a/guides/plugins/apps/lifecycle/webhook.md +++ b/guides/plugins/apps/lifecycle/webhook.md @@ -7,6 +7,8 @@ nav: # Webhook +## Overview + With webhooks, you can subscribe to events occurring in Shopware. Whenever such an event occurs, a `POST` request will be sent to the URL specified for this particular event. ## Prerequisites @@ -115,7 +117,7 @@ The next property, `timestamp` is the time at which the webhook was handled. Thi ::: info Starting from Shopware version 6.4.1.0, the current Shopware version will be sent as a `sw-version` header. -Starting from Shopware version 6.4.5.0, the current language id of the shopware context will be sent as a `sw-context-language` header, and the locale of the user or locale of the context language is available under the `sw-user-language` header. +Starting from Shopware version 6.4.5.0, the current language id of the shopware context will be sent as a `sw-context-language` header, and the locale of the user or locale of the context language is available under the `sw-user-language` header. ::: You can verify the authenticity of the incoming request by checking the `shopware-shop-signature`. Every request should have a SHA256 HMAC of the request body that is signed with the secret your app assigned the shop during the [registration](app-registration-setup.md#setup). The mechanism to verify the request is exactly the same as the one used for the [confirmation request](app-registration-setup.md#confirmation-request). diff --git a/guides/plugins/apps/rule-builder/add-custom-rule-conditions.md b/guides/plugins/apps/rule-builder/add-custom-rule-conditions.md index 92213eff44..f4681791a8 100644 --- a/guides/plugins/apps/rule-builder/add-custom-rule-conditions.md +++ b/guides/plugins/apps/rule-builder/add-custom-rule-conditions.md @@ -7,6 +7,8 @@ nav: # Add Custom Rule Conditions +## Overview + This guide explains how to make your app introduce custom conditions for use in the [Rule Builder](../../../../concepts/framework/rule-system/index.md). Custom conditions can be defined with fields to be rendered in the Administration and with their own logic, using the same approach as [App Scripts](../app-scripts/index.md). ::: info diff --git a/guides/plugins/apps/storefront/apps-as-themes.md b/guides/plugins/apps/storefront/apps-as-themes.md index fca16042b5..0b31635fbc 100644 --- a/guides/plugins/apps/storefront/apps-as-themes.md +++ b/guides/plugins/apps/storefront/apps-as-themes.md @@ -1,14 +1,13 @@ --- nav: - title: Apps as themes + title: Apps as Themes position: 10 --- -# Apps as themes +# Apps as Themes -It is absolutely possible to ship whole [themes](../../themes/) inside an app. All you have to do is include your theme configuration \(in the form of a [theme.json](../../../plugins/themes/theme-configuration) file\) inside your app's Resources folder. -So the folder structure of a theme may look like this: +To ship whole [themes](../../themes/) inside an app, just include the theme configuration as a [theme.json](../../../plugins/themes/configuration/theme-configuration.md) file inside your app's `Resources` folder. The folder structure of a theme may look like this: ```text └── DemoTheme diff --git a/guides/plugins/apps/storefront/cookies-with-apps.md b/guides/plugins/apps/storefront/cookies-with-apps.md index f84fa63fc9..25a93e4921 100644 --- a/guides/plugins/apps/storefront/cookies-with-apps.md +++ b/guides/plugins/apps/storefront/cookies-with-apps.md @@ -7,6 +7,8 @@ nav: # Add Cookies to the Consent Manager +## Overview + Before proceeding, review the [app-base-guide](../app-base-guide.md). The [Cookie Consent Management Concept](../../../../concepts/commerce/content/cookie-consent-management) provides a comprehensive guide to Shopware's cookie consent system. diff --git a/guides/plugins/apps/storefront/customize-templates.md b/guides/plugins/apps/storefront/customize-templates.md index f34cecb25a..5e49d987cb 100644 --- a/guides/plugins/apps/storefront/customize-templates.md +++ b/guides/plugins/apps/storefront/customize-templates.md @@ -1,6 +1,6 @@ --- nav: - title: Customize templates + title: Customize Templates position: 10 --- diff --git a/guides/plugins/plugins/administration/administration-reference/directives.md b/guides/plugins/plugins/administration/administration-reference/directives.md index 728d3f3501..a884695b92 100644 --- a/guides/plugins/plugins/administration/administration-reference/directives.md +++ b/guides/plugins/plugins/administration/administration-reference/directives.md @@ -5,7 +5,7 @@ nav: --- -# Directives reference +# Directives Reference This is an overview of all the directives registered globally to Vue. Directives are the same as in Vue. diff --git a/guides/plugins/plugins/administration/administration-reference/mixins.md b/guides/plugins/plugins/administration/administration-reference/mixins.md index 286aeb02ff..bcf17236e2 100644 --- a/guides/plugins/plugins/administration/administration-reference/mixins.md +++ b/guides/plugins/plugins/administration/administration-reference/mixins.md @@ -5,7 +5,7 @@ nav: --- -# Mixins +# Mixins Reference This is an overview of all the mixins provided by the Shopware 6 Administration. Mixins in the Shopware 6 Administration are essentially the same as the default Vue. They behave generally the same as in Vue, differing only in registration and the way mixins are included in a component. Learn more about them in the official [Vue documentation](https://vuejs.org/v2/guide/mixins.html). diff --git a/guides/plugins/plugins/administration/administration-reference/utils.md b/guides/plugins/plugins/administration/administration-reference/utils.md index 1307b23b32..b7718e96df 100644 --- a/guides/plugins/plugins/administration/administration-reference/utils.md +++ b/guides/plugins/plugins/administration/administration-reference/utils.md @@ -5,7 +5,7 @@ nav: --- -# Utils +# Utils Reference This guide provides an overview of utility functions bound to the Shopware global object. diff --git a/guides/plugins/plugins/administration/advanced-configuration/add-rule-assignment-configuration.md b/guides/plugins/plugins/administration/advanced-configuration/add-rule-assignment-configuration.md index bd74972ec8..af61a9522a 100644 --- a/guides/plugins/plugins/administration/advanced-configuration/add-rule-assignment-configuration.md +++ b/guides/plugins/plugins/administration/advanced-configuration/add-rule-assignment-configuration.md @@ -1,11 +1,11 @@ --- nav: - title: Add rule assignment configuration + title: Add Rule Assignment Configuration position: 330 --- -# Add rule assignment configuration +# Add Rule Assignment Configuration ::: info The rule assignment configuration is available from Shopware Version 6.4.8.0 diff --git a/guides/plugins/plugins/administration/advanced-configuration/add-shortcuts.md b/guides/plugins/plugins/administration/advanced-configuration/add-shortcuts.md index 37cc59babf..c5049f86b0 100644 --- a/guides/plugins/plugins/administration/advanced-configuration/add-shortcuts.md +++ b/guides/plugins/plugins/administration/advanced-configuration/add-shortcuts.md @@ -1,6 +1,6 @@ --- nav: - title: Add shortcuts + title: Add Shortcuts position: 320 --- diff --git a/guides/plugins/plugins/administration/advanced-configuration/modify-blacklist-for-dynamic-product-groups.md b/guides/plugins/plugins/administration/advanced-configuration/modify-blacklist-for-dynamic-product-groups.md index 7a5d444082..fe2e22acfd 100644 --- a/guides/plugins/plugins/administration/advanced-configuration/modify-blacklist-for-dynamic-product-groups.md +++ b/guides/plugins/plugins/administration/advanced-configuration/modify-blacklist-for-dynamic-product-groups.md @@ -4,7 +4,7 @@ nav: position: 20 --- -# Modify dynamic product groups blacklist +# Modify Dynamic Product Groups Blacklist ## Overview diff --git a/guides/plugins/plugins/administration/data-handling-processing/handling-media.md b/guides/plugins/plugins/administration/data-handling-processing/handling-media.md index a0b0bee273..3ea3bf11e3 100644 --- a/guides/plugins/plugins/administration/data-handling-processing/handling-media.md +++ b/guides/plugins/plugins/administration/data-handling-processing/handling-media.md @@ -1,4 +1,10 @@ -# Handling media +--- +nav: + title: Handling Media + position: 100 +--- + +# Handling Media ## Overview diff --git a/guides/plugins/plugins/administration/data-handling-processing/search-custom-data.md b/guides/plugins/plugins/administration/data-handling-processing/search-custom-data.md index eb9e810ab3..4197383b05 100644 --- a/guides/plugins/plugins/administration/data-handling-processing/search-custom-data.md +++ b/guides/plugins/plugins/administration/data-handling-processing/search-custom-data.md @@ -1,11 +1,11 @@ --- nav: - title: Add custom data to the search + title: Add Custom Data to the Search position: 310 --- -# Add custom data to the search +# Add Custom Data to the Search ## Overview diff --git a/guides/plugins/plugins/administration/data-handling-processing/the-shopware-object.md b/guides/plugins/plugins/administration/data-handling-processing/the-shopware-object.md index d99c4f7880..08c65130c8 100644 --- a/guides/plugins/plugins/administration/data-handling-processing/the-shopware-object.md +++ b/guides/plugins/plugins/administration/data-handling-processing/the-shopware-object.md @@ -1,11 +1,11 @@ --- nav: - title: The Shopware object + title: The Shopware Object position: 270 --- -# The Shopware object +# The Shopware Object ## Overview diff --git a/guides/plugins/plugins/administration/data-handling-processing/using-custom-fields.md b/guides/plugins/plugins/administration/data-handling-processing/using-custom-fields.md index e0f69c7c61..04c8b735dd 100644 --- a/guides/plugins/plugins/administration/data-handling-processing/using-custom-fields.md +++ b/guides/plugins/plugins/administration/data-handling-processing/using-custom-fields.md @@ -1,11 +1,11 @@ --- nav: - title: Using custom fields + title: Using Custom Fields position: 300 --- -# Using custom fields +# Using Custom Fields ## Prerequisites diff --git a/guides/plugins/plugins/administration/data-handling-processing/using-data-handling.md b/guides/plugins/plugins/administration/data-handling-processing/using-data-handling.md index 79eb46c72d..c2a34f65c6 100644 --- a/guides/plugins/plugins/administration/data-handling-processing/using-data-handling.md +++ b/guides/plugins/plugins/administration/data-handling-processing/using-data-handling.md @@ -1,11 +1,13 @@ --- nav: - title: Using the data handling + title: Using Data Handling position: 120 --- -# Using the data handling +# Using Data Handling + +## Overview The Shopware 6 Administration allows you to fetch and write nearly everything in the database. This guide will teach you the basics of the data handling. diff --git a/guides/plugins/plugins/administration/data-handling-processing/using-the-data-grid-component.md b/guides/plugins/plugins/administration/data-handling-processing/using-the-data-grid-component.md index 2a0cccd7fb..e5ee60fa90 100644 --- a/guides/plugins/plugins/administration/data-handling-processing/using-the-data-grid-component.md +++ b/guides/plugins/plugins/administration/data-handling-processing/using-the-data-grid-component.md @@ -1,11 +1,11 @@ --- nav: - title: Using the data grid component + title: Using the Data Grid Component position: 230 --- -# Using the data grid component +# Using the Data Grid Component ## Overview diff --git a/guides/plugins/plugins/administration/data-handling-processing/using-vuex-state.md b/guides/plugins/plugins/administration/data-handling-processing/using-vuex-state.md index 8e2d6fcca5..e4b78f0cff 100644 --- a/guides/plugins/plugins/administration/data-handling-processing/using-vuex-state.md +++ b/guides/plugins/plugins/administration/data-handling-processing/using-vuex-state.md @@ -1,9 +1,17 @@ +--- +nav: + title: Using Vuex Stores + position: 110 + +--- + # Using Vuex Stores ## Overview The Shopware 6 Administration uses [Vuex](https://vuex.vuejs.org/) stores to keep track of complex state, while just adding a wrapper around it. Learn what Vuex is, how to use it and when to use it from their great [documentation](https://vuex.vuejs.org/). + This guide will show you how to use Vuex as you normally would, through the interfaces provided by the Shopware 6 Administration. ## Prerequisites diff --git a/guides/plugins/plugins/administration/mixins-directives/using-mixins.md b/guides/plugins/plugins/administration/mixins-directives/using-mixins.md index 5183170ffc..d07134d656 100644 --- a/guides/plugins/plugins/administration/mixins-directives/using-mixins.md +++ b/guides/plugins/plugins/administration/mixins-directives/using-mixins.md @@ -9,7 +9,7 @@ nav: ## Overview -This documentation chapter will cover how to use an existing Administration mixin in your plugin. Generally, mixins behave the same as they do in Vue normally, differing only in the registration and the way mixins are included in a component. +This guide covers how to use an existing Administration mixin in a plugin. Generally, mixins behave the same as they do in Vue normally, differing only in the registration and the way mixins are included in a component. ## Prerequisites @@ -17,9 +17,9 @@ All you need for this guide is a running Shopware 6 instance and full access to ## Finding a mixin -The Shopware 6 Administration comes with a few predefined [mixins](../../../../../resources/references/administration-reference/mixins.md) +The Shopware 6 Administration comes with a few predefined [mixins](../administration-reference/mixins.md). -If you want to learn how to create your own mixin look at this guide: [Creating mixins](add-mixins.md) +To create your own mixin, review the [Adding mixins](./add-mixins.md) guide. ## Using the Mixin diff --git a/guides/plugins/plugins/administration/module-component-management/add-custom-component.md b/guides/plugins/plugins/administration/module-component-management/add-custom-component.md index 4b2439f8cc..abe002af76 100644 --- a/guides/plugins/plugins/administration/module-component-management/add-custom-component.md +++ b/guides/plugins/plugins/administration/module-component-management/add-custom-component.md @@ -1,11 +1,11 @@ --- nav: - title: Add custom component + title: Add Custom Components position: 20 --- -# Add custom component +# Add Custom Components ## Overview diff --git a/guides/plugins/plugins/administration/module-component-management/add-custom-field.md b/guides/plugins/plugins/administration/module-component-management/add-custom-field.md index 36222eaddc..01d6381eeb 100644 --- a/guides/plugins/plugins/administration/module-component-management/add-custom-field.md +++ b/guides/plugins/plugins/administration/module-component-management/add-custom-field.md @@ -1,15 +1,15 @@ --- nav: - title: Add custom input field to existing component + title: Add Custom Input Field to Existing Component position: 200 --- -# Add custom input field to existing component +# Add Custom Input Field to Existing Component ## Overview -If you were wondering how to add a new input field to an existing module in the Administration via plugin, then you've found the right guide to cover that subject. In the following examples, you'll add a new input field to the product's detail page, to display and configure some other product data not being handled by default. +This guide explains how to add a new input field to an existing module in the Administration using a plugin. The following examples show how to add a new input field to the product's detail page in order to display and configure other product data not being handled by default. ## Prerequisites diff --git a/guides/plugins/plugins/administration/module-component-management/add-custom-module.md b/guides/plugins/plugins/administration/module-component-management/add-custom-module.md index 7e1e082b20..2d2f5ff46c 100644 --- a/guides/plugins/plugins/administration/module-component-management/add-custom-module.md +++ b/guides/plugins/plugins/administration/module-component-management/add-custom-module.md @@ -1,11 +1,13 @@ --- nav: - title: Add custom module + title: Add Custom Module position: 10 --- -# Add custom module +# Add Custom Module + +## Overview In the `Administration` core code, each module is defined in a directory called `module`. Inside the `module` directory lies the list of several modules, each having their own directory named after the module itself. diff --git a/guides/plugins/plugins/administration/module-component-management/customizing-components.md b/guides/plugins/plugins/administration/module-component-management/customizing-components.md index 0e42bca3fc..ecb179b707 100644 --- a/guides/plugins/plugins/administration/module-component-management/customizing-components.md +++ b/guides/plugins/plugins/administration/module-component-management/customizing-components.md @@ -1,10 +1,12 @@ --- nav: - title: Customizing components + title: Customizing Components position: 170 --- -# Customizing components +# Customizing Components + +## Overview The Shopware 6 Administration allows you to override and extend components to change its content and its behavior. diff --git a/guides/plugins/plugins/administration/module-component-management/customizing-modules.md b/guides/plugins/plugins/administration/module-component-management/customizing-modules.md index f17ad8f973..db7cf7d122 100644 --- a/guides/plugins/plugins/administration/module-component-management/customizing-modules.md +++ b/guides/plugins/plugins/administration/module-component-management/customizing-modules.md @@ -1,11 +1,11 @@ --- nav: - title: Customize modules + title: Customize Modules position: 140 --- -# Customize modules +# Customize Modules ## Overview diff --git a/guides/plugins/plugins/administration/module-component-management/index.md b/guides/plugins/plugins/administration/module-component-management/index.md index 85dd4bf80c..71f992be3d 100644 --- a/guides/plugins/plugins/administration/module-component-management/index.md +++ b/guides/plugins/plugins/administration/module-component-management/index.md @@ -13,9 +13,9 @@ This guide covers how to create, extend, and customize Administration modules an - Override or extend existing components - Work with base components and input fields -- [Add Custom Module](./add-custom-module) -- [Customizing Modules](./customizing-modules) +- [Add Custom Field](./add-custom-field) - [Add Custom Component](./add-custom-component) +- [Add Custom Module](./add-custom-module) - [Customizing Components](./customizing-components) +- [Customizing Modules](./customizing-modules) - [Using Base Components](./using-base-components) -- [Add Custom Field](./add-custom-field) diff --git a/guides/plugins/plugins/administration/module-component-management/using-base-components.md b/guides/plugins/plugins/administration/module-component-management/using-base-components.md index 9deb569b3c..1c7c73d63d 100644 --- a/guides/plugins/plugins/administration/module-component-management/using-base-components.md +++ b/guides/plugins/plugins/administration/module-component-management/using-base-components.md @@ -1,11 +1,13 @@ --- nav: - title: Using base components + title: Using Base Components position: 210 --- -# Using base components +# Using Base Components + +## Overview The Shopware 6 Administration comes with a bunch of tailored Vue components, already accessible in all of your templates via the `component registry`. This guide will show you how you can use Shopware-made components in your templates, if you want to learn more about the `component registry` and how you can register your own components to it have a look at the [corresponding guide](../module-component-management/add-custom-component.md) diff --git a/guides/plugins/plugins/administration/permissions-error-handling/add-acl-rules.md b/guides/plugins/plugins/administration/permissions-error-handling/add-acl-rules.md index bace313750..7bdb353f44 100644 --- a/guides/plugins/plugins/administration/permissions-error-handling/add-acl-rules.md +++ b/guides/plugins/plugins/administration/permissions-error-handling/add-acl-rules.md @@ -1,11 +1,11 @@ --- nav: - title: Adding permissions + title: Adding Permissions position: 110 --- -# Adding permissions +# Adding Permissions ## Overview diff --git a/guides/plugins/plugins/administration/permissions-error-handling/add-error-handling.md b/guides/plugins/plugins/administration/permissions-error-handling/add-error-handling.md index 71abe7a7c1..99b562e3e9 100644 --- a/guides/plugins/plugins/administration/permissions-error-handling/add-error-handling.md +++ b/guides/plugins/plugins/administration/permissions-error-handling/add-error-handling.md @@ -1,13 +1,11 @@ --- nav: - title: Adding error handling + title: Adding Error Handling position: 130 --- -# Adding error handling - -​ +# Adding Error Handling ## Overview diff --git a/guides/plugins/plugins/administration/routing-navigation/add-custom-route.md b/guides/plugins/plugins/administration/routing-navigation/add-custom-route.md index 921501684a..5c3964a08c 100644 --- a/guides/plugins/plugins/administration/routing-navigation/add-custom-route.md +++ b/guides/plugins/plugins/administration/routing-navigation/add-custom-route.md @@ -1,11 +1,13 @@ --- nav: - title: Add custom route + title: Add Custom Route position: 30 --- -# Add custom route +# Add Custom Route + +## Overview Routes in the Shopware 6 Administration are essentially the same as in any other [Vue Router](https://router.vuejs.org). This guide will teach you the basics of creating your very first route from scratch. diff --git a/guides/plugins/plugins/administration/routing-navigation/add-menu-entry.md b/guides/plugins/plugins/administration/routing-navigation/add-menu-entry.md index cf007a06ff..bc938bacc9 100644 --- a/guides/plugins/plugins/administration/routing-navigation/add-menu-entry.md +++ b/guides/plugins/plugins/administration/routing-navigation/add-menu-entry.md @@ -1,11 +1,11 @@ --- nav: - title: Add menu entry + title: Add Menu Entry position: 40 --- -# Add menu entry +# Add Menu Entry ## Overview diff --git a/guides/plugins/plugins/administration/routing-navigation/add-new-tab.md b/guides/plugins/plugins/administration/routing-navigation/add-new-tab.md index 8c6b5b73eb..a2f1bf11c6 100644 --- a/guides/plugins/plugins/administration/routing-navigation/add-new-tab.md +++ b/guides/plugins/plugins/administration/routing-navigation/add-new-tab.md @@ -1,15 +1,15 @@ --- nav: - title: Add tab to existing module + title: Add Tab to Existing Module position: 160 --- -# Add tab to existing module +# Add Tab to Existing Module ## Overview -You want to create a new tab in the Administration? This guide gets you covered on this subject. A realistic example would be adding a new association for an entity, which you want to configure on a separate tab on the entity detail page. +This guide covers creating a new tab in the Administration. A realistic example would be adding a new association for an entity, which you want to configure on a separate tab on the entity detail page. ## Prerequisites diff --git a/guides/plugins/plugins/administration/routing-navigation/overriding-routes.md b/guides/plugins/plugins/administration/routing-navigation/overriding-routes.md index f19c7f3dad..0cfbfc19c7 100644 --- a/guides/plugins/plugins/administration/routing-navigation/overriding-routes.md +++ b/guides/plugins/plugins/administration/routing-navigation/overriding-routes.md @@ -1,11 +1,11 @@ --- nav: - title: Override existing routes + title: Override Existing Routes position: 150 --- -# Override existing routes +# Override Existing Routes ## Overview diff --git a/guides/plugins/plugins/administration/services-utilities/add-filter.md b/guides/plugins/plugins/administration/services-utilities/add-filter.md index db9cb1a1ed..8f48f334d4 100644 --- a/guides/plugins/plugins/administration/services-utilities/add-filter.md +++ b/guides/plugins/plugins/administration/services-utilities/add-filter.md @@ -1,19 +1,19 @@ --- nav: - title: Add filter + title: Add Filter position: 280 --- -# Add filter +# Add Filter ## Overview -In this guide you'll learn, how to create a filter for the Shopware Administration. A filter is just a little helper for formatting text. In this example, we create a filter that converts text into uppercase and adds an underscore at the beginning and end. +This guide covers how to create a filter for the Shopware Administration. A filter is just a little helper for formatting text. In this example, we create a filter that converts text into uppercase and adds an underscore at the beginning and end. ## Prerequisites -This guide requires you to already have a basic plugin running. If you don't know how to do this in the first place, have a look at our [Plugin base guide](../../plugin-base-guide.md). +You need to already have a basic plugin running. If you don't know how to create a plugin, have a look at our [Plugin base guide](../../plugin-base-guide.md). ## Creating the filter diff --git a/guides/plugins/plugins/administration/services-utilities/extending-services.md b/guides/plugins/plugins/administration/services-utilities/extending-services.md index 6987377e39..c274aa1f84 100644 --- a/guides/plugins/plugins/administration/services-utilities/extending-services.md +++ b/guides/plugins/plugins/administration/services-utilities/extending-services.md @@ -5,13 +5,13 @@ nav: --- -# Extending services +# Extending Services ## Overview -This guide will teach you how to extend a Shopware provided service with middleware and decorators. +This guide covers how to extend a Shopware provided service with middleware and decorators. The Shopware 6 Administration uses [BottleJS](https://github.com/young-steveo/bottlejs) to provide the framework for services. -If you want to learn how to create your own services, look at [this guide](./add-custom-service.md). +To learn how to create your own services, look at [this guide](./add-custom-service.md). ## Prerequisites diff --git a/guides/plugins/plugins/administration/services-utilities/injecting-services.md b/guides/plugins/plugins/administration/services-utilities/injecting-services.md index 1edd111eb1..54512b8f9a 100644 --- a/guides/plugins/plugins/administration/services-utilities/injecting-services.md +++ b/guides/plugins/plugins/administration/services-utilities/injecting-services.md @@ -1,13 +1,18 @@ -# Injecting services +--- +nav: + title: Injecting Services + position: 110 -## Overview +--- + +# Injecting Services -This short guide will teach you how to use a service in the Shopware 6 Administration. +## Overview -Along these lines, this chapter will cover the following topics: +This short guide covers how to use a service in the Shopware 6 Administration, including: -* What is an Administration service? -* How to use a service? +* What an Administration service is +* How to use a service ## Prerequisites diff --git a/guides/plugins/plugins/administration/services-utilities/making-api-requests.md b/guides/plugins/plugins/administration/services-utilities/making-api-requests.md index 8765efe94e..f4287bf984 100644 --- a/guides/plugins/plugins/administration/services-utilities/making-api-requests.md +++ b/guides/plugins/plugins/administration/services-utilities/making-api-requests.md @@ -1,6 +1,6 @@ --- nav: - title: Making API requests + title: Making API Requests position: 70 --- diff --git a/guides/plugins/plugins/administration/services-utilities/the-sanitizer-helper.md b/guides/plugins/plugins/administration/services-utilities/the-sanitizer-helper.md index be6f215c0f..41b6071b86 100644 --- a/guides/plugins/plugins/administration/services-utilities/the-sanitizer-helper.md +++ b/guides/plugins/plugins/administration/services-utilities/the-sanitizer-helper.md @@ -1,4 +1,11 @@ -# The Sanitizer helper +--- +nav: + title: Sanitizer Helper + position: 130 + +--- + +# Sanitizer Helper ## Overview diff --git a/guides/plugins/plugins/administration/services-utilities/using-filter.md b/guides/plugins/plugins/administration/services-utilities/using-filter.md index e68c14e1ab..16a1d8c580 100644 --- a/guides/plugins/plugins/administration/services-utilities/using-filter.md +++ b/guides/plugins/plugins/administration/services-utilities/using-filter.md @@ -1,15 +1,15 @@ --- nav: - title: Using filter + title: Using Filter position: 290 --- -# Using filter +# Using Filter ## Overview -In this guide you'll learn how to use filters in the Shopware Administration. +This guide describes how to use filters in the Shopware Administration. ## Prerequisites diff --git a/guides/plugins/plugins/administration/services-utilities/using-utils.md b/guides/plugins/plugins/administration/services-utilities/using-utils.md index f2525788b7..597ebcad5d 100644 --- a/guides/plugins/plugins/administration/services-utilities/using-utils.md +++ b/guides/plugins/plugins/administration/services-utilities/using-utils.md @@ -1,13 +1,15 @@ --- nav: - title: Using utility functions + title: Using Utility Functions position: 250 --- -# Using utility functions +# Using Utility Functions -Utility functions in the Shopware 6 Administration are registered to [the Shopware object](../data-handling-processing/the-shopware-object.md) and are therefore accessible everywhere in the Administration. They provide many useful [shortcuts](../../../../../resources/references/administration-reference/utils.md) for common tasks. +## Overview + +Utility functions in the Shopware 6 Administration are registered to [the Shopware object](../data-handling-processing/the-shopware-object.md) and are therefore accessible everywhere in the Administration. They provide many useful [shortcuts](../administration-reference/utils.md) for common tasks. ## Prerequisites diff --git a/guides/plugins/plugins/administration/templates-styling/add-custom-styles.md b/guides/plugins/plugins/administration/templates-styling/add-custom-styles.md index 2a1ff93a46..a67cefc091 100644 --- a/guides/plugins/plugins/administration/templates-styling/add-custom-styles.md +++ b/guides/plugins/plugins/administration/templates-styling/add-custom-styles.md @@ -1,11 +1,11 @@ --- nav: - title: Add custom styles + title: Add Custom Styles position: 220 --- -# Add custom styles +# Add Custom Styles ## Overview diff --git a/guides/plugins/plugins/administration/templates-styling/adding-responsive-behavior.md b/guides/plugins/plugins/administration/templates-styling/adding-responsive-behavior.md index 539586d873..c2007026d8 100644 --- a/guides/plugins/plugins/administration/templates-styling/adding-responsive-behavior.md +++ b/guides/plugins/plugins/administration/templates-styling/adding-responsive-behavior.md @@ -1,11 +1,13 @@ --- nav: - title: Adding responsive behavior + title: Adding Responsive Behavior position: 260 --- -# Adding responsive behavior +# Adding Responsive Behavior + +## Overview The Shopware 6 Administration provides two ways of adding classes to elements based on their size, the device helper and the `v-responsive` directive. Alternatively, you can use `css` media queries to make your plugin responsive. Learn how to use `css` here: diff --git a/guides/plugins/plugins/bundle.md b/guides/plugins/plugins/bundle.md index 8434d1bf6d..82c92d3d79 100644 --- a/guides/plugins/plugins/bundle.md +++ b/guides/plugins/plugins/bundle.md @@ -7,7 +7,7 @@ nav: # Using Symfony Bundles Instead of Plugins -This guide handles some basic concepts of Shopware plugins covered in our [Plugin base guide](plugin-base-guide). You may want to have a look or refresh your knowledge on Symfony's [Bundle system](https://symfony.com/doc/current/bundles.html). +This guide refers to some basic concepts of Shopware plugins also covered in the [Plugin base guide](./plugin-base-guide.md). You may want to refresh your knowledge of Symfony's [Bundle system](https://symfony.com/doc/current/bundles.html). ::: info Check out our [Shopware Toolbox PHPStorm extension](../../development/tooling/shopware-toolbox.md) with useful features like autocompletion, code generation or guideline checks. @@ -20,8 +20,6 @@ You might use a Symfony bundle instead of a plugin when: * You are building project-level customization * You want pure Symfony integration -A bundle is Symfony's preferred way to provide additional third-party features to any Symfony application. Those bundles are everywhere: Symfony even outsources many of its core features into external bundles. The template engine `Twig`, the `Security` bundle, the `WebProfiler`, as well as many other third-party bundles can be installed on demand to extend your Symfony application in any way. The Bundle System is Symfony's way of providing an extendable framework with plugin capabilities. - ## How Plugins extend bundles Shopware plugins extend Symfony bundles and add: @@ -42,7 +40,7 @@ Use a pure Symfony bundle when: * You manage everything via Composer * You do not distribute the extension -## Project Structure +## Project structure How a typical Shopware 6 project structure looks when bundles are used: @@ -81,7 +79,7 @@ project-root/ └── .shopware-project.yaml ``` -The Bundle is typically placed in the `src/` folder of your project, which is the standard location for custom code in a Shopware project. You still will need to register the bundle in the `config/bundles.php` file of your project. +The Bundle is typically placed in a project's `src/` folder, which is the standard location for custom code. You still will need to register the bundle in the project's `config/bundles.php` file. ## Choosing the right bundle class @@ -92,7 +90,7 @@ There are two bundle classes you can choose from: ## Creating a bundle -By default, The namespace `App\` is registered to the `src` folder in any Shopware project to be used for customizations. We recommend using this namespace, if you like to change the project structure, you can change the `App\` namespace in the `composer.json` file of your project. +By default, The namespace `App\` is registered to the `src` folder in any Shopware project to be used for customizations. We recommend using this namespace. To change the project structure, change the `App\` namespace in the project's `composer.json` file. ```php // /src/YourBundleName.php @@ -107,7 +105,7 @@ class YourBundleName extends Bundle } ``` -The bundle class needs to be registered in the `config/bundles.php` file of your project. +The bundle class must be registered in the project's `config/bundles.php` file. ```php // /config/bundles.php @@ -118,15 +116,15 @@ App\YourBundleName\YourBundleName::class => ['all' => true], ## Adding services, Twig templates, routes, and themes -You can add services, Twig templates, routes, etc. to your bundle like you would do in a plugin. Create `Resources/config/services.php` and `Resources/config/routes.php` files, or `Resources/views` for Twig templates. The bundle will be automatically detected and the files will be loaded. +You can add services, Twig templates, routes, etc. to your bundle just as you would to a plugin. Create `Resources/config/services.php` and `Resources/config/routes.php` files, or `Resources/views` for Twig templates. The bundle will be automatically detected and the files will be loaded. To mark your bundle as a theme, it's enough to implement the `Shopware\Core\Framework\ThemeInterface` interface in your bundle class. This will automatically register your bundle as a theme and make it available in the Shopware administration. -You can also add a `theme.json` file to define the theme configuration like [described here](../themes/theme-configuration.md). +You can also add a `theme.json` file to define the theme configuration like [described here](../themes/configuration/theme-configuration.md). ## Adding migrations -Migrations are not automatically detected in bundles. To enable migrations, you need to overwrite the `build` method in your bundle class like this: +Migrations are not automatically detected in bundles. To enable migrations, overwrite the `build` method in the bundle class: ```php // /src/YourBundleName.php @@ -147,14 +145,13 @@ class YourBundleName extends Bundle } ``` -As Bundles don't have a lifecycle, the migrations are not automatically executed. -You need to execute them manually via the console command: +As Bundles don't have a lifecycle, the migrations are not automatically executed. Execute them manually via the console command: ```bash bin/console database:migrate --all ``` -If you use [Deployment Helper](../../hosting/installation-updates/deployments/deployment-helper.md), you can add it to the `.shopware-project.yaml` file like this: +If you use [Deployment Helper](../../hosting/installation-updates/deployments/deployment-helper.md), you can add it to the `.shopware-project.yaml` file: ```yaml deployment: @@ -165,9 +162,7 @@ deployment: ## Integration into Shopware CLI -The Shopware CLI cannot detect bundles automatically. Therefore, the assets of the bundles are not built automatically. -You will need to adjust your project's `composer.json` file of your project to specify the path to the bundle. -Do this by adding the `extra` section to the `composer.json` file: +The Shopware CLI cannot detect bundles automatically. Therefore, bundle assets are not built automatically. Adjust the project's `composer.json` file to specify the path to the bundle. Do this by adding the `extra` section to the `composer.json` file: ```json { @@ -185,16 +180,13 @@ This will tell Shopware CLI where the bundle is located and its name. ## Next steps -Now that you know about the differences between a Symfony bundle and a Shopware plugin, you might also want to have a look into the following Symfony-specific topics and how they are integrated in Shopware 6: +Now that you know about the differences between a Symfony bundle and a Shopware plugin, review the following guides: * [Dependency Injection](../plugins/services/dependency-injection.md) * [Listening to events](../plugins/framework/event/listening-to-events.md) -::: info -Here are some useful videos explaining: - -* **[Bundle Methods in a plugin](https://www.youtube.com/watch?v=cUXcDwQwmPk)** -* **[Symfony services in Shopware 6](https://www.youtube.com/watch?v=l5QJ8EtilaY)** +Also check out these useful videos: -Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma). -::: +* [Bundle Methods in a plugin](https://www.youtube.com/watch?v=cUXcDwQwmPk) +* [Symfony services in Shopware 6](https://www.youtube.com/watch?v=l5QJ8EtilaY) +* The free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma) diff --git a/guides/plugins/plugins/checkout/cart/add-cart-processor-collector.md b/guides/plugins/plugins/checkout/cart/add-cart-processor-collector.md index d726d5d06f..5b331b3dd5 100644 --- a/guides/plugins/plugins/checkout/cart/add-cart-processor-collector.md +++ b/guides/plugins/plugins/checkout/cart/add-cart-processor-collector.md @@ -1,6 +1,6 @@ --- nav: - title: Add cart collector/processor + title: Add Cart Collector/Processor position: 10 --- diff --git a/guides/plugins/plugins/checkout/cart/customize-price-calculation.md b/guides/plugins/plugins/checkout/cart/customize-price-calculation.md index 389dd1bc9e..2827007607 100644 --- a/guides/plugins/plugins/checkout/cart/customize-price-calculation.md +++ b/guides/plugins/plugins/checkout/cart/customize-price-calculation.md @@ -7,6 +7,8 @@ nav: # Customize Price Calculation +## Overview + This guide explains how to globally adjust the calculation of product prices by decorating a single service, and includes a brief example. ## Prerequisites diff --git a/guides/plugins/plugins/content/cms/add-cms-block.md b/guides/plugins/plugins/content/cms/add-cms-block.md index 373c9df27e..fd4a5a726f 100644 --- a/guides/plugins/plugins/content/cms/add-cms-block.md +++ b/guides/plugins/plugins/content/cms/add-cms-block.md @@ -6,9 +6,9 @@ nav: # Add CMS Blocks -## What is a Block? +## Overview -A CMS block in Shopware is a fundamental structural component of the Shopping Experience (CMS) system. Understanding the hierarchy helps clarify what blocks are: +A CMS block in Shopware is a fundamental structural component of the Shopping Experience (CMS) system. Understanding the hierarchy helps clarify what blocks are. ### CMS Hierarchy @@ -184,7 +184,7 @@ You can create your own blocks or extend and reuse existing ones. Don't forget t ``` -The `block` is automatically passed to the template and contains meta data and configuration values. See the `CmsBlockDefinition.php` for a full overview. +The `block` is automatically passed to the template and contains meta data and configuration values. See the `CmsBlockDefinition.php` for a full overview. ### How to Render Slots diff --git a/guides/plugins/plugins/content/cms/add-cms-element.md b/guides/plugins/plugins/content/cms/add-cms-element.md index b556c577a9..0c0bdc515c 100644 --- a/guides/plugins/plugins/content/cms/add-cms-element.md +++ b/guides/plugins/plugins/content/cms/add-cms-element.md @@ -1,14 +1,14 @@ --- nav: - title: Add CMS element + title: Add CMS Element position: 20 --- # Add CMS Elements -## What is an Element? +## Overview -A CMS element in Shopware is the smallest content unit in the Shopping Experience (CMS) system. Understanding the hierarchy helps clarify what elements are: +A CMS element in Shopware is the smallest content unit in the Shopping Experience (CMS) system. Understanding the hierarchy helps clarify what elements are. ### CMS Hierarchy @@ -244,7 +244,7 @@ You can create your own elements or extend and reuse existing ones. Don't forget ``` -The `element` is automatically passed to the template and contains meta data and configuration values. See the `CmsSlotDefinition.php` for a full overview. +The `element` is automatically passed to the template and contains meta data and configuration values. See the `CmsSlotDefinition.php` for a full overview. ## Next steps diff --git a/guides/plugins/plugins/content/cms/add-data-to-cms-elements.md b/guides/plugins/plugins/content/cms/add-data-to-cms-elements.md index d57bbf4a4c..d7e9c7a8ee 100644 --- a/guides/plugins/plugins/content/cms/add-data-to-cms-elements.md +++ b/guides/plugins/plugins/content/cms/add-data-to-cms-elements.md @@ -1,12 +1,14 @@ --- nav: - title: Add data to CMS element + title: Add Data to CMS Element position: 40 --- # Add Data to CMS Element +## Overview + When creating custom CMS elements, you sometimes want to use more complex data types than text or boolean values, e.g., other entities such as media or products. In those cases you can implement a custom `CmsElementResolver` to resolve the configuration data. diff --git a/guides/plugins/plugins/content/media/add-custom-file-extension.md b/guides/plugins/plugins/content/media/add-custom-file-extension.md index a3870a4082..09ba451f2c 100644 --- a/guides/plugins/plugins/content/media/add-custom-file-extension.md +++ b/guides/plugins/plugins/content/media/add-custom-file-extension.md @@ -7,6 +7,8 @@ nav: # Add Custom Media File Extensions +## Overview + Not all media types can be uploaded to Shopware with the Administration's Media module. This guide explains how to use plugins to add custom media file extensions. ## Prerequisites diff --git a/guides/plugins/plugins/content/media/remote-thumbnail-generation.md b/guides/plugins/plugins/content/media/remote-thumbnail-generation.md index 1e760a2804..61270ff85d 100644 --- a/guides/plugins/plugins/content/media/remote-thumbnail-generation.md +++ b/guides/plugins/plugins/content/media/remote-thumbnail-generation.md @@ -11,6 +11,8 @@ nav: This feature is available starting with Shopware version 6.6.4.0 ::: +## Overview + In certain scenarios, you might want to disable the filesystem thumbnail generation in Shopware and use an external CDN service to handle the thumbnails. This can be beneficial for performance and scalability reasons. When the remote thumbnail configuration is enabled, the thumbnail images and thumbnail records in the database are not generated by Shopware, but by the external service. diff --git a/guides/plugins/plugins/content/sitemap/add-custom-sitemap-entries.md b/guides/plugins/plugins/content/sitemap/add-custom-sitemap-entries.md index 519eaa085b..0c0fd47dfb 100644 --- a/guides/plugins/plugins/content/sitemap/add-custom-sitemap-entries.md +++ b/guides/plugins/plugins/content/sitemap/add-custom-sitemap-entries.md @@ -57,7 +57,7 @@ It then has to be registered to the [service container][dependency-injection] us It has to provide three methods: - `getDecorated`: Just throw an exception of type `DecorationPatternException` here. This is done for the sake of extending -a class via decoration. Learn more about this [here][adjusting-services]. +a class via decoration. Learn more about this [here](../../services/adjusting-service.md). - `getName`: A technical name for your custom URLs - `getUrls`: The main method to take care of. It has to return an instance of `Shopware\Core\Content\Sitemap\Struct\UrlResult`, containing an array of all URLs to be added. @@ -235,6 +235,6 @@ All of those instances are then stored in an array, which in return is passed to This completes the implementation. Your custom URLs will now be included in the generated sitemap. [dynamic-entity-seo]: ../seo/add-custom-seo-url#dynamic-seo-urls-for-entities -[dependency-injection]: ../../plugin-fundamentals/dependency-injection +[dependency-injection]: ../../services/dependency-injection.md [custom-complex-data]: ../../framework/data-handling/add-custom-complex-data [adjusting-services]: ../../plugin-fundamentals/adjusting-service diff --git a/guides/plugins/plugins/content/sitemap/remove-sitemap-entries.md b/guides/plugins/plugins/content/sitemap/remove-sitemap-entries.md index 8fe36175d4..6d5a06a5d6 100644 --- a/guides/plugins/plugins/content/sitemap/remove-sitemap-entries.md +++ b/guides/plugins/plugins/content/sitemap/remove-sitemap-entries.md @@ -1,11 +1,13 @@ --- nav: - title: Remove sitemap entries + title: Remove Sitemap Entries position: 30 --- # Remove Sitemap Entries +## Overview + This guide shows how to exclude specific URLs from the sitemap. ## Using the configuration diff --git a/guides/plugins/plugins/creating-plugins.md b/guides/plugins/plugins/creating-plugins.md new file mode 100644 index 0000000000..d130d10e20 --- /dev/null +++ b/guides/plugins/plugins/creating-plugins.md @@ -0,0 +1,219 @@ +--- +nav: + title: Creating Plugins + position: 20 + +--- + +## Creating Plugins + +This guide walks you through creating and scaffolding a basic Shopware plugin so it can be installed locally on your Shopware 6 instance. + +::: info +Refer to this video on [Creating a plugin](https://www.youtube.com/watch?v=_Tkoq5W7woI) that shows how to bootstrap a plugin. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma). +::: + +## Prerequisites + +You'll need: + +* PHP knowledge +* A running Shopware 6 instance; refer to our [Install Shopware 6](../../installation/index.md) guide +* full file system and command line access + +`/custom/plugins` contains all plugins from the Shopware store. You install and manage these plugins via the Shopware Administration. + +## 1. Choose a name + +Use **UpperCamelCase**, which means that your plugin name must begin with a capital letter too. Whenever possible, begin it with a company prefix to avoid duplicate names (e.g., `SwagBasicExample`). Choose a name that describes your plugin as succinctly and clearly as possible. + +::: info +A vendor prefix is required if you plan to publish your plugin in the [Shopware Community Store](https://store.shopware.com/en). +::: + +## 2. Generate the plugin structure + +From your Shopware project's root directory, run: + +```bash +bin/console plugin:create SwagBasicExample +``` + +Optionally, you can run this command to create a demo configuration file in the `Resources` directory: + +```bash +bin/console plugin:create SwagBasicExample --create-config +``` + +The command will generate all the basic required files that are needed for an extension to be installed on a Shopware instance. Make sure to adjust the namespace in the files as per your need. + +### Structure for long-term maintainability + +When building multiple custom features, consider grouping related functionality inside a single plugin or repository instead of creating many isolated plugins. + +Keeping extensions in one repository with shared CI, shared static analysis rules, and unified coding standards makes future upgrades significantly easier to manage. + +## 3. Plugin structure + +Generated location: + +```bash +custom/plugins/SwagBasicExample +``` + +Minimal structure: + +```text +SwagBasicExample/ +├── composer.json +└── src/ + └── SwagBasicExample.php +``` + +Basic plugin class: + +```php + +Example composer.json + +```json +// /composer.json +{ + "name": "swag/basic-example", + "description": "Description for the plugin SwagBasicExample", + "version": "1.0.0", + "type": "shopware-platform-plugin", + "license": "MIT", + "authors": [ + { + "name": "Shopware" + } + ], + "require": { + "shopware/core": "~6.6.0" + }, + "extra": { + "shopware-plugin-class": "Swag\\BasicExample\\SwagBasicExample", + "label": { + "de-DE": "Der angezeigte lesbare Name für das Plugin", + "en-GB": "The displayed readable name for the plugin" + }, + "description": { + "de-DE": "Beschreibung in der Administration für das Plugin", + "en-GB": "Description in the Administration for this plugin" + } + }, + "autoload": { + "psr-4": { + "Swag\\BasicExample\\": "src/" + } + } +} +``` + + +::: warning +If you change the `autoload.psr-4` path (for example, not using `src/`), adjust your directory structure accordingly. +::: + +::: Info +Set up [CI](../../development/testing/ci.md) early. Run static analysis, tests, and `shopware-cli extension build` in CI so your plugin ZIP is reproducible and safe to promote across environments. +::: + +## Add Shopware Packagist (optional) + +Shopware's Packagist instance enables management of Shopware Store plugins directly in the `composer.json`. To add the repository to your project, run: + +```bash +composer config repositories.shopware composer https://packages.shopware.com +``` + +Authentication via API token is required. Refer to ["Using Composer for plugin installation in Shopware"](https://www.shopware.com/en/news/using-composer-for-plugin-installation-in-shopware/) for detailed information. + +### Manual creation (optional) + +In most cases, you should use `bin/console plugin:create`. Manual creation is only useful if you need full control over the structure or are working in a custom setup. + +Navigate to `custom/plugins` to create a new directory named after your plugin, so that it looks like this: + +```bash +custom/plugins/SwagBasicExample +``` + +Minimal structure: + +```text +SwagBasicExample/ +├── composer.json +└── src/ + └── SwagBasicExample.php +``` + +- **namespace**: here, it's `Swag\BasicExample`. We recommend using a combination of your manufacturer prefix and the technical name to name it. +- **`src/` directory**: recommended but not strictly required. +- **PHP class**: `SwagBasicExample.php`, which you name after your plugin. + +The new class `SwagBasicExample` must extend Shopware's abstract plugin class, `Shopware\Core\Framework\Plugin`: + +```php +// /src/SwagBasicExample.php + [\Shopware\Core\Framework\Routing\StoreApiRouteScope::ID]])]`. +* Response decorators must extend `StoreApiResponse`. + +Route design: + +* A route represents a single, focused functionality. +* A route must return a `StoreApiResponse`, to convert to JSON. +* A route response can only contain one object. +* Routes may be decorated to extend behavior. + +Storefront integration: + +* Storefront controllers must not access repositories directly. +* Controllers must call Store API routes. +* Page loaders and controllers may call multiple routes. +* Business logic belongs in Store API routes, not in controllers. + +## Next steps + +Review our guides for [adding routes](add-store-api-route.md) and [overriding existing routes](override-existing-route.md). diff --git a/guides/plugins/plugins/framework/store-api/override-existing-route.md b/guides/plugins/plugins/framework/store-api/override-existing-route.md index 73d454ac5d..95123ef0d7 100644 --- a/guides/plugins/plugins/framework/store-api/override-existing-route.md +++ b/guides/plugins/plugins/framework/store-api/override-existing-route.md @@ -1,6 +1,6 @@ --- nav: - title: Override existing route + title: Override Existing Route position: 30 --- diff --git a/guides/plugins/plugins/framework/system-check/add-custom-check.md b/guides/plugins/plugins/framework/system-check/add-custom-check.md index 04497e88d1..36e3b547e2 100644 --- a/guides/plugins/plugins/framework/system-check/add-custom-check.md +++ b/guides/plugins/plugins/framework/system-check/add-custom-check.md @@ -1,11 +1,13 @@ --- nav: - title: Add custom check + title: Add Custom Check position: 10 --- -# Overview +# Add Custom Check + +## Overview In this guide, we will be building a dummy example of a custom system check that verifies if the local system has enough disk space to operate normally. diff --git a/guides/plugins/plugins/index.md b/guides/plugins/plugins/index.md index e2de9d1356..3d9a202c10 100644 --- a/guides/plugins/plugins/index.md +++ b/guides/plugins/plugins/index.md @@ -7,58 +7,56 @@ nav: # Plugins -Plugins are Shopware's server-side extension type, giving you deep integration with the e-commerce platform. They allow you to extend, overwrite, and modify Shopware’s core capabilities. Unlike apps and themes, plugins run directly inside the shop environment and can interact tightly with the system. - -You will likely create a plugin when you need deep server-side integration or require complex functionalities such as: - -- Custom price calculation -- Product imports -- Custom content/product logic -- Integrating third-party identity providers -- Dynamic validations -- Customer tracking or behavioral logic - -| Goal | Guide | -|------|--------| -| Create a new plugin from scratch | [Plugin base guide](plugin-base-guide.md) | -| Add Admin configuration fields (`config.xml`) | [Add plugin configuration](plugin-fundamentals/add-plugin-configuration.md) | -| Read config in PHP, Admin JS, or Storefront | [Use plugin configuration](plugin-fundamentals/use-plugin-configuration.md) | -| React to domain events | [Listening to events](../plugins/framework/event/listening-to-events.md) | -| Register services & DI | [Dependency injection](../plugins/services/dependency-injection.md) | -| Database changes | [Database migrations](../plugins/database/database-migrations.md) | -| Composer dependencies in a plugin | [Adding Composer dependencies](../plugins/dependencies/using-composer-dependencies.md) | -| More topics | [Plugin fundamentals](plugin-fundamentals/index.md) (logging, cache, routes, …) | +Plugins are Shopware’s PHP-based, server-side extension type for enhancing platform functionality. They allow you to extend, overwrite, and modify Shopware's core capabilities at runtime. -::: info -If your extension focuses primarily on Storefront design changes, a [theme plugin](../themes/theme-base-guide.md) is often the best choice. -::: +Plugins run directly inside the Shopware environment and provide full access to: -## Types of plugins +* The Symfony service container +* Events and subscribers +* Database layer and migrations +* CLI commands and scheduled tasks +* Administration extensions +* Storefront extensions -Shopware plugins differ in their folder structure and functionality. +Technically, plugins are extensions of [Symfony bundles](./bundle.md). They follow a defined directory structure and, when used as managed extensions, provide a lifecycle (install, update, deactivate, uninstall). -### Plugins +Plugins can ship their own assets, controllers, services, and tests, enabling deep platform and full extensibility across core and custom functionality. -`/custom/plugins` contains all plugins from the Shopware store. You install and manage these plugins via the Shopware Administration. +## When to create and use a plugin -### Static plugins +You will typically use a plugin when you need to: -`/custom/static-plugins` contains all project-specific plugins that are typically committed to the Git repository. +* Implement custom business logic for customer tracking, content, products and product imports, etc. +* Modify or customize checkout or pricing behavior or calculations +* Add database entities or migrations +* Listen to and react to platform events +* Register services in the DI container +* Extend the Administration with custom modules +* Add backend commands or scheduled tasks +* Integrate third-party systems, including identity providers +* Enable dynamic validations -:::info -The Shopware Administration does not detect static plugins. The project must require them via Composer for them to be installable. +:::Info +For infrastructure and external system integrations (e.g., Redis, Elasticsearch, or custom APIs), refer to the dedicated [integration guides](../plugins/integrations/index.md /integrations). ::: -```bash -# You can find the vendor/package name in the plugin's composer.json file under "name" -composer req / -``` +### Choosing the right extension type + +| Requirement | Use | +|-------------|------| +| Backend logic or deep integration | Plugin | +| Storefront styling or template overrides only | Plugin-based Theme | +| SaaS-based integration without server access | App | + +::: info +If your extension focuses only on design changes, a simple template adjustment, typically done through a plugin-based [theme](../themes/index.md), may be the best choice. +::: -### Symfony bundle / Shopware bundle +## Plugin types -You can also use Shopware/Symfony [bundles](bundle.md) instead of plugins. Bundles are installed bundles with Composer and offer full control over projects. They are not managed by the Shopware Administration, and are a good choice when you want to avoid plugin lifecycle handling or Administration management. +Shopware supports multiple plugin models, which differ in their folder structure and functionality. -## Feature comparison +### Feature comparison | Feature | Plugin | Static Plugin | Shopware Bundle | Symfony Bundle | |-----------------------------------------------|--------------------|-------------------------|---------------------------------|---------------------------------| @@ -68,3 +66,67 @@ You can also use Shopware/Symfony [bundles](bundle.md) instead of plugins. Bundl | Can be managed in Administration | Yes | No | No | No | | Can be a Theme | Yes | Yes | Yes | No | | Can modify Admin / Storefront with JS/CSS | Yes | Yes | Yes | No | + +### Static plugins (recommended) + +Project-specific static plugins live in `/custom/static-plugins`, which contains all project-specific plugins that are typically committed to the Git repository. The Shopware Administration does not detect static plugins. They must be required via Composer before they can be installed and activated: + +```bash +# You can find the vendor/package name in the plugin's composer.json file under "name" +composer req / +``` + +Static plugins are ideal for: + +* Custom project logic +* Team development workflows +* CI/CD pipelines +* Long-term maintainability + +Characteristics: + +* Versioned in Git +* Live inside your project repository +* Are installed and managed via Composer +* Integrate cleanly into deployment workflows +* No dependency on Administration installation +* Offer clear separation between project code and marketplace extensions + +### Managed plugins + +Managed plugins are commonly used for marketplace-distributed extensions. They are located in `/custom/plugins` and are typically installed and managed via the Shopware Administration. + +### Bundles + +Symfony-based [bundles](../plugins/bundle.md) are installed via Composer. They do not have a Shopware plugin lifecycle and are not managed via the Administration. + +Bundles are useful when you want: + +* Full Symfony-level control +* No lifecycle handling or Administration management +* Pure project-level customization + +Choose the extension model that best fits your distribution and maintenance strategy. + +## Architectural recommendation + +There is no need to create a separate plugin for every distinct functionality. + +For custom projects, it is often preferable to: + +* Maintain all custom logic in a single repository +* Share one CI pipeline and one set of static analysis rules +* Organize functionality through clean internal directory structure + +It does not matter whether static plugins or Symfony bundles internally are used, as much as having: + +* Clear domain boundaries +* Consistent structure +* Centralized quality control + +It is perfectly valid to ship multiple separate plugins, but keeping them in a single repository with unified tooling significantly reduces long-term maintenance and upgrade friction. + +## Next steps + +* Review the [Plugin base guide](./plugin-base-guide.md) to learn how to create plugins +* Make note of [CI](../../development/testing/ci.md) and other testing guidance to prevent upgrade-related regressions diff --git a/guides/plugins/plugins/install-activate-plugin.md b/guides/plugins/plugins/install-activate-plugin.md new file mode 100644 index 0000000000..ef4ccd9b29 --- /dev/null +++ b/guides/plugins/plugins/install-activate-plugin.md @@ -0,0 +1,55 @@ +--- +nav: + title: Install and Activate Plugins + position: 30 + +--- + +# Install and Activate Plugins + +This guide explains how to install and activate a newly created plugin. + +From your Shopware project root directory, refresh the list of plugins: + +```bash +bin/console plugin:refresh +``` + +A warning about the `version` field of the `composer.json` file might appear; this can be ignored. You should see a list like this: + +```bash +Shopware Plugin Service +======================= + + ------------------------------ -------------------------------------------- ----------- ----------------- ---------------------------- ----------- -------- ------------- + Plugin Label Version Upgrade version Author Installed Active Upgradeable + ------------------------------ -------------------------------------------- ----------- ----------------- ---------------------------- ----------- -------- ------------- + SwagBasicExample The displayed readable name for the plugin 1.0.0 Shopware No No No + ------------------------------ -------------------------------------------- ----------- ----------------- ---------------------------- ----------- -------- ------------- +``` + +This output is a **good sign**, because this means Shopware recognized your plugin successfully. + +Now install and activate: + +```bash +bin/console plugin:install --activate SwagBasicExample +``` + +This should print the following output: + +```bash +Shopware Plugin Lifecycle Service +================================= + + Install 1 plugin(s): + * The displayed readable name for the plugin (v1.0.0) + + Plugin "SwagBasicExample" has been installed and activated successfully. +``` + +If successful, your plugin is now active and ready to use! + +## Next steps + +Review our [plugin lifecycle](../plugins/plugin-fundamentals/plugin-lifecycle.md) guide next. diff --git a/guides/plugins/plugins/integrations/commercial/customer-specific-pricing.md b/guides/plugins/plugins/integrations/commercial/customer-specific-pricing.md index dab744a1c2..42c56ed537 100644 --- a/guides/plugins/plugins/integrations/commercial/customer-specific-pricing.md +++ b/guides/plugins/plugins/integrations/commercial/customer-specific-pricing.md @@ -5,7 +5,9 @@ nav: --- -# Customer-specific Pricing +# Customer-Specific Pricing + +## Overview The Customer-specific pricing feature enables significant advances in pricing model capabilities in the Shopware 6 ecosystem. diff --git a/guides/plugins/plugins/integrations/commercial/index.md b/guides/plugins/plugins/integrations/commercial/index.md index 04de3a0c7b..22d2f6f526 100644 --- a/guides/plugins/plugins/integrations/commercial/index.md +++ b/guides/plugins/plugins/integrations/commercial/index.md @@ -11,5 +11,5 @@ The Commercial plugin extends Shopware with advanced enterprise features availab This section documents the API-first features provided by the Commercial plugin and how to integrate them into your systems: -* [Multi-Inventory](./multi-inventory.md) * [Customer-specific Pricing](./customer-specific-pricing.md) +* [Multi-Inventory](./multi-inventory.md) diff --git a/guides/plugins/plugins/integrations/commercial/multi-inventory.md b/guides/plugins/plugins/integrations/commercial/multi-inventory.md index c08e6a9529..9ec19cfed8 100644 --- a/guides/plugins/plugins/integrations/commercial/multi-inventory.md +++ b/guides/plugins/plugins/integrations/commercial/multi-inventory.md @@ -7,6 +7,10 @@ nav: # Multi-Inventory +## Overview + +Multi-Inventory extends Shopware’s stock management by letting you manage inventory across multiple warehouses and warehouse groups. It is designed primarily for API-first integrations with ERP systems, while also providing Administration support for manual management and inspection. This guide explains the required setup, the underlying data model, and how to work with the feature through the Admin API. + ## Pre-requisites and setup ### Commercial Plugin diff --git a/guides/plugins/plugins/integrations/elasticsearch/add-product-entity-extension-to-elasticsearch.md b/guides/plugins/plugins/integrations/elasticsearch/add-product-entity-extension-to-elasticsearch.md index e0141eeeff..7a9ccaeed2 100644 --- a/guides/plugins/plugins/integrations/elasticsearch/add-product-entity-extension-to-elasticsearch.md +++ b/guides/plugins/plugins/integrations/elasticsearch/add-product-entity-extension-to-elasticsearch.md @@ -1,6 +1,6 @@ --- nav: - title: Add product entity extension to elasticsearch + title: Add Product Entity Extension to Elasticsearch position: 20 --- diff --git a/guides/plugins/plugins/integrations/index.md b/guides/plugins/plugins/integrations/index.md new file mode 100644 index 0000000000..0b92ad078f --- /dev/null +++ b/guides/plugins/plugins/integrations/index.md @@ -0,0 +1,15 @@ +--- +nav: + title: Integrations + position: 30 +--- + +# Integrations + +Plugins are commonly used to integrate external systems and infrastructure services into Shopware. Typical scenarios that go beyond basic plugin setup include: + +* Commercial & API-based integrations, including [customer-specific pricing](./commercial/customer-specific-pricing.md), [multi-inventory](./commercial/multi-inventory.md), and [API](../../../development/integrations-api/index.md) +* Infrastructure integrations, including [Redis](redis.md) and [Elasticsearch](./elasticsearch/index.md) +* Extended search capabilities, including [adding product entity extensions to Elasticsearch](./elasticsearch/add-product-entity-extension-to-elasticsearch.md) + +Use these guides when a plugin needs to connect to external services, extend core infrastructure, or integrate ERP and pricing systems. diff --git a/guides/plugins/plugins/plugin-base-guide.md b/guides/plugins/plugins/plugin-base-guide.md index af947177e8..c863a34cde 100644 --- a/guides/plugins/plugins/plugin-base-guide.md +++ b/guides/plugins/plugins/plugin-base-guide.md @@ -9,202 +9,33 @@ nav: ## Overview -Plugins in Shopware are essentially an extension of [Symfony bundles](../plugins/bundle.md). Such bundles and plugins can provide their own resources like assets, controllers, services or tests, which you'll learn in the next guides. A plugin is the main way to extend your Shopware 6 instance programmatically. +This guide outlines the typical development flow when creating a Shopware plugin, using the recommended static plugin approach. Core concepts apply to all plugin types. Not every plugin requires all steps. -This section guides you through the basics of creating a plugin from scratch, which can then be installed on your Shopware 6 instance. Refer to the [Shopware 6 Installation guide](../../../guides/installation/index.md). +## Typical plugin development flow -## Prerequisites +1. [Create the plugin structure](creating-plugins.md) +2. [Install and activate the plugin](install-activate-plugin.md) +3. [Understand the plugin lifecycle](../plugins/plugin-fundamentals/plugin-lifecycle.md) +4. [Add plugin configuration](../plugins/plugin-fundamentals/add-plugin-configuration.md) +5. [Register services](../plugins/services/index.md) and use [dependency injection](../plugins/services/dependency-injection.md) +6. [Listen to events](../plugins/framework/event/listening-to-events.md) or [decorate services](../plugins/services/adjusting-service.md#decorating-the-service) +7. Extend the platform (either or both): [Storefront](../plugins/storefront/index.md), [Administration](../plugins/administration/index.md) +8. [Add database migrations](../plugins/database/database-migrations.md) (if required) +9. [Add scheduled tasks](../plugins/plugin-fundamentals/add-scheduled-task.md) or [CLI commands](../plugins/plugin-fundamentals/add-custom-commands.md) (if required) +10. Add configuration: [npm](../plugins/dependencies/using-npm-dependencies.md), [Composer](../plugins/dependencies/using-composer-dependencies.md) (if required) +11. [Write tests](../../development/testing/index.md): CI and upgrade safety: Configure [CI](../../development/testing/ci.md) to run static analysis, tests, and produce reproducible artifacts to avoid upgrade regressions. +12. Add [diagnostics](../plugins/plugin-fundamentals/logging.md) -* a running Shopware 6 instance -* full access to both the files and the command line -* PHP knowledge +## Upgrade readiness -## Create your first plugin +Design plugins so that: -Let's get started with creating your plugin by finding a proper name for it. +* [Migrations](../../upgrades-migrations/index.md) are idempotent +* Lifecycle logic is minimal and predictable +* Domain logic is encapsulated behind services -### Name your plugin +Upgrades are easier when the plugin surface area is small and well-structured. -First, you need to find a name for your plugin. We're talking about a technical name here, so it needs to describe your plugins functionality as short as possible, written in UpperCamelCase. To prevent issues with duplicated plugin names, you should add a shorthand prefix for your company. Shopware uses "Swag" as a prefix for that case. For this example guide we'll use the plugin name **SwagBasicExample.** +## Getting started -::: info -Using a prefix for your plugin name is not just a convention we'd recommend, but a hard requirement if you want to publish your plugin in the [Shopware Extension Store](https://store.shopware.com/en). -::: - -### Create the plugin with `plugin:create` - -Now that you've found your name, it's time to actually create your plugin. - -Shopware provides a command that generates the basic plugin structure. Go to your Shopware project root directory and run: - -```bash -bin/console plugin:create SwagBasicExample -``` - -You can also pass the optional `-c` or `--create-config` flag to create a demo configuration file in the `Resources` directory. The command will generate all the basic required files that are needed for an extension to be installed on a Shopware instance. Make sure to adjust the namespace in the files as needed to match your plugin. - -A minimal plugin setup includes: - -* `src/.php`: the plugin base class extending `Shopware\Core\Framework\Plugin` -* `composer.json`: package metadata such as `type: shopware-platform-plugin` and autoload configuration - -If you used `-c` or `--create-config` the command also creates a demo configuration file in the Resources directory. Otherwise, `src/Resources/config/config.xml` is optional and can be added later for Administration settings. - -### Create the plugin structure manually - -To create the structure manually, please follow the instructions below. - -First, navigate to the directory `custom/plugins` in your Shopware 6 installation. Inside the `plugins` directory, create a new directory named after your plugin. It should look like this: `custom/plugins/SwagBasicExample` - -By convention, you'll have another directory called `src`. This is not required, but recommended. And that's it for the directory structure for now. - -Inside your `src` directory, create a PHP class named after your plugin, `SwagBasicExample.php`. This new class `SwagBasicExample` has to extend from Shopware's abstract Plugin class, which is `Shopware\Core\Framework\Plugin`. - -Apart from this, only the namespace is missing. You can freely define it, but we'd recommend using a combination of your manufacturer prefix and the technical name. In this `guide` this would be `Swag\BasicExample`: - -```php -// /src/SwagBasicExample.php -/composer.json -{ - "name": "swag/basic-example", - "description": "Description for the plugin SwagBasicExample", - "version": "1.0.0", - "type": "shopware-platform-plugin", - "license": "MIT", - "authors": [ - { - "name": "Shopware" - } - ], - "require": { - "shopware/core": "~6.7.0" - }, - "extra": { - "shopware-plugin-class": "Swag\\BasicExample\\SwagBasicExample", - "label": { - "de-DE": "Der angezeigte lesbare Name für das Plugin", - "en-GB": "The displayed readable name for the plugin" - }, - "description": { - "de-DE": "Beschreibung in der Administration für das Plugin", - "en-GB": "Description in the Administration for this plugin" - } - }, - "autoload": { - "psr-4": { - "Swag\\BasicExample\\": "src/" - } - } -} -``` - -There's another two things that you need to know: - -1. The `shopware-plugin-class` information. This has to point to the plugin's base PHP class. The one, that you've previously created. -2. The whole `autoload` part. This has to mention your [PSR-4](https://www.php-fig.org/psr/psr-4/) namespace. So if you'd like to have another namespace for your plugin, this is the place to go. - -::: warning -The path you've configured in the configuration `autoload.psr-4`, `src/` in this case, will be referred to as `/src` in almost all code examples. If you're using a custom path here, e.g. just a slash `/`, then the examples would be `/` here instead. -::: - -And that's it. The basic structure and all necessary files for your plugin to be installable are done. - -::: info -Refer to this video on **[The composer.json plugin file](https://www.youtube.com/watch?v=CY3SlfwkTm8)** that explains the basic structure of the `composer.json` plugin file. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma). -::: - -## Install your plugin - -You can safely install your plugin now and Shopware should easily recognize it like this. - -Open up your command line terminal and navigate to your Shopware 6 directory, the one which also contains the `custom` directory. - -Once inside there, you need to refresh the list of plugins, that Shopware knows yet. This is done with the following command: - -```bash -php bin/console plugin:refresh -``` - -There might be a warning appearing regarding the `version` of the `composer.json` file, but you can safely ignore that. You should end up with a list like the following: - -```bash -Shopware Plugin Service -======================= - - ------------------------------ -------------------------------------------- ----------- ----------------- ---------------------------- ----------- -------- ------------- - Plugin Label Version Upgrade version Author Installed Active Upgradeable - ------------------------------ -------------------------------------------- ----------- ----------------- ---------------------------- ----------- -------- ------------- - SwagBasicExample The displayed readable name for the plugin 1.0.0 Shopware No No No - ------------------------------ -------------------------------------------- ----------- ----------------- ---------------------------- ----------- -------- ------------- -``` - -This output is a **good sign**, because this means Shopware recognized your plugin successfully. But it's not installed yet, so let's do that. - -```bash -php bin/console plugin:install --activate SwagBasicExample -``` - -This should print the following output: - -```bash -Shopware Plugin Lifecycle Service -================================= - - Install 1 plugin(s): - * The displayed readable name for the plugin (v1.0.0) - - Plugin "SwagBasicExample" has been installed and activated successfully. -``` - -And that's basically it. **You've just successfully created your Shopware 6 plugin!** - -## Next steps - -These guides may be of interest when creating your first plugin: - -* [Installing data with your plugin](../../../guides/plugins/plugins/database/database-migrations.md) -* [Learn more about the plugin lifecycle methods](../../../guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md) -* [Adding a configuration to your plugin](../../../guides/plugins/plugins/plugin-fundamentals/add-plugin-configuration.md) -* [Learning about the service container](../../../guides/plugins/plugins/services/dependency-injection.md) -* [Adding a custom service](../../../guides/plugins/plugins/services/add-custom-service.md) -* [Start listening to events](../../../guides/plugins/plugins/framework/event/listening-to-events.md) +The first step is to [create the plugin structure](../plugins/creating-plugins.md). diff --git a/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md b/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md index 90ecd35a27..b987a72e42 100644 --- a/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md +++ b/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md @@ -1,6 +1,6 @@ --- nav: - title: Add custom CLI commands + title: Add Custom CLI Commands position: 90 --- @@ -18,6 +18,6 @@ $services->set(Swag\BasicExample\Command\ExampleCommand::class) Commands registered as services in a Shopware plugin are automatically available via `bin/console`. -## More interesting topics +## Other interesting topics * [Adding a scheduled task](add-scheduled-task) diff --git a/guides/plugins/plugins/plugin-fundamentals/add-plugin-configuration.md b/guides/plugins/plugins/plugin-fundamentals/add-plugin-configuration.md index eed8483784..2274a54eb7 100644 --- a/guides/plugins/plugins/plugin-fundamentals/add-plugin-configuration.md +++ b/guides/plugins/plugins/plugin-fundamentals/add-plugin-configuration.md @@ -1,30 +1,31 @@ --- nav: - title: Add plugin configuration - position: 10 + title: Add Plugin Configuration + position: 20 --- # Add Plugin Configuration -The Shopware plugin system lets you define a configuration screen in the Administration for your plugin using `config.xml` only. No custom Admin templates are required. +Shopware allows you to define a configuration page for your plugin using a `config.xml` file. No custom Administration module or knowledge of templating is required. ::: info Related guide -See [Use plugin configuration](use-plugin-configuration.md) for more details. +See [Use plugin configuration](use-plugin-configuration.md) for additional guidance. ::: ## Prerequisites -To build your own configuration page for your plugin, you first need a plugin as base. -Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide.md). +A running plugin. Review the [Plugin Base Guide](../plugin-base-guide.md) for instructions. ## Create your plugin configuration -Related resources: [Adding a plugin configuration (YouTube)](https://www.youtube.com/watch?v=XXcmgKBRh-s), [Backend Development](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma). +::: info +This video is part of the free Shopware Academy online training ["Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma). +::: + +Create `src/Resources/config/config.xml` inside your plugin. The content of the `config.xml` will be dynamically rendered in the Administration. -All you need to do is create a `config.xml` file inside a `Resources/config` directory in your plugin root. -The content of the `config.xml` will be dynamically rendered in the Administration. -Below you'll find an example structure: +An example structure: ```text └── plugins @@ -43,10 +44,9 @@ As you now know how to create configurations, you can start to fill it with life ### Cards in your configuration -The `config.xml` follows a simple syntax. -You can organize the content in `` elements. -Every `config.xml` must contain a minimum of one `` element and each `` must contain one `` and at least one `<input-field>`. -See the minimum `config.xml` below: +The `config.xml` follows a simple syntax. You can organize the content in `<card>` elements. + +Every `config.xml` must contain at least one `<card>` element with a `<title>` and at least one `<input-field>`. See the minimum `config.xml` below: ::: code-group @@ -95,8 +95,11 @@ Your `<input-field>` can be of different types, this is managed via the `type` a Unless defined otherwise, your `<input-field>` will be a text field. Below you'll find a list of all available `<input-field type="?">`. -| Type | Configuration settings | Renders | Default value example | -|:--------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------|:----------------------------------------| +<details> +<summary>Supported input field types</summary> + +| Type | Configuration settings | Renders | Default value example | +|:--------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:------------------|:----------------------------------------| | text | [copyable](add-plugin-configuration.md#copyable), [placeholder](add-plugin-configuration.md#label-placeholder-and-help-text), [length](add-plugin-configuration.md#text-length-restrictions) | Text field | Some text | | textarea | [copyable](add-plugin-configuration.md#copyable), [placeholder](add-plugin-configuration.md#label-placeholder-and-help-text) | Text area | Some more text | | text-editor | [placeholder](add-plugin-configuration.md#label-placeholder-and-help-text) | HTML editor | Some text with HTML `<div>`tags`</div>` | @@ -113,6 +116,8 @@ Below you'll find a list of all available `<input-field type="?">`. | single-select | [options](add-plugin-configuration.md#options), [placeholder](add-plugin-configuration.md#label-placeholder-and-help-text) | Single-Select box | option_id | | multi-select | [options](add-plugin-configuration.md#options), [placeholder](add-plugin-configuration.md#label-placeholder-and-help-text) | Multi-Select box | [option_id1, option_id2] | +</details> + ### Input field settings These settings are used to configure your `<input-field>`. @@ -417,10 +422,8 @@ Full multi-card `config.xml` example (collapse to focus on smaller snippets abov ## Add values to your configuration -After adding your input fields to the `config.xml`, save and refresh the Administration. Then open the **Extensions → My extensions → Plugins** tab, find your plugin, and open **Configure** (or the plugin’s configuration action). Use the **Configuration** tab to enter values for your fields. *(Apps use a separate tab; plugin settings are under **Plugins**.)* +After adding your input fields to the `config.xml`, save and refresh the Administration. Navigate from the sidebar to the **Extensions → My extensions → Plugins** tab, find your plugin, and click **Configure** (or the plugin’s configuration action). Use the **Configuration** tab to enter values for your fields. (Apps use a separate tab.) ## Next steps -Now you've added your own plugin configuration. -But how do you actually read which configurations the shop owner used? -This will be covered in our guide about [Using the plugin configuration](use-plugin-configuration.md). +Now that your configuration is defined, review the [Using the plugin configuration](use-plugin-configuration.md) guide to use it in your plugin logic. diff --git a/guides/plugins/plugins/plugin-fundamentals/add-scheduled-task.md b/guides/plugins/plugins/plugin-fundamentals/add-scheduled-task.md index f4c69e14a2..bcb539191c 100644 --- a/guides/plugins/plugins/plugin-fundamentals/add-scheduled-task.md +++ b/guides/plugins/plugins/plugin-fundamentals/add-scheduled-task.md @@ -1,14 +1,12 @@ --- nav: - title: Add scheduled task + title: Add Scheduled Task position: 100 --- # Add Scheduled Task -## Overview - Quite often one might want to run any type of code on a regular basis, e.g. to clean up very old entries every once in a while, automatically. Usually known as "Cronjobs", Shopware 6 supports a `ScheduledTask` for this. ## Prerequisites diff --git a/guides/plugins/plugins/plugin-fundamentals/logging.md b/guides/plugins/plugins/plugin-fundamentals/logging.md index 5275b11d47..45ef94236e 100644 --- a/guides/plugins/plugins/plugin-fundamentals/logging.md +++ b/guides/plugins/plugins/plugin-fundamentals/logging.md @@ -1,3 +1,10 @@ +--- +nav: + title: Logging + position: 10 + +--- + # Logging ## Overview diff --git a/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md b/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md index 9da908f428..8989d1c102 100644 --- a/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md +++ b/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md @@ -1,13 +1,15 @@ --- nav: title: Plugin Lifecycle Methods - position: 140 + position: 40 --- # Plugin Lifecycle Methods -Shopware builds upon the `Symfony Bundle System` to extend its functionality. Whenever you create a Shopware plugin, you have to extend the `Shopware\Core\Framework\Plugin` class. If you investigate this class, you will see that this class extends `Shopware\Core\Framework\Bundle`, which in return extends the Symfony's `Bundle` class: +## Overview + +When creating a Shopware plugin, you must extend the `Shopware\Core\Framework\Plugin` class. This extends `Shopware\Core\Framework\Bundle`, which in turn extends the Symfony `Bundle` class: ```php // @@ -25,11 +27,11 @@ class YourNamespace\PluginName extends A Shopware plugin goes through several lifecycle stages: -- Install -- Activate -- Deactivate -- Update -- Uninstall +* Install +* Activate +* Deactivate +* Update +* Uninstall | Lifecycle | Description | | :--- | :--- | @@ -45,143 +47,146 @@ Each stage allows you to prepare, modify, or clean up your plugin’s integratio Lifecycle methods are implemented in your base plugin class (`<plugin root>/src/SwagBasicExample.php`), which acts like a bootstrap file, and provide access to the [service container](../services/dependency-injection.md) via `$this->container`. -## Prerequisites - -This guide is built upon our [plugin base guide](../plugin-base-guide), which explains the basics of a plugin as a whole. Make sure to have a look at it to get started on building your first plugin. - -## Lifecycle methods - -Each of the followings methods are going to be part of the plugin bootstrap, in this example the file will be `<plugin root>/src/SwagBasicExample.php`, which is the bootstrap file of the previously mentioned plugin base guide. - -Throughout all of the lifecycle methods, you have access to the [service container](../services/dependency-injection.md) via `$this->container`. +## Install -### Install +`install()` is executed when a plugin is installed. Use this method to: -The install method of a plugin is executed when the plugin is installed. You can use this method to install all the necessary requirements for your plugin, e.g. a new payment method. +* Register entities (e.g., payment methods) +* Create initial data +* Prepare system requirements ```php // <plugin root>/src/SwagBasicExample public function install(InstallContext $installContext): void { - // Do stuff such as creating a new payment method + // Try creating a new payment method, for example } ``` -In your install method, you have access to the `InstallContext`, which provides information such as: +The `InstallContext` provides: -- The current plugin version -- The current Shopware version -- The `Context`, which provides a lot more of system information, e.g. the currently used language -- A collection of the [plugin migrations](../database/database-migrations.md) -- If the migrations should be executed \(`isAutoMigrate` or `setAutoMigrate` to prevent the execution\) +* Current plugin version +* Current Shopware version +* System `Context`, which provides information about the system (e.g., current language, currency, and permissions) +* [Plugin migrations](../database/database-migrations.md) +* Auto-migration control \(`isAutoMigrate` or `setAutoMigrate` to prevent execution\) ::: info -You maybe don't want to create new data necessary for your plugin in the `install` method, even though it seems to be the perfect place. That's because an installed plugin is not automatically active yet - hence some data changes would have an impact on the system before the plugin is even active and therefore functioning. A good rule of thumb is: Only install new data or entities, that can be activated or deactivated themselves, such as a payment method. This way you can create a new payment method in the `install` method, but keep it inactive for now. +Avoid creating new business data for your plugin in the `install()` method. Creating fully active entities at this stage, when the plugin isn't active yet, may affect the system before the plugin is actually enabled. A good rule of thumb: Only create data that can be safely activated or deactivated independently—for example, a payment method. You can create the entity during `install()`, but keep it inactive until the `activate()` method runs. ::: -### Uninstall +## Activate -The opposite of the `install` method. It gets executed once the plugin is uninstalled. You might want to remove the data, that your plugin created upon installation. +`activate()` is executed once the plugin is activated. You most likely want to do one of the following next: + +* Activate entities that you created in the install method, e.g. such as a payment method +* Create new entities or data that you couldn't create with `install()` -::: warning -You can't simply remove everything that your plugin created previously. Think about a new payment method, that your plugin created and which was then used for actual orders. If you were to remove this payment method when uninstalling the plugin, all the orders that used this payment method would be broken, since the system wouldn't find the used payment method anymore. In this case, you most likely just want to deactivate the respective entity, if possible. Be careful here! -::: ```php // <plugin root>/src/SwagBasicExample -public function uninstall(UninstallContext $uninstallContext): void +public function activate(ActivateContext $activateContext): void { - // Remove or deactivate the data created by the plugin + // Activate entities, such as a new payment method + // Or create new entities, because now your plugin is installed and active } ``` -The `uninstall` method comes with the `UninstallContext`, which offers the same information as the `install` method. There's one more very important information available with the `UninstallContext`, which is the method `keepUserData`. +The `ActivateContext` provides the same information as the `InstallContext`. -#### Keeping user data upon uninstall +## Deactivate + +The opposite of `activate()` in most respects. It is executed when the plugin is deactivated. -When uninstalling a plugin, the user is asked if he really wants to delete all the plugin data. The method `keepUserData` of the `UninstallContext` will provide the users decision. If `keepUserData` returns `true`, you should **not** remove important data of your plugin, the user wants to keep them. +* Deactivate entities created by the `install` method +* Remove entities that cannot be safely deactivated and that would otherwise interfere with the system if left active while the plugin is inactive ```php // <plugin root>/src/SwagBasicExample -public function uninstall(UninstallContext $uninstallContext): void +public function deactivate(DeactivateContext $deactivateContext): void { - parent::uninstall($uninstallContext); - - if ($uninstallContext->keepUserData()) { - return; - } - - // Remove or deactivate the data created by the plugin + // Deactivate entities, such as a new payment method + // Or remove previously created entities } ``` -::: info -Refer to this video on **[Uninstalling a plugin](https://www.youtube.com/watch?v=v9OXrUJzC1I)** dealing with plugin uninstall routines. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma). -::: +The `DeactivateContext` provides the same information as the `InstallContext`. -### Activate +## Update -The `activate` method is executed once the plugin gets actually activated. You most likely want to do one of the following things here: +The `update()` method runs when your plugin is updated to a new version. Database changes should be handled via [plugin migrations](../database/database-migrations.md), rather than inside `update()`, to avoid repeated execution or version checks. -- Activate entities that you created in the install method, e.g. such as a payment method -- Create new entities or data, that you couldn't create in the install method +`update()` is still useful for non-database adjustments, feature toggles, configuration changes, or logic that depends on the previous and new plugin versions. ```php // <plugin root>/src/SwagBasicExample -public function activate(ActivateContext $activateContext): void +public function update(UpdateContext $updateContext$context): void { - // Activate entities, such as a new payment method - // Or create new entities here, because now your plugin is installed and active for sure + // Update as necessary, rarely database-related } ``` -The `ActivateContext` provides the same information as the `InstallContext`. +The `UpdateContext` provides the same information as the `InstallContext`, but comes with one additional method. Use `getUpdatePluginVersion()` to retrieve the target version being installed, and `getCurrentPluginVersion()` to retrieve the version currently installed before the update. -### Deactivate +::: warning +Run [CI](../../../development/testing/ci.md) (static analysis, tests, and reproducible artifact) before plugin updates to reduce the risk of upgrade-time failures. +::: -The opposite of the `activate` method. It is triggered once the plugin deactivates the plugin. This method should mostly do the opposite of the plugin's `activate` method: +## PostInstall and PostUpdate methods -- Deactivate entities created by the `install` method -- Maybe remove entities, that cannot be deactivated but would harm the system, if they remained in the system while the plugin is inactive +`PostUpdate` and `PostInstall` are executed **after** a successful install or update. These are useful for actions that should only run once the installation or update process has fully completed. ```php // <plugin root>/src/SwagBasicExample -public function deactivate(DeactivateContext $deactivateContext): void +public function postInstall(InstallContext $installContext): void { - // Deactivate entities, such as a new payment method - // Or remove previously created entities } -``` -The `DeactivateContext` provides the same information as the `InstallContext`. +public function postUpdate(UpdateContext $updateContext): void +{ +} +``` -### Update +### Uninstall -The `update` method is executed once your plugin gets updated to a new version. You do not need to update database entries here, since this should be done via [plugin migrations](../database/database-migrations.md). Otherwise you'd have to check if this specific update to an entity was already done in a previous `update` method execution, mostly by using plugin version conditions. +The opposite of `install()`, this is executed when the plugin is uninstalled. Use it to remove or clean up data created by your plugin. -However, of course you can still do that if necessary. Also, non-database updates can be done here. +::: warning +Do not blindly delete entities your plugin created. For example, if your plugin registered a payment method that was used in real orders, removing it would leave those orders in a broken state. In such cases, it's better to deactivate the entity instead of deleting it. Always consider the impact on existing production data. +::: ```php // <plugin root>/src/SwagBasicExample -public function update(UpdateContext $updateContext$context): void +public function uninstall(UninstallContext $uninstallContext): void { - // Update necessary stuff, mostly non-database related + // Remove or deactivate the data created by the plugin } ``` -The `UpdateContext` provides the same information as the `InstallContext`, but comes with one more method. In order to get the new plugin version, you can use the method `getUpdatePluginVersion` in contrast to the `getCurrentPluginVersion`, which will return the currently installed plugin version. +The `uninstall()` method receives an `UninstallContext`, which provides the same information as the `install` method. Important information is available with the `UninstallContext`, plus the`keepUserData()` flag. -### PostInstall and PostUpdate methods +#### Keeping user data upon uninstall -There are two more lifecycle methods, that are worth mentioning: `PostUpdate` and `PostInstall`, which are executed **after** the respective process of installing or updating your plugin is fully and successfully done. +When uninstalling a plugin, you can choose whether to remove all associated plugin data or not. If `keepUserData()` returns `true`, you must not delete persistent data created by your plugin. Respect this flag to avoid unintended data loss. ```php // <plugin root>/src/SwagBasicExample -public function postInstall(InstallContext $installContext): void +public function uninstall(UninstallContext $uninstallContext): void { -} + parent::uninstall($uninstallContext); -public function postUpdate(UpdateContext $updateContext): void -{ + if ($uninstallContext->keepUserData()) { + return; + } + + // Remove or deactivate the data created by the plugin } ``` + +::: info +Refer to this video on **[Uninstalling a plugin](https://www.youtube.com/watch?v=v9OXrUJzC1I)** when dealing with plugin uninstall routines. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma). +::: + +## Next steps + +Now let's [add plugin configuration](../plugin-fundamentals/add-plugin-configuration.md). diff --git a/guides/plugins/plugins/plugin-fundamentals/use-plugin-configuration.md b/guides/plugins/plugins/plugin-fundamentals/use-plugin-configuration.md index 118f69e6e2..c931476c6c 100644 --- a/guides/plugins/plugins/plugin-fundamentals/use-plugin-configuration.md +++ b/guides/plugins/plugins/plugin-fundamentals/use-plugin-configuration.md @@ -1,7 +1,7 @@ --- nav: title: Use Plugin Configuration - position: 20 + position: 30 --- diff --git a/guides/plugins/plugins/services/add-custom-service.md b/guides/plugins/plugins/services/add-custom-service.md index dc932b72e6..b0c6e79d0f 100644 --- a/guides/plugins/plugins/services/add-custom-service.md +++ b/guides/plugins/plugins/services/add-custom-service.md @@ -7,6 +7,8 @@ nav: # Add Custom Service +## Overview + In this guide you'll learn how to create a custom service using the Symfony [DI Container](https://symfony.com/doc/current/service_container.html). ## Prerequisites diff --git a/guides/plugins/plugins/services/adjusting-service.md b/guides/plugins/plugins/services/adjusting-service.md index abd6402944..62cf9e43be 100644 --- a/guides/plugins/plugins/services/adjusting-service.md +++ b/guides/plugins/plugins/services/adjusting-service.md @@ -1,6 +1,6 @@ --- nav: - title: Adjusting a service + title: Adjusting a Service position: 70 --- diff --git a/guides/plugins/plugins/services/dependency-injection.md b/guides/plugins/plugins/services/dependency-injection.md index c9f1ea4559..8a9c73ba4b 100644 --- a/guides/plugins/plugins/services/dependency-injection.md +++ b/guides/plugins/plugins/services/dependency-injection.md @@ -1,6 +1,6 @@ --- nav: - title: Dependency injection + title: Dependency Injection position: 40 --- diff --git a/guides/plugins/plugins/storefront/advanced/index.md b/guides/plugins/plugins/storefront/advanced/index.md index b6fd475ba3..2bacd1c08b 100644 --- a/guides/plugins/plugins/storefront/advanced/index.md +++ b/guides/plugins/plugins/storefront/advanced/index.md @@ -1,6 +1,6 @@ --- nav: - title: Advanced + title: Advanced Storefront Customization position: 100 --- @@ -13,4 +13,4 @@ These guides focus on performance optimization, caching behavior, cookie consent * [Add caching to custom controller](./add-caching-to-custom-controller.md) * [Add cookie to manager](./add-cookie-to-manager.md) * [Reacting to cookie consent changes](./reacting-to-cookie-consent-changes.md) -* [Remove Javascript plugin](./remove-unnecessary-js-plugin.md) +* [Remove JavaScript plugin](./remove-unnecessary-js-plugin.md) diff --git a/guides/plugins/plugins/storefront/controllers/add-custom-controller.md b/guides/plugins/plugins/storefront/controllers/add-custom-controller.md index 882e36fbf4..c154d2d8fe 100644 --- a/guides/plugins/plugins/storefront/controllers/add-custom-controller.md +++ b/guides/plugins/plugins/storefront/controllers/add-custom-controller.md @@ -7,6 +7,8 @@ nav: # Add Custom Controller +## Overview + In this guide you will learn how to create a custom Storefront controller. ## Prerequisites diff --git a/guides/plugins/plugins/storefront/controllers/add-custom-page.md b/guides/plugins/plugins/storefront/controllers/add-custom-page.md index 950dae3e54..3d4c4f61e4 100644 --- a/guides/plugins/plugins/storefront/controllers/add-custom-page.md +++ b/guides/plugins/plugins/storefront/controllers/add-custom-page.md @@ -7,6 +7,8 @@ nav: # Add Custom Page +## Overview + In this guide, you will learn how to create a custom page for your Storefront. A page in general consists of a controller, a page loader, a "page loaded" event and a page class, which is like a struct and contains the most necessary data for the page. diff --git a/guides/plugins/plugins/storefront/controllers/add-custom-pagelet.md b/guides/plugins/plugins/storefront/controllers/add-custom-pagelet.md index 3dbf44ea57..f616158d91 100644 --- a/guides/plugins/plugins/storefront/controllers/add-custom-pagelet.md +++ b/guides/plugins/plugins/storefront/controllers/add-custom-pagelet.md @@ -7,6 +7,8 @@ nav: # Add Custom Pagelet +## Overview + In this guide, you will learn how to create custom pagelets for your Storefront pages. In short: Pages are exactly that, a fully functioning page of your store with a template loaded by a route. A pagelet is an important and reusable fraction of several pages, such as a footer or the navigation. diff --git a/guides/plugins/plugins/storefront/controllers/add-data-to-storefront-page.md b/guides/plugins/plugins/storefront/controllers/add-data-to-storefront-page.md index 4f7bb8cd50..c9db46ce88 100644 --- a/guides/plugins/plugins/storefront/controllers/add-data-to-storefront-page.md +++ b/guides/plugins/plugins/storefront/controllers/add-data-to-storefront-page.md @@ -7,6 +7,8 @@ nav: # Add Data to Storefront Page +## Overview + Pages or pagelets are the objects that get handed to the templates and provide all necessary information for the template to render. If you make template changes you probably want to display some data that is currently not available in the page. diff --git a/guides/plugins/plugins/storefront/controllers/add-dynamic-content-via-ajax-calls.md b/guides/plugins/plugins/storefront/controllers/add-dynamic-content-via-ajax-calls.md index 656e95114c..16e19869ea 100644 --- a/guides/plugins/plugins/storefront/controllers/add-dynamic-content-via-ajax-calls.md +++ b/guides/plugins/plugins/storefront/controllers/add-dynamic-content-via-ajax-calls.md @@ -7,6 +7,8 @@ nav: # Add Dynamic Content via AJAX Calls +## Overview + This guide will show you how to add dynamic content to your Storefront. It combines and builds upon the guides about [adding custom JavaScript](../javascript/add-custom-javascript.md) and [adding a custom controller](../controllers/add-custom-controller.md), so you should probably read them first. diff --git a/guides/plugins/plugins/storefront/controllers/index.md b/guides/plugins/plugins/storefront/controllers/index.md index a9d47f42ba..9bdd7b359d 100644 --- a/guides/plugins/plugins/storefront/controllers/index.md +++ b/guides/plugins/plugins/storefront/controllers/index.md @@ -7,8 +7,7 @@ nav: # Storefront Controllers -Storefront controllers define HTTP endpoints for the storefront scope. -They coordinate page rendering and delegate business logic to Store API routes or page loaders. +Storefront controllers define HTTP endpoints for the storefront scope. They coordinate page rendering and delegate business logic to Store API routes or page loaders. ## Core Principles diff --git a/guides/plugins/plugins/storefront/howto/add-custom-captcha.md b/guides/plugins/plugins/storefront/howto/add-custom-captcha.md index 39e8a4fb1e..1b5f674394 100644 --- a/guides/plugins/plugins/storefront/howto/add-custom-captcha.md +++ b/guides/plugins/plugins/storefront/howto/add-custom-captcha.md @@ -7,6 +7,8 @@ nav: # Add Custom Captcha +## Overview + Add your custom captcha to the Shopware 6 core. This guide shows you how. ## Prerequisites diff --git a/guides/plugins/plugins/storefront/howto/add-custom-sorting-product-listing.md b/guides/plugins/plugins/storefront/howto/add-custom-sorting-product-listing.md index bf0bb835eb..919a2dc46f 100644 --- a/guides/plugins/plugins/storefront/howto/add-custom-sorting-product-listing.md +++ b/guides/plugins/plugins/storefront/howto/add-custom-sorting-product-listing.md @@ -7,6 +7,8 @@ nav: # Add Custom Sorting for Product Listing +## Overview + Individual sortings are groups of sorting options which you can use to sort product listings. The sortings are available in the Storefront. This guide will show you how to add individual sorting options using a migration \(manageable\) or at runtime \(non-manageable\). diff --git a/guides/plugins/plugins/storefront/howto/add-listing-filters.md b/guides/plugins/plugins/storefront/howto/add-listing-filters.md index bd63f20651..a6a1a629ca 100644 --- a/guides/plugins/plugins/storefront/howto/add-listing-filters.md +++ b/guides/plugins/plugins/storefront/howto/add-listing-filters.md @@ -7,6 +7,8 @@ nav: # Add Custom Listing Filters +## Overview + In an online shop, filters are an important feature. So you might use filters in your custom plugin. This guide will get you covered on how to implement your own, custom filters in Shopware's Storefront. ## Prerequisites @@ -156,7 +158,7 @@ As we want to filter a boolean value, we choose the `filter-boolean` component h | `filter-range` | Displays a range which can be used for filtering | | `filter-rating-select` and `filter-rating-select-item` | Filter component for rating | -Extending `component_filter_panel_items` as shown above puts our filter *after* the already existing ones. We could put it at the beginning by moving the `parent()` call to the end of the block. +Extending `component_filter_panel_items` as shown above puts our filter *after* the already existing ones. We could put it at the beginning by moving the `parent()` call to the end of the block. If we instead want our filter to be placed before or after a specific filter in the middle of the list, we can instead extend the block for that filter. For example, if we want our filter to be displayed after the price filter, we would extend the block `component_filter_panel_item_price`: diff --git a/guides/plugins/plugins/storefront/howto/use-media-thumbnails.md b/guides/plugins/plugins/storefront/howto/use-media-thumbnails.md index 0b76506649..5ec1ca24a0 100644 --- a/guides/plugins/plugins/storefront/howto/use-media-thumbnails.md +++ b/guides/plugins/plugins/storefront/howto/use-media-thumbnails.md @@ -7,6 +7,8 @@ nav: # Working with Media and Thumbnails +## Overview + In Shopware's Storefront, you can assign media objects to the different entities. To name an example, this is often used for products to show more information with images on the product detail page. This guide should give you a starting point on how to use media and thumbnails in your Storefront plugin. ## Prerequisites diff --git a/guides/plugins/plugins/storefront/howto/use-nested-line-items.md b/guides/plugins/plugins/storefront/howto/use-nested-line-items.md index 1b9df47fbb..d0a8f505cb 100644 --- a/guides/plugins/plugins/storefront/howto/use-nested-line-items.md +++ b/guides/plugins/plugins/storefront/howto/use-nested-line-items.md @@ -7,6 +7,8 @@ nav: # Use Nested Line Items +## Overview + This guide will show you how to use nested line items. It covers extending views and shows how the Custom Product plugin handles this. ## Prerequisites diff --git a/guides/plugins/plugins/storefront/howto/using-a-modal-window.md b/guides/plugins/plugins/storefront/howto/using-a-modal-window.md index b68ca553ac..859fe1bc8b 100644 --- a/guides/plugins/plugins/storefront/howto/using-a-modal-window.md +++ b/guides/plugins/plugins/storefront/howto/using-a-modal-window.md @@ -7,6 +7,8 @@ nav: # Using a Modal Window +## Overview + This guide explains how you can use a modal window in your plugin in different scenarios. ## Prerequisites diff --git a/guides/plugins/plugins/storefront/howto/using-custom-fields-storefront.md b/guides/plugins/plugins/storefront/howto/using-custom-fields-storefront.md index 632f5edd6f..45198e11f6 100644 --- a/guides/plugins/plugins/storefront/howto/using-custom-fields-storefront.md +++ b/guides/plugins/plugins/storefront/howto/using-custom-fields-storefront.md @@ -7,6 +7,8 @@ nav: # Add Custom Field in the Storefront +## Overview + This guide will show you how to use custom fields, e.g., labels in the Storefront. ## Prerequisites diff --git a/guides/plugins/plugins/storefront/howto/using-the-datepicker-plugin.md b/guides/plugins/plugins/storefront/howto/using-the-datepicker-plugin.md index 14e422e42a..d6fedee925 100644 --- a/guides/plugins/plugins/storefront/howto/using-the-datepicker-plugin.md +++ b/guides/plugins/plugins/storefront/howto/using-the-datepicker-plugin.md @@ -7,6 +7,8 @@ nav: # Using the Datepicker Plugin +## Overview + To provide an input field for date and time values, use the datepicker plugin. This guide shows you how to use it. The datepicker plugin uses the `flatpickr` implementation under the hood. So, check out the `flatpickr` documentation, diff --git a/guides/plugins/plugins/storefront/index.md b/guides/plugins/plugins/storefront/index.md index 2cc1c8d77d..4daef7317d 100644 --- a/guides/plugins/plugins/storefront/index.md +++ b/guides/plugins/plugins/storefront/index.md @@ -7,6 +7,94 @@ nav: # Storefront -Storefront handles the e-commerce platform's front end, including the online store's visual presentation and user interface. +The [Storefront](../../../../concepts/framework/architecture/storefront-concept.md) is the customer-facing layer of Shopware. When building a plugin, you extend the Storefront to: -You can customize and enhance the storefront by adding or modifying templates, layouts, styles, and components via plugins. It allows adding custom pages, layouts, dynamic content, filters, media, assets, and styles to create unique and engaging shopping experiences, ensuring a seamless and visually appealing interface for customers. It enables businesses to showcase their products, implement responsive designs, optimize performance, and deliver a personalized shopping journey to online visitors. +* Add new pages or endpoints +* Modify templates and layouts +* Inject dynamic data +* Add JavaScript behavior +* Customize styling and assets + +This section follows a practical development workflow and mirrors the folder structure inside `/storefront`. + +## How to use this section + +Most Storefront customizations follow this sequence: + +1. Add or extend a controller +2. Render or override a template +3. Inject data into the page +4. Enhance behavior with JavaScript +5. Apply styling and assets + +Start with the `/controllers` folder and move downward as needed. + +## Section structure + +## Advanced + +Infrastructure and optimization topics. + +* [Add caching to custom controller](../storefront/advanced/add-caching-to-custom-controller.md) +* [Add cookie to manager](../storefront/advanced/add-cookie-to-manager.md) +* [Reacting to cookie consent changes](../storefront/advanced/reacting-to-cookie-consent-changes.md) +* [Remove unnecessary JavaScript plugin](../storefront/advanced/remove-unnecessary-js-plugin.md) + +### Controllers + +Create new routes and pages, or extend existing ones. + +* [Add custom controller](../storefront/controllers/add-custom-controller.md) +* [Add custom page](../storefront/controllers/add-custom-page.md) +* [Add custom pagelet](../storefront/controllers/add-custom-pagelet.md) +* [Add data to a storefront page](../storefront/controllers/add-data-to-storefront-page.md) +* [Add Dynamic Content via AJAX Calls](../storefront/controllers/add-dynamic-content-via-ajax-calls.md) + +## How-to + +Feature-specific examples and focused use-cases. + +* [Add custom captcha](../storefront/howto/add-custom-captcha.md) +* [Add custom sorting for product listing](../storefront/howto/add-custom-sorting-product-listing.md) +* [Add listing filters](../storefront/howto/add-listing-filters.md) +* [Use media thumbnails](../storefront/howto/use-media-thumbnails.md) +* [Use nested line items](../storefront/howto/use-nested-line-items.md) +* [Using a modal window](../storefront/howto/using-a-modal-window.md) +* [Using custom fields in storefront](../storefront/howto/using-custom-fields-storefront.md) +* [Using the datepicker plugin](../storefront/howto/using-the-datepicker-plugin.md) + +### JavaScript + +Extend or override frontend behavior. + +* [Add custom JavaScript](../storefront/javascript/add-custom-javascript.md) +* [Add JavaScript as script tag](../storefront/javascript/add-javascript-as-script-tag.md) +* [Fetch data dynamically](../storefront/javascript/fetching-data-with-javascript.md) +* [Override existing JavaScript](../storefront/javascript/override-existing-javascript.md) +* [React to JavaScript events](../storefront/javascript/reacting-to-javascript-events.md) +* [Storefront Plugins and Helper Reference](../storefront/javascript/plugin-reference.md) + +### Styling and assets + +Control appearance and resources. + +* [Add custom assets](../storefront/styling/add-custom-assets.md) +* [Add custom styling](../storefront/styling/add-custom-styling.md) +* [Add icons](../storefront/styling/add-icons.md) +* [Add SCSS variables](../storefront/styling/add-scss-variables.md) +* [Add SCSS variables via subscriber](../storefront/styling/add-scss-variables-via-subscriber.md) +* [Add translations](../storefront/styling/add-translations.md) + +### Templates + +Override or extend Twig templates and layout blocks. + +* [Add Twig function](../storefront/templates/add-custom-twig-function.md) +* [Customize header & footer](../storefront/templates/customize-header-footer.md) +* [Customize templates](../storefront/templates/customize-templates.md) +* [Twig functions reference](../storefront/templates/twig-function-reference.md) + +## Next steps + +* After modifying Storefront code, [rebuild your assets](../../../development/tooling/using-watchers.md) +* [Visit the Composable Frontends guide](https://developer.shopware.com/frontends/) when building headless frontends instead of extending the default Storefront diff --git a/guides/plugins/plugins/storefront/javascript/add-custom-javascript.md b/guides/plugins/plugins/storefront/javascript/add-custom-javascript.md index f7e422923f..dd99922eeb 100644 --- a/guides/plugins/plugins/storefront/javascript/add-custom-javascript.md +++ b/guides/plugins/plugins/storefront/javascript/add-custom-javascript.md @@ -7,6 +7,8 @@ nav: # Add Custom JavaScript +## Overview + Adding interactivity to your Storefront sometimes might require writing your own JavaScript plugin. This guide covers writing and registering your own JavaScript plugins. You will write a plugin that checks whether the user has scrolled to the bottom of the page, then creates an alert. ## Prerequisites diff --git a/guides/plugins/plugins/storefront/javascript/add-javascript-as-script-tag.md b/guides/plugins/plugins/storefront/javascript/add-javascript-as-script-tag.md index e639b1d3e4..eeb14b347e 100644 --- a/guides/plugins/plugins/storefront/javascript/add-javascript-as-script-tag.md +++ b/guides/plugins/plugins/storefront/javascript/add-javascript-as-script-tag.md @@ -1,12 +1,14 @@ --- nav: - title: Add JavaScript as Script tag + title: Add JavaScript as Script Tag position: 65 --- # Add JavaScript as Script Tag +## Overview + You often want to add your JavaScript to your main entry point `<plugin root>/src/Resources/app/storefront/src/main.js` to automatically compile it alongside the Storefront JavaScript. Refer to the [Add custom JavaScript](./add-custom-javascript.md) guide for more information. diff --git a/guides/plugins/plugins/storefront/javascript/fetching-data-with-javascript.md b/guides/plugins/plugins/storefront/javascript/fetching-data-with-javascript.md index 1ad84631aa..5ded4397c2 100644 --- a/guides/plugins/plugins/storefront/javascript/fetching-data-with-javascript.md +++ b/guides/plugins/plugins/storefront/javascript/fetching-data-with-javascript.md @@ -7,6 +7,8 @@ nav: # Fetching Data with JavaScript +## Overview + When developing a plugin, you might want to fetch necessary data from the API. This guide explains how. ## Prerequisites diff --git a/guides/plugins/plugins/storefront/javascript/index.md b/guides/plugins/plugins/storefront/javascript/index.md index 8a660a406d..fab26da223 100644 --- a/guides/plugins/plugins/storefront/javascript/index.md +++ b/guides/plugins/plugins/storefront/javascript/index.md @@ -8,12 +8,12 @@ nav: This section explains how to extend and customize the Storefront using JavaScript plugins. It covers creating custom plugins, overriding existing functionality, reacting to events, loading external scripts, and interacting with the Store API. -* [Add custom Javascript](./add-custom-javascript.md) -* [Add Javascript as script tag](./add-javascript-as-script-tag.md) -* [Fetching data with Javascript](./fetching-data-with-javascript.md) -* [Override existing Javascript](./override-existing-javascript.md) -* [Reacting to javascript events](./reacting-to-javascript-events.md) +* [Add Custom Javascript](./add-custom-javascript.md) +* [Add Javascript as Script Tag](./add-javascript-as-script-tag.md) +* [Fetching Data with Javascript](./fetching-data-with-javascript.md) +* [Override Existing JavaScript](./override-existing-javascript.md) +* [Reacting to JavaScript events](./reacting-to-javascript-events.md) ## Reference -* [Storefront plugins and helper](./plugin-reference.md) +* [Storefront Plugins and Helper](./plugin-reference.md) diff --git a/guides/plugins/plugins/storefront/javascript/override-existing-javascript.md b/guides/plugins/plugins/storefront/javascript/override-existing-javascript.md index 792487598a..12fc6ea0ef 100644 --- a/guides/plugins/plugins/storefront/javascript/override-existing-javascript.md +++ b/guides/plugins/plugins/storefront/javascript/override-existing-javascript.md @@ -7,6 +7,8 @@ nav: # Override Existing JavaScript +## Overview + Override core JavaScript plugin logic by overriding it with your own implementations. Extending the cookie permission plugin, showing the cookie notice on every page load, and asking the user if they want to hide cookie bar via a confirm dialogue are the key actions involved. ## Prerequisites diff --git a/guides/plugins/plugins/storefront/javascript/plugin-reference.md b/guides/plugins/plugins/storefront/javascript/plugin-reference.md index 3568a49f46..10626c6772 100644 --- a/guides/plugins/plugins/storefront/javascript/plugin-reference.md +++ b/guides/plugins/plugins/storefront/javascript/plugin-reference.md @@ -1,11 +1,13 @@ --- nav: - title: Storefront Plugins + title: Storefront Plugins and Helper Reference position: 20 --- -# Storefront Plugins and Helper +# Storefront Plugins and Helper Reference + +## Overview This is a list of available JavaScript plugins and helpers that can be used and extended. diff --git a/guides/plugins/plugins/storefront/styling/add-custom-assets.md b/guides/plugins/plugins/storefront/styling/add-custom-assets.md index 8518d3eaf0..8b2f9ee446 100644 --- a/guides/plugins/plugins/storefront/styling/add-custom-assets.md +++ b/guides/plugins/plugins/storefront/styling/add-custom-assets.md @@ -7,6 +7,8 @@ nav: # Add Custom Assets +## Overview + When working with an own plugin, the usage of own custom images or other assets is a natural requirement. So of course you can do that in Shopware. In this guide we will discover together how it's possible to add and use custom assets in your Shopware plugin. ## Prerequisites @@ -80,7 +82,7 @@ You see, we can use our custom assets by using the asset path provided by the `b Of course, you're able to use custom assets in themes as well. In this context there's another way on integration custom assets into your theme. Please take a look on the guide about adding assets to a theme for further detail: -<PageRef page="../../../themes/add-assets-to-theme" /> +<PageRef page="../../../themes/assets/add-assets-to-theme.md" /> ## Next steps diff --git a/guides/plugins/plugins/storefront/styling/add-custom-styling.md b/guides/plugins/plugins/storefront/styling/add-custom-styling.md index f4e14368c6..18a01672ef 100644 --- a/guides/plugins/plugins/storefront/styling/add-custom-styling.md +++ b/guides/plugins/plugins/storefront/styling/add-custom-styling.md @@ -7,6 +7,8 @@ nav: # Add Custom Styling +## Overview + Quite often your plugin will have to change a few templates for the Storefront. Those might require custom styling to look neat, which will be explained in this guide. ## Prerequisites @@ -56,7 +58,7 @@ body { This comes with the advantage that when you want to change this color for all occurrences, you only have to change this variable once and the hard coded values are not cluttered all over the codebase. ::: info -Refer to the theme guide **[Override Bootstrap Variables in a Theme](../../../themes/override-bootstrap-variables-in-a-theme.md)** if you want to override some of the default Shopware variables. +Refer to the theme guide **[Override Bootstrap Variables in a Theme](../../../themes/styling/override-bootstrap-variables-in-a-theme.md)** if you want to override some of the default Shopware variables. ::: ### Testing its functionality diff --git a/guides/plugins/plugins/storefront/styling/add-icons.md b/guides/plugins/plugins/storefront/styling/add-icons.md index 51ce525c59..b21bf82a18 100644 --- a/guides/plugins/plugins/storefront/styling/add-icons.md +++ b/guides/plugins/plugins/storefront/styling/add-icons.md @@ -7,10 +7,12 @@ nav: # Add Custom Icons +## Overview + In this guide you will learn how to use the icon renderer component as well as adding custom icons. ::: info -Even if this is originally a plugin guide, everything will work perfectly in a theme as well. Actually, a theme even is a kind of plugin. So don't get confused by us talking about plugins here. +This guide also applies to [themes](../../../themes/index.md). ::: ## Prerequisites @@ -25,7 +27,6 @@ Needless to say, the first step is saving your image somewhere in your plugin wh ```text <YourPlugin>/src/Resources/app/storefront/dist/assets/icon/default -` ``` You can also provide "solid" icons or any other custom pack names which can be configured later with the `pack` parameter. You can do that by creating a folder with the pack name: diff --git a/guides/plugins/plugins/storefront/styling/add-scss-variables-via-subscriber.md b/guides/plugins/plugins/storefront/styling/add-scss-variables-via-subscriber.md index 255a7e61fb..f0dbbfcd44 100644 --- a/guides/plugins/plugins/storefront/styling/add-scss-variables-via-subscriber.md +++ b/guides/plugins/plugins/storefront/styling/add-scss-variables-via-subscriber.md @@ -7,6 +7,8 @@ nav: # Add SCSS Variables via Subscriber +## Overview + In order to add SCSS variables to your plugin, you can configure fields in your `config.xml` to be exposed as scss variables. We recommend to use the declaration of [SCSS variables](add-scss-variables.md) via the `config.xml` but you can still use a subscriber if you need to be more flexible as described below. diff --git a/guides/plugins/plugins/storefront/styling/add-scss-variables.md b/guides/plugins/plugins/storefront/styling/add-scss-variables.md index 757628cd72..ccd5022c14 100644 --- a/guides/plugins/plugins/storefront/styling/add-scss-variables.md +++ b/guides/plugins/plugins/storefront/styling/add-scss-variables.md @@ -11,6 +11,8 @@ nav: The configuration flag `css` is available from Shopware Version 6.4.13.0 ::: +## Overview + In order to add SCSS variables to your plugin, you can configure fields in your `config.xml` to be exposed as scss variables. We recommend using the declaration of SCSS variables via the `config.xml`. You can still use a subscriber if you need to be more flexible, as described [here](./add-scss-variables-via-subscriber.md). diff --git a/guides/plugins/plugins/storefront/styling/add-translations.md b/guides/plugins/plugins/storefront/styling/add-translations.md index cd4b2570de..d2c64a045e 100644 --- a/guides/plugins/plugins/storefront/styling/add-translations.md +++ b/guides/plugins/plugins/storefront/styling/add-translations.md @@ -7,6 +7,8 @@ nav: # Add Translations +## Overview + In this guide, you'll learn how to add translations to the Storefront and how to use them in your twig templates. To organize your snippets you can add them to `.json` files, so structuring and finding snippets you want to change is very easy. diff --git a/guides/plugins/plugins/storefront/templates/add-custom-twig-function.md b/guides/plugins/plugins/storefront/templates/add-custom-twig-function.md index 73134d8f51..6b0a0e0a0c 100644 --- a/guides/plugins/plugins/storefront/templates/add-custom-twig-function.md +++ b/guides/plugins/plugins/storefront/templates/add-custom-twig-function.md @@ -7,6 +7,8 @@ nav: # Add Custom Twig Functions +## Overview + Create your own Twig function to call a PHP script from the Twig template during theme development. Pass a string to the `TwigFunction` and return a `MD5-Hash`. ::: info diff --git a/guides/plugins/plugins/storefront/templates/customize-header-footer.md b/guides/plugins/plugins/storefront/templates/customize-header-footer.md index a61a32e931..b281725752 100644 --- a/guides/plugins/plugins/storefront/templates/customize-header-footer.md +++ b/guides/plugins/plugins/storefront/templates/customize-header-footer.md @@ -7,8 +7,11 @@ nav: # Customize Header/Footer +## Overview + With the introduction of ESI loading for the header and footer, the way how to customize the header and footer has changed. E.g. it is no longer possible to customize the header and footer depending on the current page data. + This guide will show you how to customize the header and footer in your plugin. ## Prerequisites diff --git a/guides/plugins/plugins/storefront/templates/customize-templates.md b/guides/plugins/plugins/storefront/templates/customize-templates.md index dd44a91d78..e70b27fd12 100644 --- a/guides/plugins/plugins/storefront/templates/customize-templates.md +++ b/guides/plugins/plugins/storefront/templates/customize-templates.md @@ -1,6 +1,6 @@ --- nav: - title: Customize templates + title: Customize Templates position: 10 --- @@ -13,8 +13,8 @@ This guide will cover customizing Storefront templates with a plugin. ## Prerequisites -As most guides, this guide is built upon the [Plugin base guide](../../plugin-base-guide.md), so you might want to have a look at it. -Other than that, knowing [Twig](https://twig.symfony.com/) is a big advantage for this guide, but that's not necessary. +- Familiarity with the [Plugin base guide](../../plugin-base-guide.md) and how to create plugins +- Knowledge of [Twig](https://twig.symfony.com/) is advantageous but not necessary ## Getting started diff --git a/guides/plugins/plugins/storefront/templates/index.md b/guides/plugins/plugins/storefront/templates/index.md index d2fc0864f8..96fcab9805 100644 --- a/guides/plugins/plugins/storefront/templates/index.md +++ b/guides/plugins/plugins/storefront/templates/index.md @@ -8,10 +8,10 @@ nav: This section explains how to customize and extend Storefront templates in plugins. -* [Customize templates](./customize-templates.md) +* [Customize Templates](./customize-templates.md) * [Customize Header/Footer](./customize-header-footer.md) -* [Add custom Twig functions](./add-custom-twig-function.md) +* [Add Custom Twig Functions](./add-custom-twig-function.md) ## Reference -* [Shopware's Twig functions](./twig-function-reference.md) +* [Shopware's Twig Runctions](./twig-function-reference.md) diff --git a/guides/plugins/plugins/storefront/templates/twig-function-reference.md b/guides/plugins/plugins/storefront/templates/twig-function-reference.md index f633d26168..957c0392ce 100644 --- a/guides/plugins/plugins/storefront/templates/twig-function-reference.md +++ b/guides/plugins/plugins/storefront/templates/twig-function-reference.md @@ -1,11 +1,11 @@ --- nav: - title: Twig Functions + title: Twig Functions Reference position: 10 --- -# Twig Functions +# Twig Functions Reference In Shopware, Twig functionality is extended with custom tags, functions, filters, and extensions. @@ -28,17 +28,17 @@ Templates which are imported via \{\% sw_use \%\} are not allowed to have additi | `sw_import` | Includes all macros from another file with support for multi inheritance. The API is the same like in Twig's default `import` | See [Twig 3 documentation for `import`](https://twig.symfony.com/doc/3.x/tags/import.html) | | `sw_from` | Includes single macros from another file with support for multi inheritance. The API is the same like in Twig's default `from` | See [Twig 3 documentation for `from`](https://twig.symfony.com/doc/3.x/tags/from.html) | | `sw_icon` | Displays an icon from a given icon set | See [Add custom icon](../../../../../guides/plugins/plugins/storefront/styling/add-icons.md#adding-icon) guide for details. | -| `sw_thumbnails` | Renders a tag with correctly configured “srcset” and “sizes” attributes based on the provided parameters | See [Add thumbnail](../../../../../guides/plugins/plugins/storefront/howto/use-media-thumbnails.md) guide for more information. | +| `sw_thumbnails` | Renders a tag with correctly configured “srcset” and “sizes” attributes based on the provided parameters | See [Add thumbnail](../../../../../guides/plugins/plugins/storefront/howto/use-media-thumbnails.md) guide for more information. | ## Functions | Function | Description | Notes | |:---------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------| | `config` | Gets a value from the system config (used by plugins and global settings) for the given sales channel | See [Reading the configuration values](../../../apps/lifecycle/configuration.md) | -| `theme_config` | Gets a value from the current theme | See [Theme configuration](../../../themes/theme-configuration.md) | -| `sw_block` | Renders a block of the same or another file with support for multi inheritance. The is the same like in Twig's default `block` | See [Twig 3 documentation for `block`](https://twig.symfony.com/doc/3.x/functions/block.html) | -| `sw_source` | Prints the content of a template file with support for multi inheritance. The is the same like in Twig's default `source` | See [Twig 3 documentation for `source`](https://twig.symfony.com/doc/3.x/functions/source.html) | -| `sw_include` | Renders the content of another template file with support for multi inheritance. The is the same like in Twig's default `include` and the new `sw_include` tag | See [Twig 3 documentation for `include`](https://twig.symfony.com/doc/3.x/functions/include.html) | +| `theme_config` | Gets a value from the current theme | See [Theme configuration](../../../themes/configuration/theme-configuration.md) | +| `sw_block` | Renders a block of the same or another file with support for multi inheritance. The is the same as in Twig's default `block` | See [Twig 3 documentation for `block`](https://twig.symfony.com/doc/3.x/functions/block.html) | +| `sw_source` | Prints the content of a template file with support for multi inheritance. The is the same as in Twig's default `source` | See [Twig 3 documentation for `source`](https://twig.symfony.com/doc/3.x/functions/source.html) | +| `sw_include` | Renders the content of another template file with support for multi inheritance. The is the same as in Twig's default `include` and the new `sw_include` tag | See [Twig 3 documentation for `include`](https://twig.symfony.com/doc/3.x/functions/include.html) | ## Filter diff --git a/guides/plugins/themes/add-assets-to-theme.md b/guides/plugins/themes/assets/add-assets-to-theme.md similarity index 86% rename from guides/plugins/themes/add-assets-to-theme.md rename to guides/plugins/themes/assets/add-assets-to-theme.md index 4da62935e9..40c9e3626d 100644 --- a/guides/plugins/themes/add-assets-to-theme.md +++ b/guides/plugins/themes/assets/add-assets-to-theme.md @@ -15,7 +15,7 @@ Your theme can include custom assets like images. This short guide will show you This guide is built upon the guide on creating a first theme: -<PageRef page="create-a-theme" /> +<PageRef page="../create-a-theme.md" /> ## Using custom assets @@ -23,7 +23,7 @@ There are basically two ways of adding custom assets to your theme. The first on ### Adding assets in theme.json file -While working with a theme you might have noted the [Theme configuration](theme-configuration), where you can configure paths to custom assets like images, fonts, etc. Configure your asset path accordingly: +While working with a theme you might have noted the [Theme configuration](../configuration/theme-configuration.md), where you can configure paths to custom assets like images, fonts, etc. Configure your asset path accordingly: ```javascript // <plugin root>/src/Resources/theme.json @@ -57,7 +57,7 @@ Next, run the command `bin/console theme:compile`. The assets from the path defi This way of adding custom assets refers to the default way of dealing with assets. For more details, please check out the article that specifically addresses this topic: -<PageRef page="../plugins/storefront/styling/add-custom-assets" /> +<PageRef page="../../plugins/storefront/styling/add-custom-assets.md" /> ## Linking to assets @@ -79,4 +79,4 @@ body { Now that you know how to use your assets in a theme, here is a list of other related topics where assets can be used. -* [Customize templates](../plugins/storefront/templates/customize-templates.md) +* [Customize templates](../../plugins/storefront/templates/customize-templates.md) diff --git a/guides/plugins/themes/add-icons.md b/guides/plugins/themes/assets/add-icons.md similarity index 90% rename from guides/plugins/themes/add-icons.md rename to guides/plugins/themes/assets/add-icons.md index 08fd11db68..9373fd8731 100644 --- a/guides/plugins/themes/add-icons.md +++ b/guides/plugins/themes/assets/add-icons.md @@ -17,7 +17,7 @@ Even if this is originally a plugin guide, everything will work perfectly in a t ## Prerequisites -To follow this guide easily, you first need to have a functioning plugin installed. Head over to our [Plugin base guide](../plugins/plugin-base-guide) to create a plugin, if you don't know how it's done yet. Also, knowing and understanding SCSS will be quite mandatory to fully understand what's going on here. Furthermore, it might be helpful to read the guide on how to [handle own assets](../plugins/storefront/styling/add-custom-assets.md) in your plugin before you start with this one. +To follow this guide easily, you first need to have a functioning plugin installed. Head over to our [Plugin base guide](../../plugins/plugin-base-guide.md) to create a plugin, if you don't know how it's done yet. Also, knowing and understanding SCSS will be quite mandatory to fully understand what's going on here. Furthermore, it might be helpful to read the guide on how to [handle own assets](../../plugins/storefront/styling/add-custom-assets.md) in your plugin before you start with this one. ## Adding icon @@ -27,7 +27,6 @@ Needless to say, the first step is saving your image somewhere in your plugin wh ```text <YourPlugin>/src/Resources/app/storefront/dist/assets/icon/default -` ``` You can also provide "solid" icons or any other custom pack names that can be configured later with the `pack` parameter. You can do that by creating a folder with the pack name: diff --git a/guides/plugins/themes/assets/index.md b/guides/plugins/themes/assets/index.md new file mode 100644 index 0000000000..82639e15da --- /dev/null +++ b/guides/plugins/themes/assets/index.md @@ -0,0 +1,14 @@ +--- +nav: + title: Assets + position: 30 +--- + +# Theme Assets + +This section explains how to work with assets in a Shopware theme. + +It covers adding custom assets such as images, fonts, and icon packs, and how to reference them in Twig and SCSS. + +* [Add assets to a Theme](./add-assets-to-theme.md) +* [Add custom icons](./add-icons.md) diff --git a/guides/plugins/themes/configuration/index.md b/guides/plugins/themes/configuration/index.md new file mode 100644 index 0000000000..6b2bd9a0b6 --- /dev/null +++ b/guides/plugins/themes/configuration/index.md @@ -0,0 +1,16 @@ +--- +nav: + title: Configuration + position: 40 +--- + +# Theme Configuration + +This section explains how to configure themes in Shopware. + +It covers the structure of `theme.json`, configurable theme fields in the Administration, and how to use configuration inheritance between themes. + +## Guides + +* [Theme configuration](./theme-configuration.md) +* [Theme inheritance configuration](./theme-inheritance-configuration.md) diff --git a/guides/plugins/themes/theme-configuration.md b/guides/plugins/themes/configuration/theme-configuration.md similarity index 97% rename from guides/plugins/themes/theme-configuration.md rename to guides/plugins/themes/configuration/theme-configuration.md index 58647a2373..ea7c417b90 100644 --- a/guides/plugins/themes/theme-configuration.md +++ b/guides/plugins/themes/configuration/theme-configuration.md @@ -19,7 +19,7 @@ This guide shows you how the theme configuration works and explains the possibil This guide is built upon the guide on creating a first theme: -<PageRef page="../themes/create-a-theme" /> +<PageRef page="../create-a-theme.md" /> ## Structure of theme configuration @@ -81,7 +81,7 @@ Let's have a closer look at each section. Here change the `name` of your theme and the `author`. It is recommended to choose a name in camel case. The `description` section is optional and as you notice it is also translatable. -The `views` section controls the template inheritance. This will be covered in the [Theme inheritance](add-theme-inheritance) guide. +The `views` section controls the template inheritance. This will be covered in the [Theme inheritance](../inheritance/add-theme-inheritance.md) guide. ```javascript // <plugin root>/src/Resources/theme.json @@ -107,7 +107,7 @@ The `previewMedia` field provides a path `app/storefront/dist/assets/defaultThem } ``` -The `style` section determines the order of the CSS compilation. In the `<plugin root>/src/Resources/app/storefront/src/scss/base.scss` file you can apply your changes you want to make to the `@Storefront` standard styles or add other styles you need. The `<plugin root>/src/Resources/app/storefront/src/scss/overrides.scss` file is used for a special case. Maybe you need to override some defined `variables` or `functions` defined by Shopware or Bootstrap, you can implement your changes here. Checkout the [Override bootstrap variables in a theme](override-bootstrap-variables-in-a-theme) guide for further information. +The `style` section determines the order of the CSS compilation. In the `<plugin root>/src/Resources/app/storefront/src/scss/base.scss` file you can apply your changes you want to make to the `@Storefront` standard styles or add other styles you need. The `<plugin root>/src/Resources/app/storefront/src/scss/overrides.scss` file is used for a special case. Maybe you need to override some defined `variables` or `functions` defined by Shopware or Bootstrap, you can implement your changes here. Checkout the [Override bootstrap variables in a theme](../styling/override-bootstrap-variables-in-a-theme.md) guide for further information. ```javascript // <plugin root>/src/Resources/theme.json @@ -124,7 +124,7 @@ The `style` section determines the order of the CSS compilation. In the `<plugin ## Assets -The `asset` option you can configure your paths to your assets like images, fonts, etc. The standard location to put your assets to is the `<plugin root>/app/storefront/src/assets` folder. Checkout the [Add assets to theme](add-assets-to-theme) guide for further information. +The `asset` option you can configure your paths to your assets like images, fonts, etc. The standard location to put your assets to is the `<plugin root>/app/storefront/src/assets` folder. Checkout the [Add assets to theme](../assets/add-assets-to-theme.md) guide for further information. ```javascript // <plugin root>/src/Resources/theme.json @@ -172,7 +172,7 @@ One of the benefits of creating a theme is that you can overwrite the theme conf } ``` -In the example above, we change the primary color to green. You always inherit from the storefront config and both configurations are merged. This also means that you only have to provide the values you actually want to change. You can find a more detailed explanation of the configuration inheritance in the section [Theme inheritance](add-theme-inheritance). +In the example above, we change the primary color to green. You always inherit from the storefront config and both configurations are merged. This also means that you only have to provide the values you actually want to change. You can find a more detailed explanation of the configuration inheritance in the section [Theme inheritance](../inheritance/add-theme-inheritance.md). ::: warning If you overwrite variables of another theme from a third party provider and these are renamed or removed at a later time, this can lead to issues and the theme can no longer be compiled. So be aware of it. @@ -956,7 +956,7 @@ The `configInheritance` option lets you configure additional themes from which y } ``` -In this example the `BasicTheme` is a theme that adds all the configurations you need for your corporate design. This configurations will be inherited in your new theme which can add or change some configurations only needed in a special sales channel or for a special time. See [Theme inheritance](./add-theme-inheritance) for a more detailed example. +In this example the `BasicTheme` is a theme that adds all the configurations you need for your corporate design. This configurations will be inherited in your new theme which can add or change some configurations only needed in a special sales channel or for a special time. See [Theme inheritance](../inheritance/add-theme-inheritance.md) for a more detailed example. All configuration fields and their values from the mentioned themes in `configInheritance` are available inside the current theme, unless they are explicitly overwritten. This way custom themes can be extended without copying their configuration inside the theme.json. The relationship of the inheritance is only created while installing the theme. For updating the relationship later on, the command `theme:refresh` can be used. @@ -964,5 +964,5 @@ All configuration fields and their values from the mentioned themes in `configIn Now that you know how to configure your theme, here is a list of things you can do. -- [Add SCSS Styling and JavaScript to a theme](add-css-js-to-theme) -- [Customize Templates](../plugins/storefront/templates/customize-templates.md) +- [Add SCSS Styling and JavaScript to a theme](../styling/add-css-js-to-theme.md) +- [Customize Templates](../../plugins/storefront/templates/customize-templates.md) diff --git a/guides/plugins/themes/theme-inheritance-configuration.md b/guides/plugins/themes/configuration/theme-inheritance-configuration.md similarity index 94% rename from guides/plugins/themes/theme-inheritance-configuration.md rename to guides/plugins/themes/configuration/theme-inheritance-configuration.md index 3e2077acac..84e93e82d9 100644 --- a/guides/plugins/themes/theme-inheritance-configuration.md +++ b/guides/plugins/themes/configuration/theme-inheritance-configuration.md @@ -21,7 +21,7 @@ Imagine you have a theme that is applying your corporate design to the storefron ### Create two themes -Create the two themes like described in [Theme inheritance](./add-theme-inheritance). +Create the two themes like described in [Theme inheritance](../inheritance/add-theme-inheritance.md). ### Configure your themes @@ -195,5 +195,5 @@ In this theme (`SwagBasicExampleThemeExtend`) all the configuration fields from Now that you know how the theme inheritance works you can start with own customizations. Here is a list of other related topics where assets can be used. -* [Add SCSS Styling and JavaScript to a theme](add-css-js-to-theme) -* [Customize templates](../plugins/storefront/templates/customize-templates.md) +* [Add SCSS Styling and JavaScript to a theme](../styling/add-css-js-to-theme.md) +* [Customize templates](../../plugins/storefront/templates/customize-templates.md) diff --git a/guides/plugins/themes/create-a-theme.md b/guides/plugins/themes/create-a-theme.md index 0be91731d6..58143045c3 100644 --- a/guides/plugins/themes/create-a-theme.md +++ b/guides/plugins/themes/create-a-theme.md @@ -1,55 +1,50 @@ --- nav: - title: Create a first theme + title: Create a Theme position: 20 --- -# Create a First Theme +# Create a Theme ## Overview -This guide will show you how to create a theme from scratch. You will also learn how to install and activate your theme. +This guide covers how to create, install, and activate a custom Shopware 6 theme. ## Prerequisites -All you need for this guide is a running Shopware 6 instance and full access to both the files, as well as the command line. +All you need: -## Create your first plugin theme +* A running Shopware 6 instance +* Full file system and CLI access -Let's get started with creating your plugin by finding a proper name for it. +## Name your plugin theme -### Name your plugin theme - -First, you need to find a name for your theme. We're talking about a technical name here, so it needs to describe your theme appearance as short as possible, written in UpperCamelCase. To prevent issues with duplicated theme names, you should add a shorthand prefix for your company. -Shopware uses "Swag" as a prefix for that case. -For this example guide we'll use the theme name **SwagBasicExampleTheme.** - -::: info -Notice: The name of a theme must begin with a capital letter too! -::: +Use **UpperCamelCase**, e.g., `SwagBasicExampleTheme`, beginning with a capital letter and ideally with a company prefix to avoid duplication. Choose a name that describes your theme appearance as succinctly and clearly as possible. ### Create a plugin-based theme -Now that you've found your name, it's time to actually create your plugin. - -Open your terminal and run the following command to create a new theme +Run the following command in your terminal: ```bash bin/console theme:create SwagBasicExampleTheme +``` -# you should get an output like this: +You should get an output like this: +```bash Creating theme structure under .../development/custom/plugins/SwagBasicExampleTheme ``` -After your theme was created successfully Shopware has to know that it now exists. You have to refresh the plugin list by running the following command. +Shopware needs to know that your new theme exists. Refresh the plugin list by running: ```bash bin/console plugin:refresh +``` -# you should get an output like this +You should get an output like this: +```bash [OK] Plugin list refreshed Shopware Plugin Service @@ -64,12 +59,17 @@ Shopware Plugin Service 1 plugins, 0 installed, 0 active , 0 upgradeable ``` -Now Shopware recognises your plugin theme. The next step is the installation and activation of your theme. Run the following command in terminal. +### Activating the theme + +The next command installs and activates the theme: ```bash -# run this command to install and activate your plugin bin/console plugin:install --activate SwagBasicExampleTheme +``` + +The output should look like this, indicating success: +```bash Shopware Plugin Lifecycle Service ================================= @@ -81,17 +81,18 @@ Shopware Plugin Lifecycle Service [OK] Installed 1 plugin(s). ``` -Your theme was successfully installed and activated. +### Assign to a sales channel -The last thing we need to do to work with the theme is to assign it to a sales channel. You can do that by running the `theme:change` command in the terminal and follow the instructions. +The final step in this guide involves assigning the theme to a sales channel and changing the default Storefront theme. Run this command: ```bash # run this to change the current Storefront theme $ bin/console theme:change +``` -# you will get an interactive prompt to change the -# current theme of the Storefront like this +You should see an interactive prompt like this: +```bash Please select a sales channel: [0] Storefront | 64bbbe810d824c339a6c191779b2c205 [1] Headless | 98432def39fc4624b33213a56b8c944d @@ -106,14 +107,13 @@ Set "SwagBasicExampleTheme" as new theme for sales channel "Storefront" Compiling theme 13e0a4a46af547479b1347617926995b for sales channel SwagBasicExampleTheme ``` -At first, we have to select a sales channel. The obvious choice here is the 'Storefront'. Afterwards enter the number for our theme. - -Now your theme is fully installed, and you can start your customization. +First, select `Storefront` as the sales channel. Then enter your theme's number. This fully installs your theme, and you can start your customization. ### Directory structure of a theme +The structure of a plugin-based theme: + ```bash -# structure of a plugin-based theme ├── composer.json └── src ├── Resources @@ -134,10 +134,37 @@ Now your theme is fully installed, and you can start your customization. └── SwagBasicExampleTheme.php ``` +## Troubleshooting + +When the theme is not visible, run the command: + +```bash +bin/console plugin:refresh +bin/console plugin:list +``` + +When the theme is not applied, run the command: + +```bash +bin/console theme:change +bin/console theme:compile +``` + +When there are errors no changes, run the command: + +```bash +bin/console cache:clear +``` + +Also helpful: + +* Check `var/log/` +* Verify file permissions in `custom/plugins/` + ## Next steps -Now that you have created your own theme, the next step is to learn how to make settings and adjustments. +Now that you have created a theme, learn how to configure settings and styling: -* [Theme configuration](theme-configuration) -* [Add SCSS Styling and JavaScript to a theme](add-css-js-to-theme) -* [Add assets to theme](add-assets-to-theme) +* [Theme configuration](../themes/configuration/theme-configuration.md) +* [Add SCSS Styling and JavaScript to a theme](../themes/styling/add-css-js-to-theme.md) +* [Add assets to theme](../themes/assets/add-assets-to-theme.md) diff --git a/guides/plugins/themes/differences-plugins-and-apps-vs-themes.md b/guides/plugins/themes/differences-plugins-and-apps-vs-themes.md deleted file mode 100644 index 03f0853ab6..0000000000 --- a/guides/plugins/themes/differences-plugins-and-apps-vs-themes.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -nav: - title: Differences Plugins and Apps vs Themes - position: 30 - ---- - -# Differences Plugins and Apps vs Themes - -A theme is a special type of Plugin or App, aimed at easily changing the visual appearance of the Storefront. If you want to get more information about plugins and apps you can check out the [Plugin Base Guide](../plugins/plugin-base-guide) and [App Base Guide](../apps/app-base-guide). - -There are basically several ways to change the appearance of the Storefront. You can have "regular" plugins or apps whose main purpose is to add new functions and change the behavior of the shop. These plugins / apps might also contain SCSS/CSS and JavaScript to be able to embed their new features into the Storefront. - -Technically, a theme is also a plugin / app, but it will be visible in the theme manger once it's activated and can be assigned to a specific sales channel, while plugins / apps are activated globally. To distinguish a theme from a "regular" plugin / app you need to implement the Interface `Shopware\Storefront\Framework\ThemeInterface`. A theme can inherit also from other themes, overwrite the default configuration \(colors, fonts, media\) and add new configuration options. - -You do not need to write any PHP code in a theme. If you need PHP code, you should choose a plugin instead. Another important distinction to themes is this: Themes are specific for a sales channel and have to be assigned to them to take effect, the other way around plugins and apps have a global effect on the Shopware installation. - -## Next steps - -Now that you have learned the differences between themes, plugins and apps, you can create your first theme. - -* [Create a first Shopware theme](create-a-theme) diff --git a/guides/plugins/themes/index.md b/guides/plugins/themes/index.md index 28c15966f0..938330367d 100644 --- a/guides/plugins/themes/index.md +++ b/guides/plugins/themes/index.md @@ -1,13 +1,17 @@ --- nav: - title: Themes + title: Storefront Themes position: 20 --- -# Themes +# Storefront Themes -A Shopware theme is an extension (plugin or app) that enables you to customize and modify the appearance and design of your online storefront. You can change the layout, styling, typography, colors, images, and other visual elements to match your brand identity and desired user experience. +Storefront Themes let you customize the visual appearance of the Shopware [Storefront](../../../concepts/framework/architecture/index.md). They are not a separate extension type, but are either implemented as plugins or, in Cloud environments, delivered via apps. + +Unlike regular plugins, themes do not contain backend logic. Their purpose is purely storefront presentation, and they are managed per sales channel through the Theme Manager. + +Shopware comes with a default theme built on top of Bootstrap 5. Everything you can do with Bootstrap, you can do with the Shopware Storefront. ```text Extensions @@ -17,17 +21,32 @@ Extensions └── can include a Theme (Cloud-ready) ``` -Tasks that themes enable include: +Themes support tasks such as: -* template overrides -* custom styles -* configuration interfaces -* control the order in which styles and templates are loaded +* overriding Twig templates +* adding custom SCSS/CSS styling — adjust layout, typography, colors, images, and other visual elements to match your brand identity and desired user experience +* defining configurable theme settings in the Administration +* controlling the inheritance order of styles and templates ::: info -Note that a plugin can also override templates. +A plugin can also override templates. ::: -To get started with your first theme, follow our [Theme Base Guide](theme-base-guide). +## Differences between themes vs. plugins and apps + +A theme is a specialized type of plugin or app that is focused on changing the visual appearance of the Storefront. For more information about plugins and apps, see the [Plugin Base Guide](../plugins/plugin-base-guide.md) and [App Base Guide](../apps/app-base-guide.md). + +There are several ways to change the appearance of the Storefront. Regular plugins or apps are mainly used to add functionality and change shop behavior. They can also include SCSS/CSS and JavaScript to integrate those features into the Storefront. + +A theme is technically also a plugin or app, but once activated, it appears in the Theme Manager and can be assigned to a specific sales channel. Plugins and apps, by contrast, are activated globally. + +To distinguish a theme from a regular plugin or app, it must implement the interface `Shopware\Storefront\Framework\ThemeInterface`. A theme can also [inherit](../themes/inheritance/index.md) from other themes, override default configuration values such as colors, fonts, and media, and introduce additional [configuration](../themes/configuration/index.md) options. + +You do not need to write any PHP code in a theme. If your extension requires PHP code, you should use a plugin instead. + +Another key difference is scope: themes only take effect for the sales channels they are assigned to, whereas plugins and apps affect the Shopware installation globally. + +## Getting started -For more on how themes relate to plugins and apps, see [Plugins and Apps vs Themes](./differences-plugins-and-apps-vs-themes.md). +* [Theme Base Guide](./theme-base-guide.md) +* [Create a first theme](./create-a-theme.md) diff --git a/guides/plugins/themes/add-theme-inheritance-without-resources.md b/guides/plugins/themes/inheritance/add-theme-inheritance-without-resources.md similarity index 85% rename from guides/plugins/themes/add-theme-inheritance-without-resources.md rename to guides/plugins/themes/inheritance/add-theme-inheritance-without-resources.md index 2d5108f72f..cbd4694ec7 100644 --- a/guides/plugins/themes/add-theme-inheritance-without-resources.md +++ b/guides/plugins/themes/inheritance/add-theme-inheritance-without-resources.md @@ -31,7 +31,7 @@ If you want to build your theme only upon the Bootstrap SCSS you can use the `@S * This option can only be used in the `style` section of the `theme.json`. You must not use it in `views` or `script`. * All theme variables like `$sw-color-brand-primary` are also available when using the Bootstrap option. -* You can only use either `@StorefrontBootstrap` or `@Storefront`. They should not be used at the same time. The `@Storefront` bundle **includes** the Bootstrap SCSS already. +* You can only use either `@StorefrontBootstrap` or `@Storefront`. They should not be used at the same time. The `@Storefront` bundle includes the Bootstrap SCSS already. * `@StorefrontBootstrap` does not include `@Plugins`, you have to add it yourself. ::: @@ -39,6 +39,6 @@ If you want to build your theme only upon the Bootstrap SCSS you can use the `@S Here is a list of related topics which might be interesting for you. -* [Theme configuration](theme-configuration) -* [Add SCSS Styling and JavaScript to a theme](add-css-js-to-theme) -* [Add assets to theme](add-assets-to-theme) +* [Theme configuration](../configuration/theme-configuration.md) +* [Add SCSS Styling and JavaScript to a theme](../styling/add-css-js-to-theme.md) +* [Add assets to theme](../assets/add-assets-to-theme.md) diff --git a/guides/plugins/themes/add-theme-inheritance.md b/guides/plugins/themes/inheritance/add-theme-inheritance.md similarity index 88% rename from guides/plugins/themes/add-theme-inheritance.md rename to guides/plugins/themes/inheritance/add-theme-inheritance.md index 5403a5bc3a..ec9ef93df7 100644 --- a/guides/plugins/themes/add-theme-inheritance.md +++ b/guides/plugins/themes/inheritance/add-theme-inheritance.md @@ -19,7 +19,7 @@ All you need for this guide is a running Shopware 6 instance and full access to ## Extending an existing theme with a new theme -The first step is to create a new theme which will extend the existing `SwagBasicExampleTheme`. Checkout the [Create a first theme](create-a-theme) guide if you don't know how to create a new theme. In this guide we call the extending theme `SwagBasicExampleThemeExtend`. After `SwagBasicExampleTheme` was installed, activated and assigned to a sales channel we need to set up the inheritance. +The first step is to create a new theme which will extend the existing `SwagBasicExampleTheme`. Checkout the [Create a first theme](../create-a-theme.md) guide if you don't know how to create a new theme. In this guide we call the extending theme `SwagBasicExampleThemeExtend`. After `SwagBasicExampleTheme` was installed, activated and assigned to a sales channel we need to set up the inheritance. ## Set up the inheritance @@ -104,7 +104,7 @@ The same applies to the JavaScript `script` section. The javascript of the Store ### `style` section -The `style` section behaves similarly to the others. The only difference here is the `override.css` can affect SCSS variables e.g. `$border-radius`. That's why it's at the top of the list. To find out more about overriding variables check out the [Override Bootstrap variables in a theme](override-bootstrap-variables-in-a-theme) guide. +The `style` section behaves similarly to the others. The only difference here is the `override.css` can affect SCSS variables e.g. `$border-radius`. That's why it's at the top of the list. To find out more about overriding variables check out the [Override Bootstrap variables in a theme](../styling/override-bootstrap-variables-in-a-theme.md) guide. ### `asset` section @@ -112,11 +112,11 @@ If you want to use assets from the `@SwagBasicExampleTheme` you have add it to t ### `configInheritance` section -Finally, the `configInheritance` section will use the field configuration from the given themes and defines the last of the themes, that is different from the current theme, as the parent theme. The configuration values are inherited from the themes mentioned in `configInheritance`. The Storefront theme configuration will always be inherited, even if no `configInheritance` is given. See [Theme inheritance configuration](theme-inheritance-configuration) for a more detailed example. +Finally, the `configInheritance` section will use the field configuration from the given themes and defines the last of the themes, that is different from the current theme, as the parent theme. The configuration values are inherited from the themes mentioned in `configInheritance`. The Storefront theme configuration will always be inherited, even if no `configInheritance` is given. See [Theme inheritance configuration](../configuration/theme-inheritance-configuration.md) for a more detailed example. ## Next steps Now that you know how the theme inheritance works you can start with own customizations. Here is a list of other related topics where assets can be used. -* [Add SCSS Styling and JavaScript to a theme](add-css-js-to-theme) -* [Customize templates](../plugins/storefront/templates/customize-templates.md) +* [Add SCSS Styling and JavaScript to a theme](../styling/add-css-js-to-theme.md) +* [Customize templates](../../plugins/storefront/templates/customize-templates.md) diff --git a/guides/plugins/themes/inheritance/index.md b/guides/plugins/themes/inheritance/index.md new file mode 100644 index 0000000000..acf3d99c4b --- /dev/null +++ b/guides/plugins/themes/inheritance/index.md @@ -0,0 +1,12 @@ +--- +nav: + title: Inheritance + position: 50 +--- + +# Theme Inheritance + +This section explains how to extend and compose themes using Shopware’s inheritance system. Guides cover: + +* [Theme inheritance](./add-theme-inheritance.md) +* [Add theme inheritance without resources](./add-theme-inheritance-without-resources.md) diff --git a/guides/plugins/themes/add-css-js-to-theme.md b/guides/plugins/themes/styling/add-css-js-to-theme.md similarity index 95% rename from guides/plugins/themes/add-css-js-to-theme.md rename to guides/plugins/themes/styling/add-css-js-to-theme.md index a4f67d4806..744b80de82 100644 --- a/guides/plugins/themes/add-css-js-to-theme.md +++ b/guides/plugins/themes/styling/add-css-js-to-theme.md @@ -13,7 +13,7 @@ This guide explains how you can add your custom styling via SCSS and add your cu ## Prerequisites -All you need for this guide is a running Shopware 6 instance and full access to both the files, as well as the command line. You also need to have an installed and activated theme which is assigned to a sales channel. Checkout the [Create a first theme](create-a-theme) guide if you have not yet a working theme setup. +All you need for this guide is a running Shopware 6 instance and full access to both the files, as well as the command line. You also need to have an installed and activated theme which is assigned to a sales channel. Checkout the [Create a first theme](../create-a-theme.md) guide if you have not yet a working theme setup. ## Adding custom SCSS @@ -124,4 +124,4 @@ This command starts a NodeJS web server on port `9998`. If you open the Storefro Now that you know how to customize the styling via SCSS and add JavaScript, here is a list of things you can do. * [Override Bootstrap variables in a theme](override-bootstrap-variables-in-a-theme) -* [Customize templates](../plugins/storefront/templates/customize-templates.md) +* [Customize templates](../../plugins/storefront/templates/customize-templates.md) diff --git a/guides/plugins/themes/styling/index.md b/guides/plugins/themes/styling/index.md new file mode 100644 index 0000000000..4f7ef2f29b --- /dev/null +++ b/guides/plugins/themes/styling/index.md @@ -0,0 +1,13 @@ +--- +nav: + title: Styling + position: 45 +--- + +# Theme Styling + +This section explains how to customize the visual styling of a Shopware theme. Included guides: + +* [Add SCSS Styling and JavaScript to a Theme](./add-css-js-to-theme.md) +* [Override Bootstrap variables in a Theme](./override-bootstrap-variables-in-a-theme.md) +* [Override responsive breakpoints in a Theme](./override-theme-breakpoints.md) diff --git a/guides/plugins/themes/override-bootstrap-variables-in-a-theme.md b/guides/plugins/themes/styling/override-bootstrap-variables-in-a-theme.md similarity index 90% rename from guides/plugins/themes/override-bootstrap-variables-in-a-theme.md rename to guides/plugins/themes/styling/override-bootstrap-variables-in-a-theme.md index 1c7c2ab42e..b131dfade0 100644 --- a/guides/plugins/themes/override-bootstrap-variables-in-a-theme.md +++ b/guides/plugins/themes/styling/override-bootstrap-variables-in-a-theme.md @@ -17,7 +17,7 @@ Sometimes it is necessary to adjust SCSS variables if you want to change the loo ## Prerequisites -All you need for this guide is a running Shopware 6 instance and full access to both the files, as well as the command line. You also need to have an installed and activated theme which is assigned to a sales channel. Checkout the [Create a first theme](create-a-theme) guide if you have not yet a working theme setup. +All you need for this guide is a running Shopware 6 instance and full access to both the files, as well as the command line. You also need to have an installed and activated theme which is assigned to a sales channel. Checkout the [Create a first theme](../create-a-theme.md) guide if you have not yet a working theme setup. ## Override default SCSS variables @@ -91,6 +91,6 @@ When running `composer run watch:storefront` in platform only setups or `./bin/w Now that you know how to override Bootstrap variables, here is a list of related topics which might be interesting for you. -* [Theme configuration](theme-configuration) -* [Add SCSS Styling and JavaScript to a theme](add-css-js-to-theme) -* [Add assets to a theme](add-assets-to-theme) +* [Theme configuration](../configuration/theme-configuration.md) +* [Add SCSS Styling and JavaScript to a theme](../styling/add-css-js-to-theme.md) +* [Add assets to a theme](../assets/add-assets-to-theme.md) diff --git a/guides/plugins/themes/override-theme-breakpoints.md b/guides/plugins/themes/styling/override-theme-breakpoints.md similarity index 100% rename from guides/plugins/themes/override-theme-breakpoints.md rename to guides/plugins/themes/styling/override-theme-breakpoints.md diff --git a/guides/plugins/themes/theme-base-guide.md b/guides/plugins/themes/theme-base-guide.md index f694213dd4..0f28ea922a 100644 --- a/guides/plugins/themes/theme-base-guide.md +++ b/guides/plugins/themes/theme-base-guide.md @@ -7,10 +7,18 @@ nav: # Theme Base Guide -A theme gives you the ability to extend/change the visual appearance of the Storefront via styling the SCSS/CSS and adjusting twig templates. You can also provide JavaScript with your theme to change how the Storefront behaves in the browser. For example, JavaScript is used in Shopware to open the offcanvas shopping-cart. Now, as you might know, Shopware comes with a default theme, to make things a bit easier. The default theme in Shopware is built on top of Bootstrap 5, style-wise. So everything you can do with Bootstrap, you can do with the Shopware Storefront as well. +## Developer workflow -Another handy capability is the theme configuration: As a theme developer you can define variables which can be configured by the shop owner in the Administration. Those variables are accessible in your theme and let you implement powerful features. +If you are building a theme, follow this path: + +1. [Create a theme](create-a-theme.md) +2. Configure it via [`theme.json`](../themes/configuration/theme-configuration.md) +3. [Add SCSS styling and JavaScript](styling/add-css-js-to-theme.md) +4. [Add assets](../themes/assets/add-assets-to-theme.md) and [icons](../themes/assets/add-icons.md) +5. Override [Bootstrap variables](../themes/styling/override-bootstrap-variables-in-a-theme.md) or [responsive breakpoints](../themes/styling/override-theme-breakpoints.md) +6. [Customize Storefront templates](../plugins/storefront/templates/customize-templates.md) +7. Use [theme inheritance](inheritance/add-theme-inheritance.md) if needed ## Next steps -Now that you know what you can do with themes, the next steps would be to [create themes](create-a-theme). +Now that you know what you can do with themes, the next steps would be to [create themes](create-a-theme.md). diff --git a/guides/upgrades-migrations/extension-translation.md b/guides/upgrades-migrations/extension-translation.md index da543719f1..7332633988 100644 --- a/guides/upgrades-migrations/extension-translation.md +++ b/guides/upgrades-migrations/extension-translation.md @@ -35,7 +35,7 @@ When a translation key is requested, Shopware will: ### Automatic Shipping with Shopware **6.7.3**, there's the command line tool `bin/console translation:lint-filenames` that can be used to -check the translation files, or use the `--fix` parameter to even automate the migration process. For more information, see [this migration article](../../../../../concepts/translations/fallback-language-selection.md#migration-and-linting-via-command). +check the translation files, or use the `--fix` parameter to even automate the migration process. For more information, see [this migration article](../../concepts/translations/fallback-language-selection.md#migration-and-linting-via-command). ### Manual @@ -76,7 +76,7 @@ Here are some example locales that are dialects of the generic base layer. └··· ``` -For more details on selecting a fallback language and structuring your snippet files, see the [Fallback Languages guide](../../../../../concepts/translations/fallback-language-selection.md). +For more details on selecting a fallback language and structuring your snippet files, see the [Fallback Languages guide](../../concepts/translations/fallback-language-selection.md). ## Testing Your Migration diff --git a/guides/upgrades-migrations/language-pack-migration.md b/guides/upgrades-migrations/language-pack-migration.md index b9a06d262c..509643522f 100644 --- a/guides/upgrades-migrations/language-pack-migration.md +++ b/guides/upgrades-migrations/language-pack-migration.md @@ -88,6 +88,6 @@ Starting with **Shopware 6.7.7.0** and **Language Pack 5.37.1**, the migration p please update Shopware to >= 6.7.7.0, Language Pack to >= 5.37.1, remove the translation files created from running the command and run the command again. Or follow the updated migration guide. -[translation-system]: ../../../../../concepts/translations/built-in-translation-system.md +[translation-system]: ../../concepts/translations/built-in-translation-system.md [language-pack-plugin]: https://store.shopware.com/en/swag338126230916f/shopware-language-pack.html [shopware-translations]: https://translate.shopware.com diff --git a/index.md b/index.md index 194bb08bb0..36ae5c2abd 100644 --- a/index.md +++ b/index.md @@ -14,6 +14,6 @@ These two sections are complemented by the **References**, which contain structu Visit the [academy](https://academy.shopware.com/collections?category=developer-sw6) for video content. If you have any questions left, you can always ask them on [StackOverflow](https://stackoverflow.com/questions/tagged/shopware6?tab=Newest) or join our awesome community on [Discord](https://discord.com/channels/1308047705309708348/1309107911175176217). -To begin developing, [start here with our installation guide](guides/installation.md). +To begin developing, [start here with our installation guide](../docs/guides/installation/index.md). ![Readme](assets/readme-splash.png) diff --git a/products/cli/extension-commands/build.md b/products/cli/extension-commands/build.md index 354d60b0d5..92b629836e 100644 --- a/products/cli/extension-commands/build.md +++ b/products/cli/extension-commands/build.md @@ -1,13 +1,13 @@ --- nav: - title: Building extensions and creating archives + title: Building Extensions and Creating Archives position: 2 --- -# Building extensions and creating archives +# Building Extensions and Creating Archives -Extensions consist of PHP Changes, JavaScript and CSS. To release an extension to the Shopware Store or upload it to a Shopware 6 instance without having to rebuild Storefront and Administration, your extension needs to provide the compiled assets. +Extensions consist of PHP Changes, JavaScript, and CSS. To release an extension to the Shopware Store or upload it to a Shopware 6 instance without having to rebuild Storefront and Administration, your extension needs to provide the compiled assets. ## Building an extension diff --git a/products/cli/project-commands/autofix.md b/products/cli/project-commands/autofix.md index e8a5307b79..aaf1b15af8 100644 --- a/products/cli/project-commands/autofix.md +++ b/products/cli/project-commands/autofix.md @@ -9,7 +9,7 @@ nav: Shopware-CLI comes with some builtin auto fixers for project migrations. -## Migrate a Project to Symfony Flex +## Migrate a project to Symfony Flex Prior to Shopware 6.5, Shopware didn't use Symfony Flex. This means that the project structure was different, and some configuration files were located in different places. The `shopware-cli project autofix flex` command will migrate your project to Symfony Flex and move all configuration files to the correct locations. @@ -25,7 +25,7 @@ The command will delete all unnecessary configuration files. It will also update ## Migrate custom/plugins extensions to Composer -It's best practice to manage the store and your custom plugins via Composer. [If you want to learn more about this check out this guide](../../../guides/hosting/installation-updates/extension-managment.md). Shopware-CLI has a helper for migrating locally installed plugins to Composer through Shopware Packagist for the Shopware Store. Make sure you have a Shopware Packages Token, which can be gathered in the Shopware Account. You can find the token in the Shopware Account under "Shops" > "Licenses" > "..." of one extension and "Install via Composer. +It's best practice to manage the store and your custom plugins via Composer. [If you want to learn more about this check out this guide](../../../guides/hosting/installation-updates/extension-management.md). Shopware-CLI has a helper for migrating locally installed plugins to Composer through Shopware Packagist for the Shopware Store. Make sure you have a Shopware Packages Token, which can be gathered in the Shopware Account. You can find the token in the Shopware Account under "Shops" > "Licenses" > "..." of one extension and "Install via Composer. ```bash shopware-cli project autofix composer-plugins diff --git a/products/cli/project-commands/mysql-dump.md b/products/cli/project-commands/mysql-dump.md index 307fe11e23..b10ed0d68f 100644 --- a/products/cli/project-commands/mysql-dump.md +++ b/products/cli/project-commands/mysql-dump.md @@ -1,11 +1,11 @@ --- nav: - title: Generating MySQL dumps + title: Generating MySQL Dumps position: 1 --- -# Generating MySQL dumps +# Generating MySQL Dumps Shopware CLI has built-in support for generating MySQL dumps. The dump command is native implementation and does not use existing tools like `mysqldump`. diff --git a/products/cli/project-commands/remote-extension-managment.md b/products/cli/project-commands/remote-extension-management.md similarity index 93% rename from products/cli/project-commands/remote-extension-managment.md rename to products/cli/project-commands/remote-extension-management.md index 7235008547..9bf8486841 100644 --- a/products/cli/project-commands/remote-extension-managment.md +++ b/products/cli/project-commands/remote-extension-management.md @@ -5,7 +5,7 @@ nav: --- -# Remote extension management +# Remote Extension Management Shopware CLI has an extension manager to install and manage extensions in your Shopware project through the Shopware API like the Extension Manager in the Shopware 6 Administration panel, but for the CLI. @@ -13,7 +13,7 @@ Shopware CLI has an extension manager to install and manage extensions in your S This functionality was designed for Shopware SaaS and should not be used for self-hosted installations. [The recommendation is to use the Deployment Helper and install all plugins via Composer](../../../guides/hosting/installation-updates/deployments/deployment-helper.md) ::: -To use the extension manager, you need a `.shopware-project.yml` or set environment variables. See here for more information about the [Fixture Bundle](../../../resources/tooling/fixture-bundle/index.md). +To use the extension manager, you need a `.shopware-project.yml` or set environment variables. See here for more information about the [Fixture Bundle](../../../guides/development/tooling/fixture-bundle.md). ::: warning Make sure you log in using your username and password to the CLI. The extension API can be used **only by users**. diff --git a/products/cli/shopware-account-commands/authentication.md b/products/cli/shopware-account-commands/authentication.md index 6bc08a424c..9a123ff676 100644 --- a/products/cli/shopware-account-commands/authentication.md +++ b/products/cli/shopware-account-commands/authentication.md @@ -7,14 +7,12 @@ nav: # Authentication -To interact with the Shopware Account API, you need to authenticate yourself. - -For this, you need to log in using: +To interact with the Shopware Account API, you need to authenticate yourself. Run the command: ```bash shopware-cli account login ``` -and it will open a browser window for you to log in. +A browser window will open for you to log in. -For CI/CD pipelines, you should pass `SHOPWARE_CLI_ACCOUNT_CLIENT_ID` and `SHOPWARE_CLI_ACCOUNT_CLIENT_SECRET` as environment variables and call directly the command you want to use. The client ID and client secret can be generated in the **Extension Partner** section under the [Development](https://account.shopware.com/producer/development) navigation point in the [Shopware Account](https://account.shopware.com). +For CI/CD pipelines, pass `SHOPWARE_CLI_ACCOUNT_CLIENT_ID` and `SHOPWARE_CLI_ACCOUNT_CLIENT_SECRET` as environment variables and directly call the command you want to use. The client ID and client secret can be generated in the **Extension Partner** section under the [Development](https://account.shopware.com/producer/development) navigation point in the [Shopware Account](https://account.shopware.com). diff --git a/products/digital-sales-rooms/index.md b/products/digital-sales-rooms/index.md index 3fa44dff69..cba80b0bc7 100644 --- a/products/digital-sales-rooms/index.md +++ b/products/digital-sales-rooms/index.md @@ -31,7 +31,7 @@ Review the below minimum operating requirements before you install the *Digital * [pnpm](https://pnpm.io/installation) >= 8 * [Shopware Frontends framework](https://frontends.shopware.com/) based on Nuxt 3. * Instance of [Shopware 6](../../guides/installation/) (version 6.6.0 and above). - * Recommend installing with [devenv](../../guides/installation/setups/devenv.md) + * Recommend installing with [devenv](../../guides/installation/legacy-setups/devenv-setup.md) * Third party services: * [Daily.co](https://www.daily.co/) - Refer to setup instructions for [realtime video call](./setup-3rd-party/realtime-video-dailyco.md) * [Mercure](https://mercure.rocks/)- Refer to setup instructions for [realtime Mercure service](./setup-3rd-party/realtime-service-mercure.md) diff --git a/products/paas/shopware-paas/repository.md b/products/paas/shopware-paas/repository.md index 40152d6a96..7beccb60b5 100644 --- a/products/paas/shopware-paas/repository.md +++ b/products/paas/shopware-paas/repository.md @@ -19,7 +19,7 @@ This guide explains the repository setup using **GitHub**. You can also integrat ## Create a Shopware project -Firstly, create a new project with `composer create-project shopware/production <folder-name>` using the [Symfony Flex](../../../guides/installation/template.md) template. +Firstly, create a new project with `composer create-project shopware/production <folder-name>` using the [Symfony Flex template](../../../guides/installation/project-overview.md#project-template). This will create a brand new Shopware 6 project in the given folder. Now, change it into the newly created project and require the PaaS configuration with `composer req shopware/paas-meta`. @@ -77,14 +77,14 @@ shopware <paas-url>.git (push) ## Migrating from the old template to the new template -If you have already used the [Shopware PaaS old template](https://github.com/shopwareArchive/paas), please follow the guide to [migrate it to the new structure](../../../guides/installation/template#how-to-migrate-from-production-template-to-symfony-flex). +If you have already used the [Shopware PaaS old template](https://github.com/shopwareArchive/paas), please follow the guide to [migrate it to the new structure](../../../products/cli/project-commands/autofix.md#migrate-a-project-to-symfony-flex). The following tasks have to be done additionally to the flex migration: * The root `.platform.app.yml` has been moved to `.platform/applications.yaml` * The following services has been renamed: - * `queuerabbit` to `rabbitmq` - * `searchelastic` to `opensearch` + * `queuerabbit` to `rabbitmq` + * `searchelastic` to `opensearch` As the services are renamed, a completely new service will be created. Here are three possible options available: diff --git a/resources/guidelines/troubleshooting/index.md b/resources/guidelines/troubleshooting/index.md deleted file mode 100644 index 2abc7f7837..0000000000 --- a/resources/guidelines/troubleshooting/index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -nav: - title: Troubleshooting - position: 10 - ---- - -# Troubleshooting - -Use this section to diagnose and resolve common issues you might encounter while working with Shopware projects. diff --git a/resources/references/index.md b/resources/references/index.md index e937a0dd77..aa6dcf74b2 100644 --- a/resources/references/index.md +++ b/resources/references/index.md @@ -7,4 +7,43 @@ nav: # References -The references serve as essential resources for developers, administrators, and testers, providing comprehensive details on implementation parameters. They cover every aspect of the platform, including objects, functions, classes, and more. By consulting these references, you will be able to gain a deep understanding of Shopware's capabilities and utilize its features effectively in your development, administration, and testing tasks. +his section contains structured technical reference documentation for Shopware. Use it when you need precise specifications, XML schemas, CLI commands, event payloads, or implementation details. Step-by-step guides are in other sections. + +## Core and platform references + +Behavior, parameters, and configuration: + +* **Security**: Platform security features, configuration options, and hardening +* **Commands Reference**: Complete CLI command overview (`bin/console`) +* System & configuration details + +## App development reference + +Authoritative reference documentation for building Shopware Apps and implementing or validating features: + +* **Manifest Reference**: `manifest.xml` structure and supported sections +* **CMS Reference**: `cms.xml` blocks and slots definition +* **Entities Reference**: `entities.xml` schema and relations +* **Flow Action Reference**: `flow-action.xml` definition +* **Payment Reference**: App-based payment API contracts +* **Webhook Events Reference**: Available webhook events, payloads, and permissions + +## Script reference + +Detailed reference for Twig-based App Scripts: + +* Available services +* Cart manipulation +* Data loading +* Custom endpoints +* Hooks and extension points + +## Architecture Decision Records (ADRs) + +The ADR folder documents architectural decisions made in Shopware: + +* Rationale behind technical design choices +* Trade-offs and constraints +* Historical context for core architecture + +Consult ADRs when you need to understand *why* something works the way it does. diff --git a/resources/references/security.md b/resources/references/security.md index 2c34f39b9b..e2f5bc974d 100644 --- a/resources/references/security.md +++ b/resources/references/security.md @@ -24,7 +24,7 @@ This is because, in such cases, malicious actors would already need to be authen ## API-aware field -The `ApiAware` flag allows you to control what fields of your entity are exposed to the Store API. For more information, refer to [Flags Reference](core-reference/dal-reference/flags-reference). +The `ApiAware` flag allows you to control what fields of your entity are exposed to the Store API. For more information, refer to [Flags Reference](../../guides/development/troubleshooting/dal-reference/flags-reference.md). ## Captcha From 6d00eda98313ca60ea16c93f197d043cbb786f3c Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Thu, 7 May 2026 18:37:50 +0200 Subject: [PATCH 02/39] Update index.md --- resources/references/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/resources/references/index.md b/resources/references/index.md index aa6dcf74b2..75215c2f0a 100644 --- a/resources/references/index.md +++ b/resources/references/index.md @@ -7,7 +7,7 @@ nav: # References -his section contains structured technical reference documentation for Shopware. Use it when you need precise specifications, XML schemas, CLI commands, event payloads, or implementation details. Step-by-step guides are in other sections. +This section contains structured technical reference documentation for Shopware. Use it when you need precise specifications, XML schemas, CLI commands, event payloads, or implementation details. Step-by-step guides are in other sections. ## Core and platform references From deec71708d995dd9200feca5f25d2f131bad6a77 Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Thu, 7 May 2026 18:46:28 +0200 Subject: [PATCH 03/39] Update index.md --- index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/index.md b/index.md index 36ae5c2abd..2644612cdf 100644 --- a/index.md +++ b/index.md @@ -14,6 +14,6 @@ These two sections are complemented by the **References**, which contain structu Visit the [academy](https://academy.shopware.com/collections?category=developer-sw6) for video content. If you have any questions left, you can always ask them on [StackOverflow](https://stackoverflow.com/questions/tagged/shopware6?tab=Newest) or join our awesome community on [Discord](https://discord.com/channels/1308047705309708348/1309107911175176217). -To begin developing, [start here with our installation guide](../docs/guides/installation/index.md). +To begin developing, [start here with our installation guide](guides/installation/index.md). ![Readme](assets/readme-splash.png) From 234dfb0f342003f25104bde4b7363a077b7c6895 Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Thu, 7 May 2026 18:47:40 +0200 Subject: [PATCH 04/39] Update index.md --- guides/plugins/plugins/storefront/templates/index.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/plugins/plugins/storefront/templates/index.md b/guides/plugins/plugins/storefront/templates/index.md index 96fcab9805..d00876804f 100644 --- a/guides/plugins/plugins/storefront/templates/index.md +++ b/guides/plugins/plugins/storefront/templates/index.md @@ -14,4 +14,4 @@ This section explains how to customize and extend Storefront templates in plugin ## Reference -* [Shopware's Twig Runctions](./twig-function-reference.md) +* [Shopware's Twig Functions](./twig-function-reference.md) From b603607fac579d26378ca9dc57ff1046ce2a66b5 Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Thu, 7 May 2026 18:49:15 +0200 Subject: [PATCH 05/39] Update twig-function-reference.md --- .../storefront/templates/twig-function-reference.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/guides/plugins/plugins/storefront/templates/twig-function-reference.md b/guides/plugins/plugins/storefront/templates/twig-function-reference.md index 957c0392ce..8e29dcd051 100644 --- a/guides/plugins/plugins/storefront/templates/twig-function-reference.md +++ b/guides/plugins/plugins/storefront/templates/twig-function-reference.md @@ -36,9 +36,9 @@ Templates which are imported via \{\% sw_use \%\} are not allowed to have additi |:---------------|:---------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------------------------------------------------------------------------------------------| | `config` | Gets a value from the system config (used by plugins and global settings) for the given sales channel | See [Reading the configuration values](../../../apps/lifecycle/configuration.md) | | `theme_config` | Gets a value from the current theme | See [Theme configuration](../../../themes/configuration/theme-configuration.md) | -| `sw_block` | Renders a block of the same or another file with support for multi inheritance. The is the same as in Twig's default `block` | See [Twig 3 documentation for `block`](https://twig.symfony.com/doc/3.x/functions/block.html) | -| `sw_source` | Prints the content of a template file with support for multi inheritance. The is the same as in Twig's default `source` | See [Twig 3 documentation for `source`](https://twig.symfony.com/doc/3.x/functions/source.html) | -| `sw_include` | Renders the content of another template file with support for multi inheritance. The is the same as in Twig's default `include` and the new `sw_include` tag | See [Twig 3 documentation for `include`](https://twig.symfony.com/doc/3.x/functions/include.html) | +| `sw_block` | Renders a block of the same or another file with support for multi-inheritance. This is the same as in Twig's default `block` | See [Twig 3 documentation for `block`](https://twig.symfony.com/doc/3.x/functions/block.html) | +| `sw_source` | Prints the content of a template file with support for multi-inheritance. This is the same as in Twig's default `source` | See [Twig 3 documentation for `source`](https://twig.symfony.com/doc/3.x/functions/source.html) | +| `sw_include` | Renders the content of another template file with support for multi-inheritance. This is the same as in Twig's default `include` and the new `sw_include` tag | See [Twig 3 documentation for `include`](https://twig.symfony.com/doc/3.x/functions/include.html) | ## Filter @@ -46,7 +46,7 @@ Templates which are imported via \{\% sw_use \%\} are not allowed to have additi |:--------------------|:------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:----------------------------------------------------------------------------------------------------------------------------------------------------------------| | `replace_recursive` | Enables recursive replacement in addition to twig's default `replace` filter | To see an example, see the guide on [add custom JavaScript](../javascript/add-custom-javascript.md) | | `currency` | Adopts currency formatting: The currency symbol and the comma setting. | --- | -| `sw_sanitize` | Filters tags and attributes from a given string. By default, twig's auto escaping is on, so this filter explicitly allows basic HTML tags like <i%gt;, <b>,... | --- | +| `sw_sanitize` | Filters tags and attributes from a given string. By default, Twig's auto escaping is on, so this filter explicitly allows basic HTML tags like <i%gt;, <b>,... | --- | | `sw_convert_unit` | Convert between measurement units | Available since 6.7.1.0, to see examples, see the [adr on the measurement system](../../../../../resources/references/adr/2025-05-12-implement-measurement-system.md) | ## Extensions From 228fcf7aa76b9b41f0d0fda986f57817de408812 Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Thu, 7 May 2026 18:50:28 +0200 Subject: [PATCH 06/39] Update add-custom-cms-blocks.md --- guides/plugins/apps/content/cms/add-custom-cms-blocks.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) 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 18c29d73de..90eef7a672 100644 --- a/guides/plugins/apps/content/cms/add-custom-cms-blocks.md +++ b/guides/plugins/apps/content/cms/add-custom-cms-blocks.md @@ -1,11 +1,11 @@ --- nav: - title: Add Custom CMS bBlocks + 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. From 8c5b06608fedebad21fbbdf7003b48d17a81541d Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Thu, 7 May 2026 18:53:01 +0200 Subject: [PATCH 07/39] Update index.md --- guides/plugins/apps/app-sdks/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/plugins/apps/app-sdks/index.md b/guides/plugins/apps/app-sdks/index.md index 7998de67f6..e08baee86c 100644 --- a/guides/plugins/apps/app-sdks/index.md +++ b/guides/plugins/apps/app-sdks/index.md @@ -12,5 +12,5 @@ The Shopware app SDK enables you to build applications and plugins that extend t | **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 PH](../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, but less explicitly productized around ops/security than Go | 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 productized feature | Not prominently surfaced | Not prominently surfaced | Symfony Bundle | Yes, via PSR Request/Response/HttpClient/Repository | -| [App SDK JS](../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, but thinner explicit ops/security story than Go SDK | 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 | +| [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, but less explicitly productized around ops/security than Go | 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 productized feature | Not prominently surfaced | Not prominently surfaced | Symfony Bundle | Yes, via PSR Request/Response/HttpClient/Repository | +| [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, but thinner explicit ops/security story than Go SDK | 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 | From c4ad1f13bfdb3887f18183b2eadf8c2c2d892adb Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Thu, 7 May 2026 18:54:09 +0200 Subject: [PATCH 08/39] Update message-queue.md --- guides/hosting/infrastructure/message-queue.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/hosting/infrastructure/message-queue.md b/guides/hosting/infrastructure/message-queue.md index f53e6ad3f2..95c64d136b 100644 --- a/guides/hosting/infrastructure/message-queue.md +++ b/guides/hosting/infrastructure/message-queue.md @@ -13,7 +13,7 @@ Shopware uses the Symfony Messenger component and Enqueue to handle asynchronous ## Message queue on production systems -On a production system, the message queue should be processed via the CLI instead of the browser in the Administration ([Admin worker](#admin-worker). This way, tasks are also completed when no one is logged into the Administration and high CPU load due to multiple users in the admin is also avoided. Furthermore, 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. +On a production system, the message queue should be processed via the CLI instead of the browser in the Administration ([Admin worker](#admin-worker)). This way, tasks are also completed when no one is logged into the Administration and high CPU load due to multiple users in the admin is also avoided. Furthermore, 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. It is recommended to run one or more `messenger:consume` workers. To automatically start the processes again after they stopped because of exceeding the given limits you can use a process control system like [systemd](https://www.freedesktop.org/wiki/Software/systemd/) or [supervisor](http://supervisord.org/running.html). Alternatively, you can configure a cron job that runs the command periodically. From de1a0b3dd3260186dcff0c9fb8592be65e7d4082 Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Thu, 7 May 2026 18:55:23 +0200 Subject: [PATCH 09/39] Update code-structure.md --- guides/development/extensions/code-structure.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/development/extensions/code-structure.md b/guides/development/extensions/code-structure.md index 41926da268..de25d3128d 100644 --- a/guides/development/extensions/code-structure.md +++ b/guides/development/extensions/code-structure.md @@ -23,7 +23,7 @@ nav: ## Project/bundle structure -* Keep domain logic in bundles, not in templates or controllers; expose services via dependency injection. Se the [bundle guide](../../plugins/plugins/bundle.md) for further guidance. +* 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. From 1fc0bf3a25117c71c59e00c0bf03c6151343245e Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Thu, 7 May 2026 18:59:50 +0200 Subject: [PATCH 10/39] Update index.md --- guides/plugins/apps/app-sdks/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/plugins/apps/app-sdks/index.md b/guides/plugins/apps/app-sdks/index.md index e08baee86c..5b5edcbcd5 100644 --- a/guides/plugins/apps/app-sdks/index.md +++ b/guides/plugins/apps/app-sdks/index.md @@ -12,5 +12,5 @@ The Shopware app SDK enables you to build applications and plugins that extend t | **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, but less explicitly productized around ops/security than Go | 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 productized feature | Not prominently surfaced | Not prominently surfaced | Symfony Bundle | Yes, via PSR Request/Response/HttpClient/Repository | -| [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, but thinner explicit ops/security story than Go SDK | 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 | +| [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 | From a8234942a08b3a379f4fce5542adf4658af4121c Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Fri, 8 May 2026 08:52:05 +0200 Subject: [PATCH 11/39] Update devenv-setup.md --- guides/installation/legacy-setups/devenv-setup.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/installation/legacy-setups/devenv-setup.md b/guides/installation/legacy-setups/devenv-setup.md index 0b89eea9a5..7517fd3d65 100644 --- a/guides/installation/legacy-setups/devenv-setup.md +++ b/guides/installation/legacy-setups/devenv-setup.md @@ -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. From e7807fbeb4350780aafafd3a44de0209da1b361c Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Fri, 8 May 2026 08:52:40 +0200 Subject: [PATCH 12/39] Update devenv-setup.md --- guides/installation/legacy-setups/devenv-setup.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/installation/legacy-setups/devenv-setup.md b/guides/installation/legacy-setups/devenv-setup.md index 7517fd3d65..937a3c6cd3 100644 --- a/guides/installation/legacy-setups/devenv-setup.md +++ b/guides/installation/legacy-setups/devenv-setup.md @@ -355,8 +355,8 @@ export LANG=en_US.UTF-8 Default credentials: -- User: `shopware` -- Password: `shopware` +* User: `shopware` +* Password: `shopware` ### Mailhog From 5b59c5500d2c8b28b813e5db9c18bbe688acc9f2 Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Fri, 8 May 2026 08:53:21 +0200 Subject: [PATCH 13/39] Update migrate-zip-to-composer-project.md --- .../legacy-setups/migrate-zip-to-composer-project.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/installation/legacy-setups/migrate-zip-to-composer-project.md b/guides/installation/legacy-setups/migrate-zip-to-composer-project.md index 904cfed614..30e9dc6ee8 100644 --- a/guides/installation/legacy-setups/migrate-zip-to-composer-project.md +++ b/guides/installation/legacy-setups/migrate-zip-to-composer-project.md @@ -148,4 +148,4 @@ Adjusting environment variables may be necessary as the names have changed: | 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`. \ No newline at end of file +After reviewing the changes, commit them to the Git repository. All upcoming config changes can be applied with `composer recipes:update`. From 018c0ae5a3520d835530293d52ffb5c890e21837 Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Fri, 8 May 2026 08:54:04 +0200 Subject: [PATCH 14/39] Update add-custom-modules.md --- guides/plugins/apps/administration/add-custom-modules.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/guides/plugins/apps/administration/add-custom-modules.md b/guides/plugins/apps/administration/add-custom-modules.md index 8eb6777acc..c3d778adfd 100644 --- a/guides/plugins/apps/administration/add-custom-modules.md +++ b/guides/plugins/apps/administration/add-custom-modules.md @@ -19,8 +19,6 @@ You should be familiar with the concept of Apps, especially their registration f <PageRef page="../app-base-guide" /> -## Overview - In your app, you are able to add your own modules to the Administration. Your custom modules are loaded as iframes which are embedded in the Shopware Administration and within this iframe, your website will be loaded and shown. Creating custom modules takes place at the `<admin>` section of your `manifest.xml`; see the [Manifest Reference](../../../../resources/references/app-reference/manifest-reference.md) for more details. You can add any amount of custom modules by adding new `<module>` elements to your manifest. From e41ff1e7f1d4087893478df334e78dc248067fd5 Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Fri, 8 May 2026 08:58:34 +0200 Subject: [PATCH 15/39] Update cart-manipulation.md --- guides/plugins/apps/app-scripts/cart-manipulation.md | 9 +++------ 1 file changed, 3 insertions(+), 6 deletions(-) diff --git a/guides/plugins/apps/app-scripts/cart-manipulation.md b/guides/plugins/apps/app-scripts/cart-manipulation.md index 07289035de..939a877a3d 100644 --- a/guides/plugins/apps/app-scripts/cart-manipulation.md +++ b/guides/plugins/apps/app-scripts/cart-manipulation.md @@ -9,18 +9,15 @@ nav: ## Overview -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. +If your app needs to modify the cart, you can use the [`cart`](../../../../resources/references/app-reference/script-reference/script-hooks-reference#cart) script hook. App scripts extend the general [cart concept](../../../../concepts/commerce/checkout-concept/cart) by acting as another [cart processor](../../../../concepts/commerce/checkout-concept/cart#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#cart). ## Prerequisites From 218ab998d3bdba02554d9be4ae054610cdc025a0 Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Fri, 8 May 2026 09:09:37 +0200 Subject: [PATCH 16/39] Update data-loading.md --- .../plugins/apps/app-scripts/data-loading.md | 19 +++++++++---------- 1 file changed, 9 insertions(+), 10 deletions(-) diff --git a/guides/plugins/apps/app-scripts/data-loading.md b/guides/plugins/apps/app-scripts/data-loading.md index 4b84c35de8..7627bff8b9 100644 --- a/guides/plugins/apps/app-scripts/data-loading.md +++ b/guides/plugins/apps/app-scripts/data-loading.md @@ -9,26 +9,25 @@ nav: ## 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 template. +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 From 0d3bcd47ea5248dd23c626aec0aa536b7da2185d Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Fri, 8 May 2026 09:14:22 +0200 Subject: [PATCH 17/39] Update add-custom-cms-blocks.md --- guides/plugins/apps/content/cms/add-custom-cms-blocks.md | 9 ++++----- 1 file changed, 4 insertions(+), 5 deletions(-) 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 90eef7a672..71c84de90f 100644 --- a/guides/plugins/apps/content/cms/add-custom-cms-blocks.md +++ b/guides/plugins/apps/content/cms/add-custom-cms-blocks.md @@ -9,13 +9,13 @@ nav: ::: info This functionality is available starting with Shopware 6.4.4.0. +::: info ## Overview You can [add custom CMS blocks](../../../plugins/content/cms/add-cms-block) using the plugin system. However, these will not be available in Shopware cloud stores. -::: -Didn't get in touch with Shopware's Shopping Experiences \(CMS\) yet? Check out the concept behind it first: +New to Shopware's Shopping Experiences \(CMS\)? Start with the concept behind it: <PageRef page="../../../../../concepts/commerce/content/shopping-experiences-cms" /> @@ -23,10 +23,9 @@ Didn't get in touch with Shopware's Shopping Experiences \(CMS\) yet? Check out This guide is based on our [App Base Guide](../../app-base-guide) 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). -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: From bf8103a935655f5ae05f359bf8c7347087fae7ba Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Fri, 8 May 2026 09:16:52 +0200 Subject: [PATCH 18/39] Update creating-plugins.md --- guides/plugins/plugins/creating-plugins.md | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/guides/plugins/plugins/creating-plugins.md b/guides/plugins/plugins/creating-plugins.md index d130d10e20..256217139b 100644 --- a/guides/plugins/plugins/creating-plugins.md +++ b/guides/plugins/plugins/creating-plugins.md @@ -150,6 +150,7 @@ Here's an example `composer.json` you can refer to: } } ``` + </details> ::: warning @@ -189,9 +190,9 @@ SwagBasicExample/ └── SwagBasicExample.php ``` -- **namespace**: here, it's `Swag\BasicExample`. We recommend using a combination of your manufacturer prefix and the technical name to name it. -- **`src/` directory**: recommended but not strictly required. -- **PHP class**: `SwagBasicExample.php`, which you name after your plugin. +* **namespace**: here, it's `Swag\BasicExample`. We recommend using a combination of your manufacturer prefix and the technical name to name it. +* **`src/` directory**: recommended but not strictly required. +* **PHP class**: `SwagBasicExample.php`, which you name after your plugin. The new class `SwagBasicExample` must extend Shopware's abstract plugin class, `Shopware\Core\Framework\Plugin`: From 897181a5508271184b30c80f581978dedf1abfa5 Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Fri, 8 May 2026 09:18:01 +0200 Subject: [PATCH 19/39] Update custom-fields-of-type-media.md --- .../plugins/database/custom-fields-of-type-media.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/guides/plugins/plugins/database/custom-fields-of-type-media.md b/guides/plugins/plugins/database/custom-fields-of-type-media.md index ed2d09d559..5b2ff2b534 100644 --- a/guides/plugins/plugins/database/custom-fields-of-type-media.md +++ b/guides/plugins/plugins/database/custom-fields-of-type-media.md @@ -12,18 +12,16 @@ After adding a custom field of type media in the Administration or via a plugin, This is often used on products to add additional images to the product detail page. If you want to learn more about custom fields, take a look at [Adding custom fields](../framework/custom-field/add-custom-field). -## Overview +## Resolve media custom fields in Twig -In the product detail page template, `page.product.translated.customFields.xxx` (where `xxx` is your custom field name) contains the media UUID. -Resolve this UUID by using Twig's `searchMedia` function: +In the product detail page template, `page.product.translated.customFields.xxx` (where `xxx` is your custom field name) contains the media UUID. Resolve this UUID by using Twig's `searchMedia` function: ```php // platform/src/Core/Framework/Adapter/Twig/Extension/MediaExtension.php public function searchMedia(array $ids, Context $context): MediaCollection { ... } ``` -This function resolves the corresponding media entities for the given IDs. -Here is an example with a custom field \(`custom_sports_media_id`\) on the product detail page: +This function resolves the corresponding media entities for the given IDs. Here is an example with a custom field \(`custom_sports_media_id`\) on the product detail page: ```twig // <plugin root>/src/Resources/views/storefront/page/content/product-detail.html.twig From f971229654c29f72d7f375eebe0d2768c7cd51d5 Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Fri, 8 May 2026 09:19:10 +0200 Subject: [PATCH 20/39] Update plugin-lifecycle.md --- guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md | 1 - 1 file changed, 1 deletion(-) diff --git a/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md b/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md index 8989d1c102..7e0052682b 100644 --- a/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md +++ b/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md @@ -82,7 +82,6 @@ Avoid creating new business data for your plugin in the `install()` method. Crea * Activate entities that you created in the install method, e.g. such as a payment method * Create new entities or data that you couldn't create with `install()` - ```php // <plugin root>/src/SwagBasicExample public function activate(ActivateContext $activateContext): void From 8295892f234592c3fe5d4afe37995b355863c4aa Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Fri, 8 May 2026 09:35:49 +0200 Subject: [PATCH 21/39] Update customize-templates.md --- .../plugins/storefront/templates/customize-templates.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/plugins/plugins/storefront/templates/customize-templates.md b/guides/plugins/plugins/storefront/templates/customize-templates.md index e70b27fd12..7d7f967173 100644 --- a/guides/plugins/plugins/storefront/templates/customize-templates.md +++ b/guides/plugins/plugins/storefront/templates/customize-templates.md @@ -13,8 +13,8 @@ This guide will cover customizing Storefront templates with a plugin. ## Prerequisites -- Familiarity with the [Plugin base guide](../../plugin-base-guide.md) and how to create plugins -- Knowledge of [Twig](https://twig.symfony.com/) is advantageous but not necessary +* Familiarity with the [Plugin base guide](../../plugin-base-guide.md) and how to create plugins +* Knowledge of [Twig](https://twig.symfony.com/) is advantageous but not necessary ## Getting started From 911f26c8acdf834d2d5a12e1ed716c415045e488 Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Fri, 8 May 2026 09:39:11 +0200 Subject: [PATCH 22/39] Update index.md --- guides/plugins/plugins/index.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/plugins/plugins/index.md b/guides/plugins/plugins/index.md index 3d9a202c10..56c4a91bca 100644 --- a/guides/plugins/plugins/index.md +++ b/guides/plugins/plugins/index.md @@ -36,8 +36,8 @@ You will typically use a plugin when you need to: * Integrate third-party systems, including identity providers * Enable dynamic validations -:::Info -For infrastructure and external system integrations (e.g., Redis, Elasticsearch, or custom APIs), refer to the dedicated [integration guides](../plugins/integrations/index.md /integrations). +::: info +For infrastructure and external system integrations (e.g., Redis, Elasticsearch, or custom APIs), refer to the dedicated [integration guides](../plugins/integrations/index.md). ::: ### Choosing the right extension type From 90199dc482ed39b1cd016aaccc4aeccd65ba5bef Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Fri, 8 May 2026 10:29:01 +0200 Subject: [PATCH 23/39] Update webhook.md --- guides/plugins/apps/lifecycle/webhook.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/guides/plugins/apps/lifecycle/webhook.md b/guides/plugins/apps/lifecycle/webhook.md index c4d7c86ab9..65a125997e 100644 --- a/guides/plugins/apps/lifecycle/webhook.md +++ b/guides/plugins/apps/lifecycle/webhook.md @@ -108,8 +108,8 @@ The `source` property contains all necessary information about the Shopware inst * `url` is the URL under which your app can reach the Shopware instance and its API. * `appVersion` is the version of the app that is installed. -* `shopId` is the id by which you can identify the Shopware instance. -* `eventId` is a unique identifier of the event. This id will not change if sending of the webhook is retried, etc. **Since 6.4.11.0**. +* `shopId` is the ID by which you can identify the Shopware instance. +* `eventId` is a unique identifier of the event. This ID will not change if sending of the webhook is retried, etc. **Since 6.4.11.0**. The next property, `data` contains the name of the event so that a single endpoint can handle several different events. `data` also contains the event data in the `payload` property. Due to the asynchronous nature of these webhooks, the `payload` for `entity.written` events does not contain complete entities as these might become outdated. Instead, the entity in the payload is characterized by its id, stored under `primaryKey`, so the app can fetch additional data through the shop API. This also has the advantage of giving the app explicit control over the associations that get fetched instead of relying on the associations determined by the event. Other events, in contrast, contain the entity data that defines the event but keep in mind that the event might not contain all associations. @@ -117,7 +117,7 @@ The next property, `timestamp` is the time at which the webhook was handled. Thi ::: info Starting from Shopware version 6.4.1.0, the current Shopware version will be sent as a `sw-version` header. -Starting from Shopware version 6.4.5.0, the current language id of the shopware context will be sent as a `sw-context-language` header, and the locale of the user or locale of the context language is available under the `sw-user-language` header. +Starting from Shopware version 6.4.5.0, the current language ID of the shopware context will be sent as a `sw-context-language` header, and the locale of the user or locale of the context language is available under the `sw-user-language` header. ::: You can verify the authenticity of the incoming request by checking the `shopware-shop-signature`. Every request should have a SHA256 HMAC of the request body that is signed with the secret your app assigned the shop during the [registration](app-registration-setup.md#setup). The mechanism to verify the request is exactly the same as the one used for the [confirmation request](app-registration-setup.md#confirmation-request). From ca38db43b60594b34b0a707445ffc45f89d4ba61 Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Fri, 8 May 2026 11:35:04 +0200 Subject: [PATCH 24/39] Update phpstan.md --- guides/development/troubleshooting/phpstan.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/development/troubleshooting/phpstan.md b/guides/development/troubleshooting/phpstan.md index b8459e872a..fdcd6694fc 100644 --- a/guides/development/troubleshooting/phpstan.md +++ b/guides/development/troubleshooting/phpstan.md @@ -8,7 +8,7 @@ nav: 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. @@ -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. From 43424d459ce499b575870cf36870cac964f0de19 Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Fri, 8 May 2026 13:32:12 +0200 Subject: [PATCH 25/39] Update in-app-purchase-gateway.md --- .../apps/gateways/in-app-purchase/in-app-purchase-gateway.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/guides/plugins/apps/gateways/in-app-purchase/in-app-purchase-gateway.md b/guides/plugins/apps/gateways/in-app-purchase/in-app-purchase-gateway.md index 39788b57f5..bacd44c98b 100644 --- a/guides/plugins/apps/gateways/in-app-purchase/in-app-purchase-gateway.md +++ b/guides/plugins/apps/gateways/in-app-purchase/in-app-purchase-gateway.md @@ -19,8 +19,6 @@ The gateway enables app servers to restrict specific In-App Purchases based on a ::: info **Current Limitations:** At present, the In-App Purchase Gateway supports only restricting the checkout process for new In-App Purchases. -**Plans:** -We aim to expand its functionality to include filtering entire lists of In-App Purchases before they are displayed to users. ::: ## Prerequisites From 7dfb93646b9fa7605bd2a9c286eee56a8db8628f Mon Sep 17 00:00:00 2001 From: LApple <l.apple@shopware.com> Date: Mon, 11 May 2026 17:59:49 +0200 Subject: [PATCH 26/39] fix: update broken links --- concepts/framework/data-abstraction-layer.md | 2 +- concepts/framework/elasticsearch.md | 2 +- .../built-in-translation-system.md | 6 ++-- .../fallback-language-selection.md | 2 +- .../extensions/architecture/extendability.md | 2 +- guides/development/monetization/index.md | 6 ++-- .../testing/unit/jest-storefront.md | 2 +- .../elasticsearch/elasticsearch-debugging.md | 2 +- .../elasticsearch/elasticsearch-setup.md | 14 +++++----- .../infrastructure/reverse-http-cache.md | 2 +- .../deployments/build-w-o-db.md | 2 +- .../deployments/deployment-with-deployer.md | 16 +++++------ .../performing-updates.md | 4 +-- guides/hosting/performance/lock-store.md | 2 +- guides/hosting/performance/performance.md | 6 ++-- .../legacy-setups/devenv-setup.md | 2 +- .../add-cms-element-via-admin-sdk.md | 11 ++++---- .../add-custom-action-button.md | 2 +- .../apps/app-scripts/add-api-endpoint.md | 18 ++++++------ .../apps/app-scripts/cart-manipulation.md | 12 ++++---- guides/plugins/apps/app-scripts/index.md | 4 +-- .../apps/content/cms/add-custom-cms-blocks.md | 16 +++++------ .../apps/custom-data/custom-entities.md | 10 +++---- .../plugins/apps/custom-data/custom-fields.md | 6 ++-- ...add-custom-flow-actions-from-app-system.md | 10 +++---- ...dd-custom-flow-triggers-from-app-system.md | 6 ++-- .../apps/lifecycle/product-translator.md | 2 +- guides/plugins/apps/lifecycle/webhook.md | 2 +- .../add-custom-rule-conditions.md | 10 +++---- .../plugins/apps/storefront/apps-as-themes.md | 2 +- .../apps/storefront/cookies-with-apps.md | 8 +++--- .../apps/storefront/customize-templates.md | 8 +++--- .../using-data-handling.md | 4 +-- .../using-the-data-grid-component.md | 2 +- .../module-component-management/index.md | 17 ++++------- .../using-base-components.md | 2 +- .../add-acl-rules.md | 2 +- .../routing-navigation/overriding-routes.md | 6 ++-- .../services-utilities/injecting-services.md | 2 +- .../services-utilities/making-api-requests.md | 4 +-- .../cart/add-cart-processor-collector.md | 2 +- .../cart/customize-price-calculation.md | 4 +-- .../plugins/content/cms/add-cms-block.md | 4 +-- .../plugins/content/cms/add-cms-element.md | 28 +++++++++---------- .../content/cms/add-data-to-cms-elements.md | 6 ++-- .../media/add-custom-file-extension.md | 2 +- .../sitemap/add-custom-sitemap-entries.md | 15 ++++------ .../database/custom-fields-of-type-media.md | 2 +- .../plugins/database/database-migrations.md | 2 +- .../dependencies/add-plugin-dependencies.md | 6 ++-- .../using-composer-dependencies.md | 4 +-- .../dependencies/using-npm-dependencies.md | 6 ++-- .../data-handling/add-data-indexer.md | 8 +++--- .../framework/data-handling/reading-data.md | 2 +- .../data-handling/using-database-events.md | 2 +- .../framework/data-handling/using-flags.md | 4 +-- .../data-handling/versioning-entities.md | 8 +++--- .../framework/data-handling/writing-data.md | 16 +++++------ .../framework/filesystem/filesystem.md | 2 +- .../plugins/framework/filesystem/index.md | 2 +- .../framework/flow/action-transactions.md | 4 +-- .../framework/flow/add-flow-builder-action.md | 4 +-- .../flow/add-flow-builder-trigger.md | 9 +++--- .../message-queue/add-message-handler.md | 4 +-- .../message-queue/add-message-to-queue.md | 4 +-- .../framework/message-queue/add-middleware.md | 6 ++-- .../add-rate-limiter-to-api-route.md | 8 +++--- .../framework/rule/add-custom-rules.md | 12 ++++---- .../store-api/override-existing-route.md | 4 +-- .../system-check/add-custom-check.md | 2 +- ...oduct-entity-extension-to-elasticsearch.md | 4 +-- .../add-custom-commands.md | 2 +- .../plugin-fundamentals/add-scheduled-task.md | 4 +-- .../plugins/plugin-fundamentals/logging.md | 2 +- .../use-plugin-configuration.md | 2 +- .../plugins/services/adjusting-service.md | 2 +- .../plugins/services/dependency-injection.md | 4 +-- .../plugins/storefront/javascript/index.md | 6 ++-- .../override-existing-javascript.md | 2 +- .../storefront/styling/add-custom-assets.md | 2 +- .../themes/styling/add-css-js-to-theme.md | 2 +- products/digital-sales-rooms/index.md | 3 +- products/paas/shopware-paas/repository.md | 2 +- resources/references/security.md | 4 +-- 84 files changed, 223 insertions(+), 238 deletions(-) diff --git a/concepts/framework/data-abstraction-layer.md b/concepts/framework/data-abstraction-layer.md index db5619d5f6..e094ae9d7c 100644 --- a/concepts/framework/data-abstraction-layer.md +++ b/concepts/framework/data-abstraction-layer.md @@ -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: -<PageRef page="../../guides/plugins/plugins/services/add-custom-service" /> +<PageRef page="../../guides/plugins/plugins/services/add-custom-service.md" /> ### Translations diff --git a/concepts/framework/elasticsearch.md b/concepts/framework/elasticsearch.md index 6fded4e6e7..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 diff --git a/concepts/translations/built-in-translation-system.md b/concepts/translations/built-in-translation-system.md index 229ae44c87..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 diff --git a/concepts/translations/fallback-language-selection.md b/concepts/translations/fallback-language-selection.md index b39e1eeaf9..cbd854c357 100644 --- a/concepts/translations/fallback-language-selection.md +++ b/concepts/translations/fallback-language-selection.md @@ -62,4 +62,4 @@ For detailed instructions, see the [Extension Translation Migration](../../guide ## 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](../../guides/upgrades-migrations/extension-translation.md). +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/extensions/architecture/extendability.md b/guides/development/extensions/architecture/extendability.md index db018c7a45..cb0760589b 100644 --- a/guides/development/extensions/architecture/extendability.md +++ b/guides/development/extensions/architecture/extendability.md @@ -69,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/monetization/index.md b/guides/development/monetization/index.md index ad3af3a746..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](../../development/testing/store/store-review-errors.md). +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/unit/jest-storefront.md b/guides/development/testing/unit/jest-storefront.md index 1c920389b3..22c7ed47ee 100644 --- a/guides/development/testing/unit/jest-storefront.md +++ b/guides/development/testing/unit/jest-storefront.md @@ -51,7 +51,7 @@ Please note that in this example, `<environment>` 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/hosting/infrastructure/elasticsearch/elasticsearch-debugging.md b/guides/hosting/infrastructure/elasticsearch/elasticsearch-debugging.md index 6f737dc2da..e3dcce49b6 100644 --- a/guides/hosting/infrastructure/elasticsearch/elasticsearch-debugging.md +++ b/guides/hosting/infrastructure/elasticsearch/elasticsearch-debugging.md @@ -11,7 +11,7 @@ nav: 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](./elasticsearch-debugging) is activated in your *.env* file. +Ensure that the Debug-Mode is activated in your *.env* file. ## Shopware 6 CLI commands diff --git a/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md b/guides/hosting/infrastructure/elasticsearch/elasticsearch-setup.md index c6b8bb37e9..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. @@ -167,7 +167,7 @@ For additional support with common Elasticsearch errors and more tips please ref ### 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/guides/hosting/infrastructure/reverse-http-cache.md b/guides/hosting/infrastructure/reverse-http-cache.md index 477aac2109..7980d53580 100644 --- a/guides/hosting/infrastructure/reverse-http-cache.md +++ b/guides/hosting/infrastructure/reverse-http-cache.md @@ -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/installation-updates/deployments/build-w-o-db.md b/guides/hosting/installation-updates/deployments/build-w-o-db.md index e977fc14fd..78e1848824 100644 --- a/guides/hosting/installation-updates/deployments/build-w-o-db.md +++ b/guides/hosting/installation-updates/deployments/build-w-o-db.md @@ -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 8c5aac0c12..cb64d806a2 100644 --- a/guides/hosting/installation-updates/deployments/deployment-with-deployer.md +++ b/guides/hosting/installation-updates/deployments/deployment-with-deployer.md @@ -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/performing-updates.md b/guides/hosting/installation-updates/performing-updates.md index 3242bab8bb..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/system-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 3f98ce7162..b575e41069 100644 --- a/guides/hosting/performance/lock-store.md +++ b/guides/hosting/performance/lock-store.md @@ -12,7 +12,7 @@ By default, Symfony will use a local lock store. This means in multi-machine (cl ## 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/guides/hosting/performance/performance.md b/guides/hosting/performance/performance.md index 7158d318d1..8d58c43918 100644 --- a/guides/hosting/performance/performance.md +++ b/guides/hosting/performance/performance.md @@ -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 937a3c6cd3..2627c3d0bd 100644 --- a/guides/installation/legacy-setups/devenv-setup.md +++ b/guides/installation/legacy-setups/devenv-setup.md @@ -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/plugins/apps/administration/add-cms-element-via-admin-sdk.md b/guides/plugins/apps/administration/add-cms-element-via-admin-sdk.md index c405597a02..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 @@ -16,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. @@ -147,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`. @@ -368,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: + `<app-name>/Resources/views/storefront/element/<elementname>.html.twig` -For more details, see the guide on [CMS element development for plugins](../../plugins/content/cms/add-cms-element#storefront-implementation). -Below is an example of how your storefront template +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 c5d0b5bb9d..f6549d4436 100644 --- a/guides/plugins/apps/administration/add-custom-action-button.md +++ b/guides/plugins/apps/administration/add-custom-action-button.md @@ -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/app-scripts/add-api-endpoint.md b/guides/plugins/apps/app-scripts/add-api-endpoint.md index f9647f5e70..3c7b3f13bd 100644 --- a/guides/plugins/apps/app-scripts/add-api-endpoint.md +++ b/guides/plugins/apps/app-scripts/add-api-endpoint.md @@ -8,7 +8,7 @@ nav: # Add an API Endpoint ::: info -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 @@ -26,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 @@ -74,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: @@ -88,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 @@ -131,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. @@ -225,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: @@ -327,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 939a877a3d..38361fee09 100644 --- a/guides/plugins/apps/app-scripts/cart-manipulation.md +++ b/guides/plugins/apps/app-scripts/cart-manipulation.md @@ -9,7 +9,7 @@ nav: ## Overview -If your app needs to modify the cart, you can use the [`cart`](../../../../resources/references/app-reference/script-reference/script-hooks-reference#cart) script hook. App scripts extend the general [cart concept](../../../../concepts/commerce/checkout-concept/cart) by acting as another [cart processor](../../../../concepts/commerce/checkout-concept/cart#cart-processors---price-calculation-and-validation). +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. @@ -17,11 +17,11 @@ Note that app scripts were introduced in Shopware 6.4.8.0 and are not supported 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. -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#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 @@ -38,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. @@ -92,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 @@ -151,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/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/content/cms/add-custom-cms-blocks.md b/guides/plugins/apps/content/cms/add-custom-cms-blocks.md index 71c84de90f..f28cafc734 100644 --- a/guides/plugins/apps/content/cms/add-custom-cms-blocks.md +++ b/guides/plugins/apps/content/cms/add-custom-cms-blocks.md @@ -13,19 +13,19 @@ This functionality is available starting with Shopware 6.4.4.0. ## Overview -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. +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: -<PageRef page="../../../../../concepts/commerce/content/shopping-experiences-cms" /> +<PageRef page="../../../../../concepts/commerce/content/shopping-experiences-cms.md" /> ## 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. ## 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). 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.md). Custom CMS blocks are added by providing a `cms.xml` in the `Resources/` directory of your app. The basic directory structure looks as follows: @@ -114,7 +114,7 @@ Let's have a look at how to configure a CMS block from your app's `cms.xml`: `<name>` : A **unique** technical name for your block. -`<category>` : Blocks are divided into categories. Available categories can be found in the [plugin guide](../../../plugins/content/cms/add-cms-block#custom-block-in-the-administration). +`<category>` : Blocks are divided into categories. Available categories can be found in the [plugin guide](../../../plugins/content/cms/add-cms-block.md#how-to-create-a-block-in-the-administration). `<label>` : The **translatable** label will be shown in the Administration. @@ -124,7 +124,7 @@ Let's have a look at how to configure a CMS block from your app's `cms.xml`: The full CMS reference is available here: -<PageRef page="../../../../../resources/references/app-reference/cms-reference" /> +<PageRef page="../../../../../resources/references/app-reference/cms-reference.md" /> ### Block preview @@ -213,7 +213,7 @@ Unlike adding blocks from a plugin, blocks provided from an app will be automati ## Storefront representation -Providing the Storefront representation of your blocks works very similarly to the [plugin example](../../../plugins/content/cms/add-cms-block#storefront-representation). +Providing the Storefront representation of your blocks works very similarly to the [plugin example](../cms/add-custom-cms-blocks.md#storefront-representation). In `Resources/views/storefront/block/`, a Twig template matching the pattern `cms-block-${block.name}-component.html.twig` is expected. So in this example, it's sufficient to simply extend the existing `image-text` element: @@ -227,4 +227,4 @@ Styling of your blocks in the Storefront can then be done in `Resources/app/stor ## Further reading -You can further take a look at the [CMS references](../../../../../resources/references/app-reference/cms-reference). +You can further take a look at the [CMS references](../../../../../resources/references/app-reference/cms-reference.md). diff --git a/guides/plugins/apps/custom-data/custom-entities.md b/guides/plugins/apps/custom-data/custom-entities.md index 1ea10e714b..1163cb7af8 100644 --- a/guides/plugins/apps/custom-data/custom-entities.md +++ b/guides/plugins/apps/custom-data/custom-entities.md @@ -9,7 +9,7 @@ nav: ## Overview -In addition to [Custom fields](custom-fields), you can define entirely new entities in the system, called custom entities. Unlike [Custom fields](custom-fields), custom entities let you model fully customized data structures and relationships. These entities can then be managed directly in the Administration. +In addition to [Custom fields](custom-fields.md), you can define entirely new entities in the system, called custom entities. Unlike custom fields, custom entities let you model fully customized data structures and relationships. These entities can then be managed directly in the Administration. To use custom entities, register them in your app's `Resources/entities.xml` file: @@ -27,17 +27,17 @@ To use custom entities, register them in your app's `Resources/entities.xml` fil </entities> ``` -For a complete reference of the structure of the entities file take a look at the [Custom entity xml reference](../../../../resources/references/app-reference/entities-reference). +For a complete reference of the structure of the entities file take a look at the [Custom entity xml reference](../../../../resources/references/app-reference/entities-reference.md). ## Functionality -All registered entities will get an automatically registered repository. It is also available in the [App scripts](../app-scripts/) section, in case you are allowed to access the repository service inside the hook. +All registered entities will get an automatically registered repository. It is also available in the [App scripts](../app-scripts/index.md) section, in case you are allowed to access the repository service inside the hook. ```twig {% set blogs = services.repository.search('custom_entity_blog', criteria) %} ``` -Additionally, to the repository you can also access your custom entities via [Admin api](../../../../concepts/api/admin-api). +Additionally, to the repository you can also access your custom entities via [Admin API](../../../../concepts/api/admin-api.md). ```bash POST /api/search/custom-entity-blog @@ -81,7 +81,7 @@ Now you will find your entity in the "Entity Type" select when creating a custom ## Permissions Unlike core entities, your app directly has full access rights to your own custom entities. However, if your entity has associations that reference core tables, -you need the appropriate [permissions](../../../../resources/references/app-reference/manifest-reference) to load and write these associations. +you need the appropriate [permissions](../../../../resources/references/app-reference/manifest-reference.md) to load and write these associations. ```xml <?xml version="1.0" encoding="UTF-8"?> diff --git a/guides/plugins/apps/custom-data/custom-fields.md b/guides/plugins/apps/custom-data/custom-fields.md index e9d0bd0a0e..0102c5531b 100644 --- a/guides/plugins/apps/custom-data/custom-fields.md +++ b/guides/plugins/apps/custom-data/custom-fields.md @@ -15,9 +15,9 @@ To make use of the custom fields, register your custom field sets in your manife <<< @/docs/snippets/config/app/custom-fields-simple.xml -For a complete reference of the structure of the manifest file, take a look at the [Manifest reference](../../../../resources/references/app-reference/manifest-reference). +For a complete reference of the structure of the manifest file, take a look at the [Manifest reference](../../../../resources/references/app-reference/manifest-reference.md). -For the data needed, please refer to the custom fields in general: At first, you need a custom field set, as [custom fields](../../plugins/framework/custom-field/) in Shopware are organised in sets. Here you need to consider some important fields: +For the data needed, please refer to the custom fields in general: At first, you need a custom field set, as [custom fields](../../plugins/framework/custom-field/index.md) in Shopware are organised in sets. Here you need to consider some important fields: * `name`: A technical name for your set * `label`: This element provides the label of the text and can be used for defining translations of the label as well. @@ -43,4 +43,4 @@ When defining custom fields in the `<fields>` element, you can configure additio </float> ``` -Refer to the [custom field](../../plugins/framework/custom-field/) documentation for further details. +Refer to the [custom field](../../plugins/framework/custom-field/index.md) documentation for further details. diff --git a/guides/plugins/apps/flow-builder/add-custom-flow-actions-from-app-system.md b/guides/plugins/apps/flow-builder/add-custom-flow-actions-from-app-system.md index c3afd101a2..29245f36da 100644 --- a/guides/plugins/apps/flow-builder/add-custom-flow-actions-from-app-system.md +++ b/guides/plugins/apps/flow-builder/add-custom-flow-actions-from-app-system.md @@ -1,11 +1,11 @@ --- nav: - title: Add custom flow action from app system + title: Add Custom Flow Action from App System position: 10 --- -# Add custom flow actions +# Add Custom Flow Actions ::: info Custom flow actions in Shopware Apps are available starting with Shopware 6.4.10.0 and are not supported in previous versions. @@ -27,7 +27,7 @@ After reading, you will be able to Please make sure you already have a working Shopware 6 store running (either cloud or self-hosted). Prior knowledge about the Flow Builder feature of Shopware 6 is useful. -Please see the [Flow Builder Concept](../../../../concepts/framework/flow-concept) for more information. +Please see the [Flow Builder Concept](../../../../concepts/framework/flow-concept.md) for more information. ## Create the app wrapper @@ -260,7 +260,7 @@ Available input field attributes: You assemble your configuration from a variety of input fields. ::: info -To get more information on how to create configuration forms, see [Plugin Configurations](../../plugins/plugin-fundamentals/add-plugin-configuration#the-different-types-of-input-field). +To get more information on how to create configuration forms, see [Plugin Configurations](../../plugins/plugin-fundamentals/add-plugin-configuration.md#the-different-types-of-input-field). ::: | Type | Shopware component | @@ -291,5 +291,5 @@ bin/console app:install --activate FlowBuilderActionApp ## Further steps -* [Flow action example configuration](../../../../resources/references/app-reference/flow-action-reference) page +* [Flow action example configuration](../../../../resources/references/app-reference/flow-action-reference.md) page * [Schema definition for flow actions (GitHub)](https://github.com/shopware/shopware/blob/trunk/src/Core/Framework/App/Flow/Schema/flow-1.0.xsd)` diff --git a/guides/plugins/apps/flow-builder/add-custom-flow-triggers-from-app-system.md b/guides/plugins/apps/flow-builder/add-custom-flow-triggers-from-app-system.md index b5d14004e2..22f3f298e2 100644 --- a/guides/plugins/apps/flow-builder/add-custom-flow-triggers-from-app-system.md +++ b/guides/plugins/apps/flow-builder/add-custom-flow-triggers-from-app-system.md @@ -27,7 +27,7 @@ After reading, you will be able to : Please ensure you have a working Shopware 6 store (either cloud or self-hosted). Prior knowledge about the Flow Builder feature of Shopware 6 is useful. -Please see the [Flow Builder Concept](../../../../concepts/framework/flow-concept) for more information. +Please see the [Flow Builder Concept](../../../../concepts/framework//flow-concept.md) for more information. ## Create the app wrapper @@ -196,11 +196,11 @@ Or we can use the data when defining the email template. <h1>Visit us at: {{ url }} </h1> ``` -Please see the [StorableFlow Concept](../../../../resources/references/adr/2022-07-21-adding-the-storable-flow-to-implement-delay-action-in-flow-builder) for more information. +Please see the [StorableFlow Concept](../../../../resources/references/adr/2022-07-21-adding-the-storable-flow-to-implement-delay-action-in-flow-builder.md) for more information. ## Snippet for translation -You can define snippets to translate your custom trigger to show the trigger tree and flow list. Refer to the [Adding snippets](../../plugins/administration/templates-styling/adding-snippets) guide for more information. +You can define snippets to translate your custom trigger to show the trigger tree and flow list. Refer to the [Adding snippets](../../plugins/administration/templates-styling/adding-snippets.md) guide for more information. Snippet keys should be defined based on your trigger name defined at `<name>` in your `flow.xml`. diff --git a/guides/plugins/apps/lifecycle/product-translator.md b/guides/plugins/apps/lifecycle/product-translator.md index 7d855a5590..c6d4f4ec4a 100644 --- a/guides/plugins/apps/lifecycle/product-translator.md +++ b/guides/plugins/apps/lifecycle/product-translator.md @@ -15,7 +15,7 @@ You will learn how to read and write data to the Shopware Admin API using an exa ## Prerequisites * Basic CLI usage (creating files, directories, running commands) -* Installed [shopware-cli](../../../../products/cli/) tools +* Installed [shopware-cli](../../../../products/cli/index.md) tools * Installed [symfony-cli](https://symfony.com/download) * A running MariaDB or MySQL accessible to your development machine diff --git a/guides/plugins/apps/lifecycle/webhook.md b/guides/plugins/apps/lifecycle/webhook.md index 65a125997e..7233385a4f 100644 --- a/guides/plugins/apps/lifecycle/webhook.md +++ b/guides/plugins/apps/lifecycle/webhook.md @@ -122,7 +122,7 @@ Starting from Shopware version 6.4.5.0, the current language ID of the shopware You can verify the authenticity of the incoming request by checking the `shopware-shop-signature`. Every request should have a SHA256 HMAC of the request body that is signed with the secret your app assigned the shop during the [registration](app-registration-setup.md#setup). The mechanism to verify the request is exactly the same as the one used for the [confirmation request](app-registration-setup.md#confirmation-request). -You can use a variety of events to react to changes in Shopware that way. See the[Webhook-Events-Reference](../../../../resources/references/app-reference/webhook-events-reference.md) for an overview. +You can use a variety of events to react to changes in Shopware that way. See the [Webhook-Events-Reference](../../../../resources/references/app-reference/webhook-events-reference.md) for an overview. ## Webhooks for live version only diff --git a/guides/plugins/apps/rule-builder/add-custom-rule-conditions.md b/guides/plugins/apps/rule-builder/add-custom-rule-conditions.md index f4681791a8..0a079326f0 100644 --- a/guides/plugins/apps/rule-builder/add-custom-rule-conditions.md +++ b/guides/plugins/apps/rule-builder/add-custom-rule-conditions.md @@ -19,15 +19,15 @@ Note that app rule conditions were introduced in Shopware 6.4.12.0, and are not If you're not familiar with the app system, please take a look at the concept first. -<PageRef page="../../../../concepts/extensions/apps-concept" /> +<PageRef page="../../../../concepts/extensions/apps-concept.md" /> You should also be familiar with the general concept of the Rule Builder. -<PageRef page="../../../../concepts/framework/rule-system/index" /> +<PageRef page="../../../../concepts/framework/rule-system/index.md" /> For the attached logic of your custom conditions, you'll use [Twig files](https://twig.symfony.com/). Please refer to the App Scripts guide for a general introduction. -<PageRef page="../app-scripts/index" /> +<PageRef page="../app-scripts/index.md" /> ## Definition @@ -47,7 +47,7 @@ The following fields are required: Constraints are optional and may be used to define fields, whose purpose is to provide data for use within the condition's script. -Constraints are a collection of [custom fields](../custom-data/index.md), which allows you to provide a variety of different fields for setting parameters within the administration. Fields may be marked as `required`. The `name` attribute of the field is also the variable the field's value will be exposed as within the condition's script. So it is advisable to use a variable-friendly name and to use unique names within the confines of a single condition. +Constraints are a collection of [custom fields](../custom-data/custom-fields.md), which allows you to provide a variety of different fields for setting parameters within the administration. Fields may be marked as `required`. The `name` attribute of the field is also the variable the field's value will be exposed as within the condition's script. So it is advisable to use a variable-friendly name and to use unique names within the confines of a single condition. The above example will add the condition shown below for selection in the Administration: @@ -67,7 +67,7 @@ The corresponding scripts to the defined conditions within `manifest.xml` need t └── manifest.xml ``` -Scripts for rule conditions are [twig files](https://twig.symfony.com/) that are executed in a sandboxed environment. They offer the same extended syntax and debugging options as [App Scripts](../app-scripts/). +Scripts for rule conditions are [Twig files](https://twig.symfony.com/) that are executed in a sandboxed environment. They offer the same extended syntax and debugging options as [App Scripts](../app-scripts/index.md). Within the script you will have access to the `scope` variable which is an instance of `RuleScope` as described in the [Rule Builder concept](../../../../concepts/framework/rule-system/index.md). The scope instance provides you with the current `SalesChannelContext` and, given the right scope, the current cart. Further available variables depend on the existence of constraints within the definition of your conditions. diff --git a/guides/plugins/apps/storefront/apps-as-themes.md b/guides/plugins/apps/storefront/apps-as-themes.md index 0b31635fbc..c2d32210be 100644 --- a/guides/plugins/apps/storefront/apps-as-themes.md +++ b/guides/plugins/apps/storefront/apps-as-themes.md @@ -7,7 +7,7 @@ nav: # Apps as Themes -To ship whole [themes](../../themes/) inside an app, just include the theme configuration as a [theme.json](../../../plugins/themes/configuration/theme-configuration.md) file inside your app's `Resources` folder. The folder structure of a theme may look like this: +To ship whole [themes](../../themes/index.md) inside an app, just include the theme configuration as a [theme.json](../../../plugins/themes/configuration/theme-configuration.md) file inside your app's `Resources` folder. The folder structure of a theme may look like this: ```text └── DemoTheme diff --git a/guides/plugins/apps/storefront/cookies-with-apps.md b/guides/plugins/apps/storefront/cookies-with-apps.md index 25a93e4921..a089f0998b 100644 --- a/guides/plugins/apps/storefront/cookies-with-apps.md +++ b/guides/plugins/apps/storefront/cookies-with-apps.md @@ -9,9 +9,9 @@ nav: ## Overview -Before proceeding, review the [app-base-guide](../app-base-guide.md). +Before proceeding, review the [App Base Guide](../app-base-guide.md). -The [Cookie Consent Management Concept](../../../../concepts/commerce/content/cookie-consent-management) provides a comprehensive guide to Shopware's cookie consent system. +The [Cookie Consent Management Concept](../../../../concepts/commerce/content/cookie-consent-management.md) provides a comprehensive guide to Shopware's cookie consent system. ## Create a single cookie @@ -45,7 +45,7 @@ Cookie elements can be configured by adding the following child elements: * `expiration` (optional): Cookie lifetime in days. **If unset, the cookie expires with the session.** * `snippet-description` (optional): A string that represents the description of the cookie in the cookie consent manager. To provide translations, this should be the key of a Storefront snippet. -For a complete reference of the structure of the manifest file, take a look at the [Manifest reference](../../../../resources/references/app-reference/manifest-reference). +For a complete reference of the structure of the manifest file, take a look at the [Manifest reference](../../../../resources/references/app-reference/manifest-reference.md). ## Create a cookie group @@ -140,7 +140,7 @@ To learn how to set up Storefront snippets, refer to the snippet guide. Any changes made to the cookie definitions in your app's `manifest.xml` are automatically detected by Shopware's consent system. This will trigger a re-consent flow for users, ensuring they are always prompted about the latest cookie settings. -This process is handled by a configuration hash mechanism, which is explained in detail in the [Cookie Consent Management Concept](../../../../concepts/commerce/content/cookie-consent-management#configuration-hash-mechanism). +This process is handled by a configuration hash mechanism, which is explained in detail in the [Cookie Consent Management Concept](../../../../concepts/commerce/content/cookie-consent-management.md#configuration-hash-mechanism). ## Reacting to cookie consent changes diff --git a/guides/plugins/apps/storefront/customize-templates.md b/guides/plugins/apps/storefront/customize-templates.md index 5e49d987cb..444990af21 100644 --- a/guides/plugins/apps/storefront/customize-templates.md +++ b/guides/plugins/apps/storefront/customize-templates.md @@ -15,12 +15,12 @@ This guide will cover customizing Storefront templates using an app. Before you begin, make sure you have: -* A basic understanding of [Shopware app development](../app-base-guide). +* A basic understanding of [Shopware app development](../app-base-guide.md). * Familiarity with the [Twig template](https://twig.symfony.com/) is beneficial. ## Getting started -This guide assumes you have already set up your Shopware app. If not, refer to the [app base guide](../app-base-guide) for the initial setup. +This guide assumes you have already set up your Shopware app. If not, refer to the [app base guide](../app-base-guide.md) for the initial setup. The following sections give you a very short example of how you can extend a storefront block. For simplicity's sake, only the page logo is replaced with a 'Hello world!' text. @@ -33,7 +33,7 @@ First of all, in your app's root, register your app's own view path, which basic As mentioned earlier, this guide is only trying to replace the 'demo' logo with a 'Hello world!' text. In order to find the proper template, you can simply search for the term 'logo' inside the `<shopware root>/src/Storefront` directory. This will eventually lead you to [this file](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Storefront/Resources/views/storefront/layout/header/logo.html.twig). ::: info -There's a plugin out there called [FroshDevelopmentHelper](https://github.com/FriendsOfShopware/FroshDevelopmentHelper), that adds hints about template blocks and includes into the rendered HTML. This way, it's easier to actually find the proper template. +The [FroshDevelopmentHelper](https://github.com/FriendsOfShopware/FroshDevelopmentHelper) plugin adds hints about template blocks and includes into the rendered HTML. This way, it's easier to actually find the proper template. ::: ### Overriding the template @@ -95,5 +95,5 @@ But how do you know which variables are available to use? For this, you can just This `dump()` call will print out all variables available on this page. ::: info -Once again, the plugin called [FroshDevelopmentHelper](https://github.com/FriendsOfShopware/FroshDevelopmentHelper) adds all available page data to the Twig tab in the profiler, when opening a request and its details. This might help here as well. +[FroshDevelopmentHelper](https://github.com/FriendsOfShopware/FroshDevelopmentHelper) adds all available page data to the Twig tab in the profiler when opening a request, and its details as well. This might help here as well. ::: diff --git a/guides/plugins/plugins/administration/data-handling-processing/using-data-handling.md b/guides/plugins/plugins/administration/data-handling-processing/using-data-handling.md index c2a34f65c6..48f5050a63 100644 --- a/guides/plugins/plugins/administration/data-handling-processing/using-data-handling.md +++ b/guides/plugins/plugins/administration/data-handling-processing/using-data-handling.md @@ -23,7 +23,7 @@ Considering that the data handling in the Administration is remotely operating t ## The repository service -Accessing the Shopware API in the Administration is done by using the repository service, which can be injected with a [bottleJs](https://github.com/young-steveo/bottlejs) dependency injection container. In the Shopware Administration, there's a wrapper that makes `bottleJs` work with the [inject / provide](https://vuejs.org/v2/api/#provide-inject) from [`Vue`](https://vuejs.org/). In short: You can use the `inject` key in your component configuration to fetch services from the `bottleJs` DI container, such as the `repositoryFactory`, that you will need in order to get a repository for a single entity. +Accessing the Shopware API in the Administration is done by using the repository service, which can be injected with a [BottleJS](https://github.com/young-steveo/bottlejs) dependency injection container. In the Shopware Administration, there's a wrapper that makes `bottleJs` work with the [inject / provide](https://vuejs.org/v2/api/#provide-inject) from [`Vue`](https://vuejs.org/). In short: You can use the `inject` key in your component configuration to fetch services from the `bottleJs` DI container, such as the `repositoryFactory`, that you will need in order to get a repository for a single entity. Add those lines to your component configuration: @@ -879,4 +879,4 @@ Component.extend('swag-paypal-pos-wizard', 'sw-first-run-wizard-modal', { ## Next steps -As this is very similar to the DAL it might be interesting to learn more about that. For this, head over to the section about the [data handling](../../../../../guides/plugins/plugins/framework/data-handling/) in PHP. +As this is very similar to the DAL it might be interesting to learn more about that. For this, head over to the section about the [data handling](../../../../../guides/plugins/plugins/framework/data-handling/index.md) in PHP. diff --git a/guides/plugins/plugins/administration/data-handling-processing/using-the-data-grid-component.md b/guides/plugins/plugins/administration/data-handling-processing/using-the-data-grid-component.md index e5ee60fa90..8372f9274e 100644 --- a/guides/plugins/plugins/administration/data-handling-processing/using-the-data-grid-component.md +++ b/guides/plugins/plugins/administration/data-handling-processing/using-the-data-grid-component.md @@ -31,7 +31,7 @@ This template will be used in a new component. Learn how to override existing co ## Declaring the data -Since this is a very basic example the following code will just statically assign data to the `dataSource` and `columns` data attribute. If you want to load data and render that instead, please consult the guide [How to use the data handling](using-data-handling.md) +Since this is a very basic example the following code will just statically assign data to the `dataSource` and `columns` data attribute. If you want to load data and render that instead, please consult the [How to use the data handling guide](using-data-handling.md). ```javascript // <plugin-root>/src/Resources/app/administration/app/src/component/swag-example/index.js diff --git a/guides/plugins/plugins/administration/module-component-management/index.md b/guides/plugins/plugins/administration/module-component-management/index.md index 71f992be3d..2229f6bd7e 100644 --- a/guides/plugins/plugins/administration/module-component-management/index.md +++ b/guides/plugins/plugins/administration/module-component-management/index.md @@ -8,14 +8,9 @@ nav: This guide covers how to create, extend, and customize Administration modules and Vue components. Use them to: -- Create custom modules and routes -- Register and build custom components -- Override or extend existing components -- Work with base components and input fields - -- [Add Custom Field](./add-custom-field) -- [Add Custom Component](./add-custom-component) -- [Add Custom Module](./add-custom-module) -- [Customizing Components](./customizing-components) -- [Customizing Modules](./customizing-modules) -- [Using Base Components](./using-base-components) +* [Add Custom Fields](add-custom-field.md) +* [Add Custom Components](add-custom-component.md) +* [Add Custom Modules](add-custom-module.md) +* [Customize Components](customizing-components.md) +* [Customize Modules](customizing-modules.md) +* [Use Base Components](using-base-components.md) diff --git a/guides/plugins/plugins/administration/module-component-management/using-base-components.md b/guides/plugins/plugins/administration/module-component-management/using-base-components.md index 1c7c73d63d..34e231abb0 100644 --- a/guides/plugins/plugins/administration/module-component-management/using-base-components.md +++ b/guides/plugins/plugins/administration/module-component-management/using-base-components.md @@ -32,4 +32,4 @@ Using base components in your own Administration templates is rather simple. In </div> ``` -That's basically it. To continue building beautiful custom components, learn how to write templates and how to include them in your components [here](../templates-styling/writing-templates.md) +That's basically it. To continue building beautiful custom components, learn how to write templates and how to include them in your components [here](../templates-styling/writing-templates.md). diff --git a/guides/plugins/plugins/administration/permissions-error-handling/add-acl-rules.md b/guides/plugins/plugins/administration/permissions-error-handling/add-acl-rules.md index 7bdb353f44..83c4e1551d 100644 --- a/guides/plugins/plugins/administration/permissions-error-handling/add-acl-rules.md +++ b/guides/plugins/plugins/administration/permissions-error-handling/add-acl-rules.md @@ -26,7 +26,7 @@ Note: ACL Rules in the Administration can be circumnavigated by making direct AP ## Prerequisites -All you need for this guide is a running Shopware 6 instance and full access to both the files and a running plugin. A basic understanding of the [vue router](https://router.vuejs.org/) is also required. Of course you'll have to understand JavaScript, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation. +All you need for this guide is a running Shopware 6 instance and full access to both the files and a running plugin. A basic understanding of the [Vue router](https://router.vuejs.org/) is also required. Of course you'll have to understand JavaScript, but that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation. ## Admin privileges diff --git a/guides/plugins/plugins/administration/routing-navigation/overriding-routes.md b/guides/plugins/plugins/administration/routing-navigation/overriding-routes.md index 0cfbfc19c7..18b3a01750 100644 --- a/guides/plugins/plugins/administration/routing-navigation/overriding-routes.md +++ b/guides/plugins/plugins/administration/routing-navigation/overriding-routes.md @@ -9,13 +9,13 @@ nav: ## Overview -In the `Administration` core code, each module is defined in a directory called `module`. Modules define routes which can be extended with `routeMiddleware`. To see what else you can customize in existing modules, have a look at this [guide](../module-component-management/customizing-modules.md) +In the `Administration` core code, each module is defined in a directory called `module`. Modules define routes which can be extended with `routeMiddleware`. To see what else you can customize in existing modules, have a look at this [guide](../module-component-management/customizing-modules.md). A `module` is an encapsulated unit which implements a whole feature. For example there are modules for customers, orders, settings, etc. ## Prerequisites -All you need for this guide is a running Shopware 6 instance. Of course, you'll have to understand JavaScript and have a basic familiarity with [Vue](https://vuejs.org/) and the [Vue Router](https://router.vuejs.org/). However, that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation. Further a basic understanding of what modules are is also required, learn more about them [here](../module-component-management/add-custom-module.md) +All you need for this guide is a running Shopware 6 instance. Of course, you'll have to understand JavaScript and have a basic familiarity with [Vue](https://vuejs.org/) and the [Vue Router](https://router.vuejs.org/). However, that's a prerequisite for Shopware as a whole and will not be taught as part of this documentation. Further a basic understanding of what modules are is also required, learn more about them [here](../module-component-management/add-custom-module.md). ## Applying the override @@ -48,4 +48,4 @@ Module.register('my-new-custom-route', { This `routeMiddleware` changes the required privileges for the `sw.product.detail.base` route from `product.viewer` to `product.editor`. The rest of the route configurations stays the same in this example. -If you want to learn more about ACL take a look at this [guide](../permissions-error-handling/add-acl-rules.md) and if you want to learn everything about Administration routes, head over to this [guide](../routing-navigation/add-custom-route.md) +If you want to learn more about ACL take a look at this [guide](../permissions-error-handling/add-acl-rules.md) and if you want to learn everything about Administration routes, head over to this [guide](../routing-navigation/add-custom-route.md). diff --git a/guides/plugins/plugins/administration/services-utilities/injecting-services.md b/guides/plugins/plugins/administration/services-utilities/injecting-services.md index 54512b8f9a..f6e2d58a62 100644 --- a/guides/plugins/plugins/administration/services-utilities/injecting-services.md +++ b/guides/plugins/plugins/administration/services-utilities/injecting-services.md @@ -21,7 +21,7 @@ Of course you'll have to understand JavaScript, but that's a prerequisite for Sh ## Definition of an Administration service -Shopware 6 uses [bottleJS](https://github.com/young-steveo/bottlejs) to inject services. +Shopware 6 uses [BottleJS](https://github.com/young-steveo/bottlejs) to inject services. Services are small self-contained utility classes, like the [repositoryFactory](https://github.com/shopware/shopware/blob/v6.3.4.1/src/Administration/Resources/app/administration/src/core/data-new/repository-factory.data.js), which provides a way to talk to the API. ## Injection of a service diff --git a/guides/plugins/plugins/administration/services-utilities/making-api-requests.md b/guides/plugins/plugins/administration/services-utilities/making-api-requests.md index f4287bf984..d16c607c1c 100644 --- a/guides/plugins/plugins/administration/services-utilities/making-api-requests.md +++ b/guides/plugins/plugins/administration/services-utilities/making-api-requests.md @@ -15,7 +15,7 @@ In this guide you'll learn how to create a custom API service in your plugin's a In order to add your own custom API service for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../../plugin-base-guide). -You also need to have a custom administration module or component. Refer to [Add custom module](../module-component-management/add-custom-module) to get started. +You also need to have a custom administration module or component. Refer to [Add custom module](../module-component-management/add-custom-module.md) to get started. ## Creating the API service @@ -320,4 +320,4 @@ Now that you've created your API service, you might want to: - Implement caching strategies for better performance - Add request interceptors for global error handling -For more information on creating backend API endpoints, refer to the [API documentation](../../../../../concepts/api/). +For more information on creating backend API endpoints, refer to the [API documentation](../../../../../concepts/api/index.md). diff --git a/guides/plugins/plugins/checkout/cart/add-cart-processor-collector.md b/guides/plugins/plugins/checkout/cart/add-cart-processor-collector.md index 5b331b3dd5..35195d91ac 100644 --- a/guides/plugins/plugins/checkout/cart/add-cart-processor-collector.md +++ b/guides/plugins/plugins/checkout/cart/add-cart-processor-collector.md @@ -107,4 +107,4 @@ Your processor has to be defined in the service container using the tag `shopwar ## Next steps If you want to see a better example on what can be done with a collector and a processor, you might want to have a look at our guide -regarding [Changing the price of an item in the cart](./change-price-of-item). +regarding [Changing the price of an item in the cart](./change-price-of-item.md). diff --git a/guides/plugins/plugins/checkout/cart/customize-price-calculation.md b/guides/plugins/plugins/checkout/cart/customize-price-calculation.md index 2827007607..9cc6670ecc 100644 --- a/guides/plugins/plugins/checkout/cart/customize-price-calculation.md +++ b/guides/plugins/plugins/checkout/cart/customize-price-calculation.md @@ -13,7 +13,7 @@ This guide explains how to globally adjust the calculation of product prices by ## Prerequisites -Review the [plugin base guide](../../plugin-base-guide) and the guide on [adjusting a service](../../services/adjusting-service.md) for guidance on service decoration. +Review the [plugin base guide](../../plugin-base-guide.md) and the guide on [adjusting a service](../../services/adjusting-service.md) for guidance on service decoration. ## Decorating the calculator @@ -100,4 +100,4 @@ return static function (ContainerConfigurator $configurator): void { ## Next steps -Instead of manipulating a product's price, you can also try to add a discount or a surcharge to the cart. This is explained in our guide about [adding cart discounts](add-cart-discounts). +Instead of manipulating a product's price, you can also try to add a discount or a surcharge to the cart. This is explained in our guide about [adding cart discounts](add-cart-discounts.md). diff --git a/guides/plugins/plugins/content/cms/add-cms-block.md b/guides/plugins/plugins/content/cms/add-cms-block.md index fd4a5a726f..5519891b6a 100644 --- a/guides/plugins/plugins/content/cms/add-cms-block.md +++ b/guides/plugins/plugins/content/cms/add-cms-block.md @@ -22,7 +22,7 @@ A block represents a reusable layout unit that defines how elements are arranged **Key concept**: Blocks define the structure (layout and slots), while elements provide the actual content. This separation allows the same block to display different types of content in its slots. -> **Learn more**: For a deeper understanding of the CMS architecture, see the [Shopping Experience fundamental guide](https://developer.shopware.com/docs/concepts/commerce/content/shopping-experiences-cms.html). +> **Learn more**: For a deeper understanding of the CMS architecture, see the [Shopping Experience fundamental guide](../../../../../concepts/commerce/content/shopping-experiences-cms.md). ## Where to Find Blocks @@ -223,4 +223,4 @@ This dynamically builds the template path based on the element type. For example ## Next steps -Now you've got your very own CMS block running, what about a custom CMS element? Head over to our guide, which will explain exactly that: [Creating a custom CMS element](add-cms-element) +Now you've got your very own CMS block running, what about a custom CMS element? Head over to our guide, which will explain exactly that: [Creating a custom CMS element](add-cms-element.md). diff --git a/guides/plugins/plugins/content/cms/add-cms-element.md b/guides/plugins/plugins/content/cms/add-cms-element.md index 0c0bdc515c..0ea40ca344 100644 --- a/guides/plugins/plugins/content/cms/add-cms-element.md +++ b/guides/plugins/plugins/content/cms/add-cms-element.md @@ -1,6 +1,6 @@ --- nav: - title: Add CMS Element + title: Add CMS Elements position: 20 --- @@ -22,9 +22,9 @@ Elements are the "primitives" in the CMS hierarchy. They have no knowledge of th **Key concept**: Elements provide the actual content, while blocks define the structure and layout. This separation allows different element types to be placed in the same block slot. -> **Learn more**: For a deeper understanding of the CMS architecture, see the [Shopping Experience fundamental guide](https://developer.shopware.com/docs/concepts/commerce/content/shopping-experiences-cms.html). +> **Learn more**: For a deeper understanding of the CMS architecture, see the [Shopping Experience fundamental guide](../../../../../concepts/commerce/content/shopping-experiences-cms.md). -## Where to Find Elements +## Where to find elements Elements are added to blocks within the Shopping Experience module: @@ -41,7 +41,7 @@ You can find related element code here: * Storefront: `src/Storefront/Resources/views/storefront/element/` * Core: `\Shopware\Core\Content\Cms\SalesChannel\SalesChannelCmsPageLoader::load` -## How to Create an Element in the Administration +## How to create an element in the Administration We recommend this structure for CMS elements: @@ -66,14 +66,14 @@ We recommend this structure for CMS elements: └── cms-el-preview-dailymotion.scss ``` -### Step 1: Import Your Element in main.js +### Step 1: Import your element in main.js ```JS // <plugin root>/src/Resources/app/administration/src/main.js import './module/sw-cms/elements/dailymotion'; ``` -### Step 2: Register the Element +### Step 2: Register the element ```JS // <plugin root>/src/Resources/app/administration/src/module/sw-cms/elements/dailymotion/index.js @@ -107,7 +107,7 @@ Shopware.Service('cmsService').registerCmsElement({ | hidden | (Optional) Hides the element in the "replace element" modal | | removable | (Optional) Prevents the element from being removed from a slot via UI | -### Step 3: Create the Preview Component +### Step 3: Create the preview component The preview is shown as a thumbnail when selecting or swapping elements in block slots. You could also display a static image of your final Storefront element here. @@ -122,7 +122,7 @@ Shopware.Component.register('cms-el-preview-dailymotion', { }); ``` -### Step 4: Create the Main Component +### Step 4: Create the main component The main component is displayed in the editor layout. It should provide a good representation of the final Storefront element. @@ -158,7 +158,7 @@ Shopware.Component.register('cms-el-dailymotion', { * The `cms-element` mixin provides common props and data-mapping for config objects * Use fallback content to avoid invisible elements in the editor (for example when missing an `iframe` or `img` `src`) -### Step 5: Create the Configuration Component +### Step 5: Create the configuration component This component will be displayed in a modal and should provide form fields for all options defined in Step 2 (`defaultConfig`). @@ -184,9 +184,9 @@ Shopware.Component.register('cms-el-config-dailymotion', { **Key points**: * The `cms-element` mixin provides common props and data-mapping for config objects -* Use [Shopware meteor components](https://shopware.design/meteor-components/) for a consistent UI +* Use [Shopware Meteor components](https://shopware.design/meteor-components/) for a consistent UI -### Step 6: Inheritance Support For Elements +### Step 6: Inheritance support for elements Inheritance in the CMS provides fine-grained control over how content is customized between the base layout and content pages (category, product, landing page, ..) they are assigned to. Similar to how product variants work, content managers can choose to either inherit the content from the base layout or override it with custom content for each page. @@ -214,7 +214,7 @@ For an improved user experience when working with inherited fields, we provide a You can find more references in the standard CMS elements located in `src/Administration/Resources/app/administration/src/module/sw-cms/elements/`. -## How to Create an Element in the Storefront +## How to Create an element in the Storefront The Storefront template defines how your element appears on the actual storefront. It is expected to be located in the directory `src/Resources/views/storefront/element`. In there, a twig template file has to follow this naming convention: @@ -226,7 +226,7 @@ The Storefront template defines how your element appears on the actual storefron Full example: `cms-element-dailymotion.html.twig` -### Basic Template +### Basic template You can create your own elements or extend and reuse existing ones. Don't forget to clear the Storefront cache after adding new templates. @@ -250,4 +250,4 @@ The `element` is automatically passed to the template and contains meta data and There are many possibilities to extend Shopware's CMS. If you haven't done so already, consider using your element in a cms block. -To learn how to do this, take a look at the guide on [Add custom cms block](add-cms-block). +To learn how to do this, take a look at the guide on [Add custom CMS block](add-cms-block.md). diff --git a/guides/plugins/plugins/content/cms/add-data-to-cms-elements.md b/guides/plugins/plugins/content/cms/add-data-to-cms-elements.md index d7e9c7a8ee..7b57053968 100644 --- a/guides/plugins/plugins/content/cms/add-data-to-cms-elements.md +++ b/guides/plugins/plugins/content/cms/add-data-to-cms-elements.md @@ -16,7 +16,7 @@ In those cases you can implement a custom `CmsElementResolver` to resolve the co ## Prerequisites This guide will not explain how to create custom CMS elements in general, -so head over to the official guide about [Adding a custom CMS element](add-cms-element) to learn this first. +so head over to the official guide about [Adding a custom CMS element](add-cms-element.md) to learn this first. ## Create a data resolver @@ -56,7 +56,7 @@ class DailyMotionCmsElementResolver extends AbstractCmsElementResolver Our custom resolver extends from the `AbstractCmsElementResolver` which forces us to implement the methods `getType`, `collect` and `enrich`. -In the previous [example](add-cms-element) we added a CMS element with the name `dailymotion`. +In the previous [example](add-cms-element.md) we added a CMS element with the name `dailymotion`. As you can see the `getType` method of our custom resolver reflects that name by returning the `dailymotion` string. This resolver is called every time for an element of the type `dailymotion`. @@ -88,7 +88,7 @@ As in the following example, you can retrieve the configuration for the current In this case we read out `myCustomMedia` field which may contain a mediaId. If a `mediaId` exists, we create a new `CriteriaCollection` for it. Now we are able to use this media object later on. -If you want to add data from an [attribute entity](../../framework/data-handling/entities-via-attributes), you do not have an explicit definition class. +If you want to add data from an [attribute entity](../../framework/data-handling/entities-via-attributes.md), you do not have an explicit definition class. Instead, you pass `example_entity.definition` as second parameter to the `CriteriaCollection::add()` method. ::: code-group diff --git a/guides/plugins/plugins/content/media/add-custom-file-extension.md b/guides/plugins/plugins/content/media/add-custom-file-extension.md index 09ba451f2c..1d492a4105 100644 --- a/guides/plugins/plugins/content/media/add-custom-file-extension.md +++ b/guides/plugins/plugins/content/media/add-custom-file-extension.md @@ -15,7 +15,7 @@ Not all media types can be uploaded to Shopware with the Administration's Media Review these guides before proceeding: -- [Plugin base guide](../../plugin-base-guide) +- [Plugin base guide](../../plugin-base-guide.md) - [Dependency injection](../../services/dependency-injection.md), to learn how to add classes to the container - [Listen to events](../../framework/event/listening-to-events.md), for guidance on using subscribers diff --git a/guides/plugins/plugins/content/sitemap/add-custom-sitemap-entries.md b/guides/plugins/plugins/content/sitemap/add-custom-sitemap-entries.md index 0c0fd47dfb..0e8cc63004 100644 --- a/guides/plugins/plugins/content/sitemap/add-custom-sitemap-entries.md +++ b/guides/plugins/plugins/content/sitemap/add-custom-sitemap-entries.md @@ -1,6 +1,6 @@ --- nav: - title: Add custom sitemap entries + title: Add Custom Sitemap Entries position: 10 --- @@ -42,7 +42,7 @@ The `salesChannelId` is the ID of the sales channel you want to add the URL to. ### By adding a URL provider -This part of the guide is mainly built upon the guide about [Adding a custom SEO URL][dynamic-entity-seo], +This part of the guide is mainly built upon the guide about [Adding a custom SEO URL](../seo/add-custom-seo-url.md#dynamic-seo-urls-for-custom-content), so you might want to have a look at that. The said guide comes with a custom entity, a controller with a technical route to display each entity, and a custom SEO URL. All of this will be needed for this guide, as we're going to add the custom entity SEO URLs to the sitemap here. @@ -51,7 +51,7 @@ So let's get started. Adding custom URLs to the sitemap is done by adding a so-called "URL provider" to the system. This is done by adding a new class, which is extending from `Shopware\Core\Content\Sitemap\Provider\AbstractUrlProvider`. -It then has to be registered to the [service container][dependency-injection] using the tag +It then has to be registered to the [service container](../../services/dependency-injection.md) using the tag `shopware.sitemap_url_provider`. It has to provide three methods: @@ -201,7 +201,7 @@ Start by creating a new class `CustomUrlProvider`, which is extending from the ` Following are the constants `CHANGE_FREQ` and `priority` - you don't have to add those values as constants of course. They're going to be used later in the generation of the sitemap URLs. -Passed into the constructor are the repository for our [custom entity][custom-complex-data], +Passed into the constructor are the repository for our [custom entity](../../framework/data-handling/add-custom-complex-data.md), the DBAL connection used for actually fetching SEO URLs from the database, and the Symfony router to generate SEO URLs that have not yet been written to the database. @@ -212,7 +212,7 @@ of your entities. If there aren't any entities to be fetched, there is nothing more to be done here. Afterward we fetch all already existing SEO URLs for our custom entities. Once again, have a look at our guide about -[adding a custom SEO URL][dynamic-entity-seo] if you don't know how to add custom +[adding a custom SEO URL](../seo/add-custom-seo-url.md) if you don't know how to add custom SEO URLs in the first place. We're then iterating over all of our fetched entities, and we create an instance of `Shopware\Core\Content\Sitemap\Struct\Url` @@ -233,8 +233,3 @@ generating it on the fly. All of those instances are then stored in an array, which in return is passed to the `UrlResult`. This completes the implementation. Your custom URLs will now be included in the generated sitemap. - -[dynamic-entity-seo]: ../seo/add-custom-seo-url#dynamic-seo-urls-for-entities -[dependency-injection]: ../../services/dependency-injection.md -[custom-complex-data]: ../../framework/data-handling/add-custom-complex-data -[adjusting-services]: ../../plugin-fundamentals/adjusting-service diff --git a/guides/plugins/plugins/database/custom-fields-of-type-media.md b/guides/plugins/plugins/database/custom-fields-of-type-media.md index 5b2ff2b534..63374d4591 100644 --- a/guides/plugins/plugins/database/custom-fields-of-type-media.md +++ b/guides/plugins/plugins/database/custom-fields-of-type-media.md @@ -10,7 +10,7 @@ nav: After adding a custom field of type media in the Administration or via a plugin, you can assign media objects to different entities. This is often used on products to add additional images to the product detail page. -If you want to learn more about custom fields, take a look at [Adding custom fields](../framework/custom-field/add-custom-field). +If you want to learn more about custom fields, take a look at [Adding custom fields](../framework/custom-field/add-custom-field.md). ## Resolve media custom fields in Twig diff --git a/guides/plugins/plugins/database/database-migrations.md b/guides/plugins/plugins/database/database-migrations.md index b0def43530..05f349d57d 100644 --- a/guides/plugins/plugins/database/database-migrations.md +++ b/guides/plugins/plugins/database/database-migrations.md @@ -15,7 +15,7 @@ Migrations are PHP classes used to manage incremental and reversible database sc ## Prerequisites -To add your own database migrations for your plugin, you first need a plugin as a base. Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide). +To add your own database migrations for your plugin, you first need a plugin as a base. Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide.md). ::: info Refer to this video on **[Database migrations](https://www.youtube.com/watch?v=__pWwaK6lxw)**. Also, available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma). diff --git a/guides/plugins/plugins/dependencies/add-plugin-dependencies.md b/guides/plugins/plugins/dependencies/add-plugin-dependencies.md index 10624b067e..ee836abaf0 100644 --- a/guides/plugins/plugins/dependencies/add-plugin-dependencies.md +++ b/guides/plugins/plugins/dependencies/add-plugin-dependencies.md @@ -13,7 +13,7 @@ Shopware 6 supports declaring dependencies on other plugins that must be install ## Setup -Each plugin for Shopware 6 has to own a `composer.json` file for it to be a valid plugin. Creating a plugin is not explained here, make sure to read our [Plugin base guide](../plugin-base-guide) first. +Each plugin for Shopware 6 has to own a `composer.json` file for it to be a valid plugin. Creating a plugin is not explained here, make sure to read our [Plugin base guide](../plugin-base-guide.md) first. Since every plugin has to own a `composer.json` file, you can simply refer to this plugin by its technical name and its version mentioned in the respective plugin's `composer.json`. @@ -75,5 +75,5 @@ Now your plugin isn't installable anymore, until that requirement is fulfilled. ## More interesting topics -* [Using Composer dependencies](using-composer-dependencies) -* [Using NPM dependencies](using-npm-dependencies) +* [Using Composer dependencies](using-composer-dependencies.md) +* [Using NPM dependencies](using-npm-dependencies.md) diff --git a/guides/plugins/plugins/dependencies/using-composer-dependencies.md b/guides/plugins/plugins/dependencies/using-composer-dependencies.md index 075c7363db..32e5237ee3 100644 --- a/guides/plugins/plugins/dependencies/using-composer-dependencies.md +++ b/guides/plugins/plugins/dependencies/using-composer-dependencies.md @@ -124,5 +124,5 @@ You can then require them like other dependencies: ## More interesting topics -* [Using NPM dependencies](using-npm-dependencies) -* [Adding plugin dependencies](add-plugin-dependencies) +* [Using NPM dependencies](using-npm-dependencies.md) +* [Adding plugin dependencies](add-plugin-dependencies.md) diff --git a/guides/plugins/plugins/dependencies/using-npm-dependencies.md b/guides/plugins/plugins/dependencies/using-npm-dependencies.md index a6729f32ea..eaffb80138 100644 --- a/guides/plugins/plugins/dependencies/using-npm-dependencies.md +++ b/guides/plugins/plugins/dependencies/using-npm-dependencies.md @@ -60,7 +60,7 @@ Build the Administration using: composer build:js:admin ``` -For more information on migrating from Webpack to Vite, see the [Webpack to Vite migration guide](/guides/upgrades-migrations/administration/vite). +For more information on migrating from Webpack to Vite, see the [Webpack to Vite migration guide](../../../upgrades-migrations/administration/vite.md). ## Storefront (Webpack) @@ -128,6 +128,6 @@ Build the Storefront using: ## Next steps -Now that you know how to include new `npm` dependencies you might want to create a service with them. Learn how to do that in this guide: [How to add a custom-service](../administration/services-utilities/add-custom-service) +Now that you know how to include new `npm` dependencies you might want to create a service with them. Learn how to do that in this guide: [How to add a custom-service](../administration/services-utilities/add-custom-service.md) -If you want to add [Composer dependencies](using-composer-dependencies), or even other [plugin dependencies](add-plugin-dependencies), we've got you covered as well. +If you want to add [Composer dependencies](using-composer-dependencies.md), or even other [plugin dependencies](add-plugin-dependencies.md), we've got you covered as well. diff --git a/guides/plugins/plugins/framework/data-handling/add-data-indexer.md b/guides/plugins/plugins/framework/data-handling/add-data-indexer.md index f00bd5c9d2..21fdde45c4 100644 --- a/guides/plugins/plugins/framework/data-handling/add-data-indexer.md +++ b/guides/plugins/plugins/framework/data-handling/add-data-indexer.md @@ -13,15 +13,15 @@ Data indexer are used to optimize the performance of recurring complex tasks. One good example to understand the benefit of data indexer would be the cheapest price calculation within Shopware. Every product has a `cheapest_price` column in the database which should contain the cheapest price a product has. The calculation of this column can be complex, because a product can have several variants with advanced pricing rules and so on. This makes the calculation more difficult and would take too much time when reading 25 products for a listing. -To optimize the performance there is a data indexer that calculates the cheapest price of a product every time the product is updated by the DAL. This means that no new calculation has to be performed when a product is read, and performance during reading is significantly increased. Furthermore data indexer can make use of the [Message queue](../../../../hosting/infrastructure/message-queue) to handle the calculations asynchronously. +To optimize the performance there is a data indexer that calculates the cheapest price of a product every time the product is updated by the DAL. This means that no new calculation has to be performed when a product is read, and performance during reading is significantly increased. Furthermore data indexer can make use of the [Message queue](../../../../hosting/infrastructure/message-queue.md) to handle the calculations asynchronously. ## Prerequisites -This guide is built upon the [Plugin base guide](../../plugin-base-guide), but any plugin will work here. Just note that all examples are using the plugin mentioned above. In order to create data indexer you should have read the [Adding custom complex data guide](./add-custom-complex-data). +This guide is built upon the [Plugin base guide](../../plugin-base-guide.md), but any plugin will work here. Just note that all examples are using the plugin mentioned above. In order to create data indexer you should have read the [Adding custom complex data guide](./add-custom-complex-data.md). ## Adding an own data indexer -It is possible to add data indexer for your own entities, like the one created in the [Adding custom complex data](./add-custom-complex-data) guide or for existing entities. However, if you want to react on changes of existing entities the preferred way should be subscribing to the events if available. See the [Index data using existing events](#index-data-using-existing-events) section below. To create a new indexer, just create a new class in your plugin: +It is possible to add data indexer for your own entities, like the one created in the [Adding custom complex data](./add-custom-complex-data) guide or for existing entities. However, if you want to react on changes of existing entities the preferred way should be subscribing to the events if available. See the [Index data using existing events](./add-data-indexer.md#index-data-using-existing-events) section below. To create a new indexer, just create a new class in your plugin: ```php // <plugin root>/src/Core/Framework/DataAbstractionLayer/Indexing/ExampleIndexer.php @@ -168,7 +168,7 @@ Let's take a closer look at the functions of the entity indexer class. ### Handle messages asynchronously or synchronously -By default, all messages which are returned by the `public function update()` function in the indexer are handled synchronously. That means the `handle()` function is called directly after the `update()` function. To handle the messages asynchronously over the [Message queue](../../../../hosting/infrastructure/message-queue) the `EntityIndexingMessage` can be used with different constructor parameters. A closer look at the `EntityIndexingMessage` class shows that it has a fourth parameter named `$forceQueue` which is `false` by default. This parameter can be set to `true` and then the message will be handled asynchronously by the message queue. +By default, all messages which are returned by the `public function update()` function in the indexer are handled synchronously. That means the `handle()` function is called directly after the `update()` function. To handle the messages asynchronously over the [Message queue](../../../../hosting/infrastructure/message-queue.md) the `EntityIndexingMessage` can be used with different constructor parameters. A closer look at the `EntityIndexingMessage` class shows that it has a fourth parameter named `$forceQueue` which is `false` by default. This parameter can be set to `true` and then the message will be handled asynchronously by the message queue. ### Use DAL functionalities in the indexer diff --git a/guides/plugins/plugins/framework/data-handling/reading-data.md b/guides/plugins/plugins/framework/data-handling/reading-data.md index 91e6f4b8db..2b6f436843 100644 --- a/guides/plugins/plugins/framework/data-handling/reading-data.md +++ b/guides/plugins/plugins/framework/data-handling/reading-data.md @@ -13,7 +13,7 @@ In this guide you will learn how to properly fetch data from the database in you ## Prerequisites -Since this guide is built upon the plugin base guide [Plugin base guide](../../plugin-base-guide), you might want to have a look at it. Furthermore, the guide about [Dependency injection](../../services/dependency-injection.md) will come in handy, since you need to know how to inject a service using the DI container. You also might want to have a look at the concept behind the [Data abstraction layer](../../../../../concepts/framework/data-abstraction-layer) to get a better grasp of how it works. +Since this guide is built upon the plugin base guide [Plugin base guide](../../plugin-base-guide.md), you might want to have a look at it. Furthermore, the guide about [Dependency injection](../../services/dependency-injection.md) will come in handy, since you need to know how to inject a service using the DI container. You also might want to have a look at the concept behind the [Data abstraction layer](../../../../../concepts/framework/data-abstraction-layer.md) to get a better grasp of how it works. ## Reading data diff --git a/guides/plugins/plugins/framework/data-handling/using-database-events.md b/guides/plugins/plugins/framework/data-handling/using-database-events.md index 0ff13182f5..4aab0e9e1c 100644 --- a/guides/plugins/plugins/framework/data-handling/using-database-events.md +++ b/guides/plugins/plugins/framework/data-handling/using-database-events.md @@ -15,7 +15,7 @@ All events are nested into one container event so that your subscriber should on ## Prerequisites -This guide is built upon the [Plugin base guide](../../plugin-base-guide), but any plugin will work here. Just note that all examples are using the plugin mentioned above. +This guide is built upon the [Plugin base guide](../../plugin-base-guide.md), but any plugin will work here. Just note that all examples are using the plugin mentioned above. Furthermore you should have a look at our [Listening to Events](../../framework/event/listening-to-events.md) guide since we are subscribing to events in this guide. diff --git a/guides/plugins/plugins/framework/data-handling/using-flags.md b/guides/plugins/plugins/framework/data-handling/using-flags.md index 5cf33e686e..8a7c160094 100644 --- a/guides/plugins/plugins/framework/data-handling/using-flags.md +++ b/guides/plugins/plugins/framework/data-handling/using-flags.md @@ -13,9 +13,9 @@ In this guide you'll learn how to use flags of the DAL but this guide will not e ## Prerequisites -In order to use flags in your entities for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../../plugin-base-guide). +In order to use flags in your entities for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../../plugin-base-guide.md). -You should also have a look at the [Flags reference](../../../../development/troubleshooting/dal-reference/flags-reference.md) to understand what each flag is used for. Furthermore you should know how entities work, therefore you can head over to our [Adding custom complex data](add-custom-complex-data) guide. +You should also have a look at the [Flags reference](../../../../development/troubleshooting/dal-reference/flags-reference.md) to understand what each flag is used for. Furthermore you should know how entities work, therefore you can head over to our [Adding custom complex data](add-custom-complex-data.md) guide. ## Using flags diff --git a/guides/plugins/plugins/framework/data-handling/versioning-entities.md b/guides/plugins/plugins/framework/data-handling/versioning-entities.md index 7765511c1c..b4fd04e7ea 100644 --- a/guides/plugins/plugins/framework/data-handling/versioning-entities.md +++ b/guides/plugins/plugins/framework/data-handling/versioning-entities.md @@ -11,14 +11,14 @@ nav: In this guide you will learn how to version your entities. The entity versioning system in Shopware gives you the opportunity to create multiple versions of an entity, which could be used to save drafts for example. -Learn more about the versioning concept [here](../../../../../concepts/framework/data-abstraction-layer#versioning). +Learn more about the versioning concept [here](../../../../../concepts/framework/data-abstraction-layer.md#versioning). ## Prerequisites In order to add your own versioned entities for your plugin, you first need a plugin as base. -Therefore, you can refer to the [Plugin Base Guide](../../plugin-base-guide). +Therefore, you can refer to the [Plugin Base Guide](../../plugin-base-guide.md). -Furthermore, you should have a look at our [Adding custom complex data](add-custom-complex-data) guide, since this guide is built upon it. +Furthermore, you should have a look at our [Adding custom complex data](add-custom-complex-data.md) guide, since this guide is built upon it. ## Adjust migration @@ -116,7 +116,7 @@ The merged version is now our new live version. From now on we can find it witho If you have an entity with foreign keys, your foreign keys also need to be versioned. In this example we're using an inherited field. -If you are not familiar with inheritance, head over to our [Field inheritance](field-inheritance) guide. +If you are not familiar with inheritance, head over to our [Field inheritance](field-inheritance.md) guide. ### Migration diff --git a/guides/plugins/plugins/framework/data-handling/writing-data.md b/guides/plugins/plugins/framework/data-handling/writing-data.md index 5a55f109a8..f1ba01248e 100644 --- a/guides/plugins/plugins/framework/data-handling/writing-data.md +++ b/guides/plugins/plugins/framework/data-handling/writing-data.md @@ -13,9 +13,9 @@ This guide explains how to write data to the database in Shopware 6. It also inc ## Prerequisites -This guide is built upon the [Plugin base guide](../../plugin-base-guide), so having a look at it first won't hurt. Having read the guide about [Reading data](reading-data) or understanding how to read data is mandatory for at least one short part of this guide. +This guide is built upon the [Plugin base guide](../../plugin-base-guide.md), so having a look at it first won't hurt. Having read the guide about [Reading data](reading-data.md) or understanding how to read data is mandatory for at least one short part of this guide. -You also might want to have a look at the concept behind the [Data abstraction layer](../../../../../concepts/framework/data-abstraction-layer) first to get a better grasp of how it works. +You also might want to have a look at the concept behind the [Data abstraction layer](../../../../../concepts/framework/data-abstraction-layer.md) first to get a better grasp of how it works. ::: info Refer to this video on **[Using repositories](https://www.youtube.com/watch?v=b3wOs_OWvP0)** that covers the basics of repositories. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma). @@ -123,9 +123,9 @@ In there, we're calling the `create` method on the product repository with two p This minimal example is just filling in the product's mandatory fields: The `name`, the `productNumber`, the `stock`, the `taxId` and the `price`. So the first three fields are just plain values, easy as that. -The `taxId` though represents the ID of the associated `tax`. Since we want to assign an existing tax here, we've created a new method called `getTaxId` to actually read the ID that we need. For this purpose, you need to understand how to read data from Shopware, so have a look at our guide about [Reading data](reading-data). We're calling `searchIds` on the `taxRepository` to only get IDs, since we don't need the full tax data here. Since we only need the first ID with the given tax rate here, we're just grabbing the first ID by using the `firstId` method on the collection. And there we go, we got a tax ID to fill into the mandatory field `taxId`. +The `taxId` though represents the ID of the associated `tax`. Since we want to assign an existing tax here, we've created a new method called `getTaxId` to actually read the ID that we need. For this purpose, you need to understand how to read data from Shopware, so have a look at our guide about [Reading data](reading-data.md). We're calling `searchIds` on the `taxRepository` to only get IDs, since we don't need the full tax data here. Since we only need the first ID with the given tax rate here, we're just grabbing the first ID by using the `firstId` method on the collection. And there we go, we got a tax ID to fill into the mandatory field `taxId`. -A further explanation on how to write new associated data, instead of using existing entities, is also provided in the section [Assigning associated data](writing-data#assigning-associated-data). +A further explanation on how to write new associated data, instead of using existing entities, is also provided in the section [Assigning associated data](writing-data.md#assigning-associated-data). Now, let's go on to the last field, the `price`. The price is saved to the product entity via a `JsonField`, so it's saved in the JSON format in the database. A product can have multiple prices, thus we're providing an array of arrays again here. For this example we'll still just write a single price. The structure for the JSON can be found in the [getConstraints method of the PriceFieldSerializer](https://github.com/shopware/shopware/blob/v6.3.4.0/src/Core/Framework/DataAbstractionLayer/FieldSerializer/PriceFieldSerializer.php#L112-L141). Basically you need to provide a currency ID, for which we'll just use the shop's default currency, a gross and a net price and a boolean value of whether or not the gross and the net price are linked. If `linked` is set to `true`, changes to the gross price will also affect the net price, using the product's tax. @@ -224,7 +224,7 @@ Once again: An array of arrays, since you can delete more than one entry at once Assigning associated data is different for each kind of association. Every single of them will be covered here, from `OneToOne` associations, to `ManyToOne` and `OneToMany` associations and `ManyToMany` associations. -If you don't know how to add associations to an entity, maybe to your own entity, head over to our guide for adding an association to an entity [Add data associations](add-data-associations). +If you don't know how to add associations to an entity, maybe to your own entity, head over to our guide for adding an association to an entity [Add data associations](add-data-associations.md). #### OneToOne and ManyToOne associations @@ -308,7 +308,7 @@ public function writeData(Context $context): void The reason for that is simple: With every update action, you need to provide the primary key and the data to be updated. For mapping entities though, all data you could provide are primary keys themselves and you can't update primary keys. -Your only way to solve this is by replacing the association. Head over to our guide regarding [Replacing associated data](replacing-associated-data). +Your only way to solve this is by replacing the association. Head over to our guide regarding [Replacing associated data](replacing-associated-data.md). ### Creating associated data @@ -360,8 +360,8 @@ Note the `categories` field here. Just remember to use an array of arrays for `T ### Replacing and deleting associated data -Replacing associated data is not always as easy as it seems. Head over to our guide about [Replacing associated data](replacing-associated-data) to get a full grasp of how it is done. While [Deleting associated data](deleting-associated-data) is a separate guide refer to that as well. +Replacing associated data is not always as easy as it seems. Head over to our guide about [Replacing associated data](replacing-associated-data.md) to get a full grasp of how it is done. While [Deleting associated data](deleting-associated-data) is a separate guide refer to that as well. ## Next steps -You should now be able to write data to the database using the Data Abstraction Layer from Shopware 6. You might have missed the guide about [Reading data](reading-data) in the first place though, and you should definitely know how that is done. +You should now be able to write data to the database using the Data Abstraction Layer from Shopware 6. You might have missed the guide about [Reading data](reading-data.md) in the first place though, and you should definitely know how that is done. diff --git a/guides/plugins/plugins/framework/filesystem/filesystem.md b/guides/plugins/plugins/framework/filesystem/filesystem.md index 47db12499f..566c2bbaaa 100644 --- a/guides/plugins/plugins/framework/filesystem/filesystem.md +++ b/guides/plugins/plugins/framework/filesystem/filesystem.md @@ -24,7 +24,7 @@ However, every plugin/bundle gets an own namespace that should be used for priva ## Prerequisites -This guide is built upon both the [Plugin base guide](../../plugin-base-guide) and the [Add custom service guide](../../services/add-custom-service.md). +This guide is built upon both the [Plugin base guide](../../plugin-base-guide.md) and the [Add custom service guide](../../services/add-custom-service.md). ## Use filesystem in a service diff --git a/guides/plugins/plugins/framework/filesystem/index.md b/guides/plugins/plugins/framework/filesystem/index.md index 2ea778b52f..87449ff9b7 100644 --- a/guides/plugins/plugins/framework/filesystem/index.md +++ b/guides/plugins/plugins/framework/filesystem/index.md @@ -11,4 +11,4 @@ Plugins often need the ability to read and write files. Shopware uses [Flysystem Plugins do not require handling underlying configuration. It is possible to use the Flysystem abstraction directly, and the read/write API remains the same regardless of whether files are stored on a local file system or with a cloud provider. -To learn more about filesystem configuration in Shopware, see the [filesystem guide](../../../../hosting/infrastructure/filesystem), including details on using cloud storage (such as Amazon S3) to outsource the file system. +To learn more about filesystem configuration in Shopware, see the [filesystem guide](../../../../hosting/infrastructure/filesystem.md), including details on using cloud storage (such as Amazon S3) to outsource the file system. diff --git a/guides/plugins/plugins/framework/flow/action-transactions.md b/guides/plugins/plugins/framework/flow/action-transactions.md index d995db1682..15f1a8ecce 100644 --- a/guides/plugins/plugins/framework/flow/action-transactions.md +++ b/guides/plugins/plugins/framework/flow/action-transactions.md @@ -11,11 +11,11 @@ nav: In this guide, you will learn how to run your action code inside a transaction. This may be important for you if you want to graciously handle rollbacks in certain scenarios. We have implemented various abstractions to ease this process; however, you need to opt in. -For some more background, please see the ADR [Action Transactions](../../../../../resources/references/adr/2024-02-11-transactional-flow-actions). +For some more background, please see the ADR [Action Transactions](../../../../../resources/references/adr/2024-02-11-transactional-flow-actions.md). ## Prerequisites -In order to make your action run inside a database transaction, you will need an existing Flow Action. Therefore, you can refer to the [Add Flow Builder Action Guide.](./add-flow-builder-action) +In order to make your action run inside a database transaction, you will need an existing Flow Action. Therefore, you can refer to the [Add Flow Builder Action Guide.](./add-flow-builder-action.md) ## Run your action inside a transaction diff --git a/guides/plugins/plugins/framework/flow/add-flow-builder-action.md b/guides/plugins/plugins/framework/flow/add-flow-builder-action.md index 938ede561f..7be8244b84 100644 --- a/guides/plugins/plugins/framework/flow/add-flow-builder-action.md +++ b/guides/plugins/plugins/framework/flow/add-flow-builder-action.md @@ -13,11 +13,11 @@ In this guide, you'll learn how to create custom flow action in Shopware. The fl ## Prerequisites -In order to add your own custom flow action for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide.](../../plugin-base-guide) +In order to add your own custom flow action for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide.](../../plugin-base-guide.md) You also should be familiar with the [Dependency Injection container](../../services/dependency-injection.md) as this is used to register your custom flow action and [Listening to events](../../framework/event/listening-to-events.md#creating-your-own-subscriber) to create a subscriber class. -It might be helpful to gather some general understanding about the [concept of Flow Builder](../../../../../concepts/framework/flow-concept) as well. +It might be helpful to gather some general understanding about the [concept of Flow Builder](../../../../../concepts/framework/flow-concept.md) as well. ## Existing triggers and actions diff --git a/guides/plugins/plugins/framework/flow/add-flow-builder-trigger.md b/guides/plugins/plugins/framework/flow/add-flow-builder-trigger.md index 3ebcc5ad06..666722994b 100644 --- a/guides/plugins/plugins/framework/flow/add-flow-builder-trigger.md +++ b/guides/plugins/plugins/framework/flow/add-flow-builder-trigger.md @@ -17,10 +17,9 @@ In this guide, you'll learn how to create a custom flow trigger in Shopware. Tri ## Prerequisites -In order to add your own custom flow trigger for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../../plugin-base-guide). +In order to add your own custom flow trigger for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../../plugin-base-guide.md). -You also should be familiar with [Add custom event](../event/add-custom-event) to know how to create an event. Please refer to the [Flow Builder concept](../../../../../concepts/framework/flow-concept) -for better integration later. +You also should be familiar with [Add custom event](../event/add-custom-event.md) to know how to create an event. Please refer to the [Flow Builder concept](../../../../../concepts/framework/flow-concept.md) for better integration later. ## Existing triggers and actions @@ -44,7 +43,7 @@ Any event that implements one of these interfaces will be available in the trigg ## Create custom flow trigger -To create a custom flow trigger, firstly you have to create a plugin and install it, you can refer to the [Plugin Base Guide](../../plugin-base-guide) to do it. I will create a plugin named `ExamplePlugin`. There will be an example to actually show your new trigger in the Administration. +To create a custom flow trigger, firstly you have to create a plugin and install it, you can refer to the [Plugin Base Guide](../../plugin-base-guide.md) to do it. I will create a plugin named `ExamplePlugin`. There will be an example to actually show your new trigger in the Administration. ### Create a new trigger (event) @@ -117,7 +116,7 @@ From 6.5, in Flow Builder, the original event will be deprecated and we will onl We have created many Aware interfaces. These Aware are the conditions to restore event data in Flow Builder via `FlowStorer` respective. -You could read here more about the [Storer](../../../../../concepts/framework/flow-concept#storer-concept) concept. +You could read here more about the [Storer](../../../../../concepts/framework/flow-concept.md#storer-concept) concept. | Aware interface | Storer respective | | :--- | :--- | diff --git a/guides/plugins/plugins/framework/message-queue/add-message-handler.md b/guides/plugins/plugins/framework/message-queue/add-message-handler.md index 511a8a7fbc..a42c5b481c 100644 --- a/guides/plugins/plugins/framework/message-queue/add-message-handler.md +++ b/guides/plugins/plugins/framework/message-queue/add-message-handler.md @@ -19,7 +19,7 @@ A [handler](https://symfony.com/doc/current/messenger.html#creating-a-message-ha ## Prerequisites -As most guides, this guide is also built upon the [Plugin base guide](../../plugin-base-guide), but you don't necessarily need that. It will use an example message, so if you don't know how to add a custom message yet, have a look at our guide about [Adding a message to queue](add-message-to-queue). Furthermore, registering classes or services to the DI container is also not explained here, but it's covered in our guide about [Dependency injection](../../services/dependency-injection.md), so having this open in another tab won't hurt. +As most guides, this guide is also built upon the [Plugin base guide](../../plugin-base-guide.md), but you don't necessarily need that. It will use an example message, so if you don't know how to add a custom message yet, have a look at our guide about [Adding a message to queue](add-message-to-queue.md). Furthermore, registering classes or services to the DI container is also not explained here, but it's covered in our guide about [Dependency injection](../../services/dependency-injection.md), so having this open in another tab won't hurt. ## Handling messages @@ -46,6 +46,6 @@ class SmsHandler ## Next steps -Now that you know how to add a message handler, you may want to add a custom middleware for your bus. To do this, head over to [Add middleware](add-middleware) guide. +Now that you know how to add a message handler, you may want to add a custom middleware for your bus. To do this, head over to [Add middleware](add-middleware.md) guide. If you want to learn more about configuring the message queue, have a look at the [Message queue hosting guide](../../../../hosting/infrastructure/message-queue.md). diff --git a/guides/plugins/plugins/framework/message-queue/add-message-to-queue.md b/guides/plugins/plugins/framework/message-queue/add-message-to-queue.md index 7722b75bbc..43e22d1a1d 100644 --- a/guides/plugins/plugins/framework/message-queue/add-message-to-queue.md +++ b/guides/plugins/plugins/framework/message-queue/add-message-to-queue.md @@ -23,7 +23,7 @@ It will be wrapped in an [envelope](https://symfony.com/doc/current/components/m ## Prerequisites -As most guides, this guide is also built upon the [Plugin base guide](../../plugin-base-guide), but you don't necessarily need that. It will use an example service, so if you don't know how to add a custom service yet, have a look at our guide about [Adding a custom service](../../services/add-custom-service.md). Furthermore, registering classes or services to the DI container is also not explained here, but it's covered in our guide about [Dependency injection](../../services/dependency-injection.md), so having this open in another tab won't hurt. +As most guides, this guide is also built upon the [Plugin base guide](../../plugin-base-guide.md), but you don't necessarily need that. It will use an example service, so if you don't know how to add a custom service yet, have a look at our guide about [Adding a custom service](../../services/add-custom-service.md). Furthermore, registering classes or services to the DI container is also not explained here, but it's covered in our guide about [Dependency injection](../../services/dependency-injection.md), so having this open in another tab won't hurt. ## Create a message @@ -140,4 +140,4 @@ shopware: ## Next steps -Now that you know how to create a message and add it to the queue, let's create a handler to process our message. To do this, head over to [Add message handler](add-message-handler) guide. +Now that you know how to create a message and add it to the queue, let's create a handler to process our message. To do this, head over to [Add message handler](add-message-handler.md) guide. diff --git a/guides/plugins/plugins/framework/message-queue/add-middleware.md b/guides/plugins/plugins/framework/message-queue/add-middleware.md index d16a6134a5..860a78bbd5 100644 --- a/guides/plugins/plugins/framework/message-queue/add-middleware.md +++ b/guides/plugins/plugins/framework/message-queue/add-middleware.md @@ -15,7 +15,7 @@ A [Middleware](https://symfony.com/doc/current/messenger.html#middleware) is cal ## Prerequisites -As most guides, this guide is also built upon the [Plugin base guide](../../plugin-base-guide), but you don't necessarily need that. Furthermore, registering classes or services to the DI container is also not explained here, but it's covered in our guide about [Dependency injection](../../services/dependency-injection.md), so having this open in another tab won't hurt. +As most guides, this guide is also built upon the [Plugin base guide](../../plugin-base-guide.md), but you don't necessarily need that. Furthermore, registering classes or services to the DI container is also not explained here, but it's covered in our guide about [Dependency injection](../../services/dependency-injection.md), so having this open in another tab won't hurt. ## Create middleware @@ -62,5 +62,5 @@ framework: ## More interesting topics -* [Message Queue](add-message-to-queue) -* [Message Handler](add-message-handler) +* [Message Queue](add-message-to-queue.md) +* [Message Handler](add-message-handler.md) diff --git a/guides/plugins/plugins/framework/rate-limiter/add-rate-limiter-to-api-route.md b/guides/plugins/plugins/framework/rate-limiter/add-rate-limiter-to-api-route.md index 5c8258ab39..4547cbaf3e 100644 --- a/guides/plugins/plugins/framework/rate-limiter/add-rate-limiter-to-api-route.md +++ b/guides/plugins/plugins/framework/rate-limiter/add-rate-limiter-to-api-route.md @@ -13,13 +13,13 @@ A rate limiter controls the rate or frequency at which API requests can be made. In this guide you'll learn how to secure API routes with a rate limit to reduce the risk against bruteforce attacks. If you want to learn more about the configuration of the rate limiter in Shopware, -have a look at the [Rate limiter](../../../../hosting/infrastructure/rate-limiter) guide. +have a look at the [Rate limiter](../../../../hosting/infrastructure/rate-limiter.md) guide. ## Prerequisites -This guide is built upon both the [Plugin base guide](../../plugin-base-guide) as well as the [Dependency injection](../../services/dependency-injection.md) guide. +This guide is built upon both the [Plugin base guide](../../plugin-base-guide.md) as well as the [Dependency injection](../../services/dependency-injection.md) guide. -Furthermore you need an existing API route, to create a new one, head over to our [Add store API route](../store-api/add-store-api-route) guide. +Furthermore you need an existing API route, to create a new one, head over to our [Add Store API route](../store-api/add-store-api-route.md) guide. ## Creating a new rate limit @@ -33,7 +33,7 @@ Each rate limit configuration needs the following keys: - `enabled`: Enables / Disables the rate limit for the specific route (default value: true). - `policy`: Possible policies are `fixed_window`, `sliding_window`, `token_bucket`, `time_backoff`. For more information check the [Symfony documentation](https://symfony.com/doc/current/rate_limiter.html#rate-limiting-policies). -If you plan to configure the `time_backoff` policy, head over to [rate limiter](../../../../hosting/infrastructure/rate-limiter#configuring-time-backoff-policy) guide. +If you plan to configure the `time_backoff` policy, head over to [rate limiter](../../../../hosting/infrastructure/rate-limiter.md#configuring-time-backoff-policy) guide. Otherwise, check the [Symfony documentation](https://symfony.com/doc/current/rate_limiter.html#configuration) for the other keys you need for each policy. ```yaml diff --git a/guides/plugins/plugins/framework/rule/add-custom-rules.md b/guides/plugins/plugins/framework/rule/add-custom-rules.md index 3191a6b777..e0efe78e7c 100644 --- a/guides/plugins/plugins/framework/rule/add-custom-rules.md +++ b/guides/plugins/plugins/framework/rule/add-custom-rules.md @@ -15,11 +15,11 @@ This example will introduce a new rule, which checks if it is the first monday o ## Prerequisites -In order to add your own custom rules for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../../plugin-base-guide). +In order to add your own custom rules for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../../plugin-base-guide.md). You also should be familiar with the [Dependency Injection container](../../services/dependency-injection.md) as this is used to register your custom rule. -It might be helpful to gather some general understanding about the concept of [Rules](../../../../../concepts/framework/rule-system/index.md) (../../../../../concepts/framework/rule) as well. +It might be helpful to gather some general understanding about the concept of [Rules](../../../../../concepts/framework/rule-system/index.md) as well. ## Create custom rule @@ -140,7 +140,7 @@ $context->getRuleIds(); ### Showing rule in the Administration -Now we want to implement our new rule in the Administration so that we can manage it. To achieve this, we have to call the `addCondition` method of the [RuleConditionService](https://github.com/shopware/shopware/blob/v6.6.0.0/src/Administration/Resources/app/administration/src/app/service/rule-condition.service.ts), by decorating this service. The decoration of services in the Administration will be covered in our [Adding services](../../administration/services-utilities/add-custom-service#Decorating%20a%20service) guide. +Now we want to implement our new rule in the Administration so that we can manage it. To achieve this, we have to call the `addCondition` method of the [RuleConditionService](https://github.com/shopware/shopware/blob/v6.6.0.0/src/Administration/Resources/app/administration/src/app/service/rule-condition.service.ts), by decorating this service. The decoration of services in the Administration will be covered in our [Adding services](../../administration/services-utilities/add-custom-service.md#decorating-a-service) guide. Create a new directory called `<plugin root>/src/Resources/app/administration/src/decorator`. In this directory we create a new file called `rule-condition-service-decoration.js`. @@ -208,7 +208,7 @@ Shopware.Application.addServiceProviderDecorator('ruleConditionDataProviderServi ### Custom rule component -Now that you have registered your rule to the Administration, you would still be lacking the actual component `swag-first-monday`. As you have already defined a path for it in your service decoration, create the following directory: `<plugin root>/src/Resources/app/administration/src/core/component/swag-first-monday`. If you are unfamiliar with creating components in Shopware, refer to the [add your own component](../../administration/module-component-management/add-custom-component) section. +Now that you have registered your rule to the Administration, you would still be lacking the actual component `swag-first-monday`. As you have already defined a path for it in your service decoration, create the following directory: `<plugin root>/src/Resources/app/administration/src/core/component/swag-first-monday`. If you are unfamiliar with creating components in Shopware, refer to the [add your own component](../../administration/module-component-management/add-custom-component.md) section. Here's an example of what this component could look like: @@ -346,7 +346,7 @@ When you add a new rule-select component to assign rules somewhere in Shopware, For that, we need to write some twig code. The important property here is the `rule-aware-group-key` property which should match the assignment name of the rule-aware group we just extended. ::: info -Refer to [customize administration components](../../administration/module-component-management/customizing-components) to know more about it. +Refer to [customize Administration components](../../administration/module-component-management/customizing-components.md) to know more about it. ::: ```twig @@ -365,4 +365,4 @@ The above guide explains the integration of a boolean and no values. If you want ## Further reading -For more other information you can refer to [Add rule assignment configuration](../../administration/advanced-configuration/add-rule-assignment-configuration) section of the guide. +For more other information you can refer to [Add rule assignment configuration](../../administration/advanced-configuration/add-rule-assignment-configuration.md) section of the guide. diff --git a/guides/plugins/plugins/framework/store-api/override-existing-route.md b/guides/plugins/plugins/framework/store-api/override-existing-route.md index 95123ef0d7..40dc4c77d7 100644 --- a/guides/plugins/plugins/framework/store-api/override-existing-route.md +++ b/guides/plugins/plugins/framework/store-api/override-existing-route.md @@ -13,9 +13,9 @@ In this guide you will learn how to override existing Store API routes to add ad ## Prerequisites -As most guides, this guide is also built upon the [Plugin base guide](../../plugin-base-guide), but you don't necessarily need that. +As most guides, this guide is also built upon the [Plugin base guide](../../plugin-base-guide.md), but you don't necessarily need that. -Furthermore, you should have a look at our guide about [Adding a Store API route](add-store-api-route), since this guide is built upon it. +Furthermore, you should have a look at our guide about [Adding a Store API route](add-store-api-route.md), since this guide is built upon it. ## Decorating our route diff --git a/guides/plugins/plugins/framework/system-check/add-custom-check.md b/guides/plugins/plugins/framework/system-check/add-custom-check.md index 36e3b547e2..f08f987ab3 100644 --- a/guides/plugins/plugins/framework/system-check/add-custom-check.md +++ b/guides/plugins/plugins/framework/system-check/add-custom-check.md @@ -100,4 +100,4 @@ $services->set(YourNameSpace\LocalDiskSpaceCheck::class) ### Trigger the check -The system check is now part of the system check collection and will be executed when the system check is triggered. Refer to the [System Check](./) guide for more information. +The system check is now part of the system check collection and will be executed when the system check is triggered. Refer to the [System Check](index.md) guide for more information. diff --git a/guides/plugins/plugins/integrations/elasticsearch/add-product-entity-extension-to-elasticsearch.md b/guides/plugins/plugins/integrations/elasticsearch/add-product-entity-extension-to-elasticsearch.md index 7a9ccaeed2..8db8d1687d 100644 --- a/guides/plugins/plugins/integrations/elasticsearch/add-product-entity-extension-to-elasticsearch.md +++ b/guides/plugins/plugins/integrations/elasticsearch/add-product-entity-extension-to-elasticsearch.md @@ -9,11 +9,11 @@ nav: In this guide you'll learn how to add extended fields of the product entity to the elasticsearch engine to make it searchable. -In this example we'll assume an extension of the `ProductDefinition` with a string field `customString` like described in [Adding Complex data to existing entities](../../framework/data-handling/add-complex-data-to-existing-entities#adding-a-field-without-database). +In this example we'll assume an extension of the `ProductDefinition` with a string field `customString` like described in [Adding complex data to existing entities](../../framework/data-handling/add-complex-data-to-existing-entities.md#adding-a-field-without-database). ## Prerequisites -This guide is built upon the [Plugin Base Guide](../../plugin-base-guide.md), and the entity extension described in [Adding Complex data to existing entities](../../framework/data-handling/add-complex-data-to-existing-entities#adding-a-field-without-database). +This guide is built upon the [Plugin Base Guide](../../plugin-base-guide.md), and the entity extension described in [Adding complex data to existing entities](../../framework/data-handling/add-complex-data-to-existing-entities.md#adding-a-field-without-database). We will extend the product extension with an `OneToOneAssociationField` and `OneToManyAssociationField`. ## Decorate the ElasticsearchProductDefinition diff --git a/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md b/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md index b987a72e42..e7eb2d8b13 100644 --- a/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md +++ b/guides/plugins/plugins/plugin-fundamentals/add-custom-commands.md @@ -20,4 +20,4 @@ Commands registered as services in a Shopware plugin are automatically available ## Other interesting topics -* [Adding a scheduled task](add-scheduled-task) +* [Adding a scheduled task](add-scheduled-task.md) diff --git a/guides/plugins/plugins/plugin-fundamentals/add-scheduled-task.md b/guides/plugins/plugins/plugin-fundamentals/add-scheduled-task.md index bcb539191c..a039cf3c1e 100644 --- a/guides/plugins/plugins/plugin-fundamentals/add-scheduled-task.md +++ b/guides/plugins/plugins/plugin-fundamentals/add-scheduled-task.md @@ -11,7 +11,7 @@ Quite often one might want to run any type of code on a regular basis, e.g. to c ## Prerequisites -This guide is built upon our [plugin base guide](../plugin-base-guide), but that one is not mandatory. Knowing how the `services.php` file in a plugin works is also helpful, which will be taught in our guides about [Dependency Injection](../services/dependency-injection.md) and [Creating a service](../services/add-custom-service.md). It is shortly explained here as well though, so no worries! +This guide is built upon our [plugin base guide](../plugin-base-guide.md), but that one is not mandatory. Knowing how the `services.php` file in a plugin works is also helpful, which will be taught in our guides about [Dependency Injection](../services/dependency-injection.md) and [Creating a service](../services/add-custom-service.md). It is shortly explained here as well though, so no worries! ::: info Refer to this video on **[Adding scheduled tasks](https://www.youtube.com/watch?v=88S9P3x6wYE)**. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma). @@ -125,4 +125,4 @@ Now you still need to run the command `bin/console messenger:consume` to actuall ## More interesting topics -* [Adding a custom command](add-custom-commands) +* [Adding a custom command](add-custom-commands.md) diff --git a/guides/plugins/plugins/plugin-fundamentals/logging.md b/guides/plugins/plugins/plugin-fundamentals/logging.md index 45ef94236e..f367014c53 100644 --- a/guides/plugins/plugins/plugin-fundamentals/logging.md +++ b/guides/plugins/plugins/plugin-fundamentals/logging.md @@ -13,7 +13,7 @@ As a plugin developer, you may want to log certain actions or errors to a log fi ## Prerequisites -This guide is built upon our [plugin base guide](../plugin-base-guide), which explains the basics of a plugin as a whole. Make sure to have a look at it to get started on building your first plugin. +This guide is built upon our [plugin base guide](../plugin-base-guide.md), which explains the basics of a plugin as a whole. Make sure to have a look at it to get started on building your first plugin. ## Configuring Monolog diff --git a/guides/plugins/plugins/plugin-fundamentals/use-plugin-configuration.md b/guides/plugins/plugins/plugin-fundamentals/use-plugin-configuration.md index c931476c6c..22688a8717 100644 --- a/guides/plugins/plugins/plugin-fundamentals/use-plugin-configuration.md +++ b/guides/plugins/plugins/plugin-fundamentals/use-plugin-configuration.md @@ -11,7 +11,7 @@ The [Add a Plugin Configuration Guide](add-plugin-configuration.md) shows how to ## Prerequisites -- A plugin [Plugin Base Guide](../plugin-base-guide.md) +- Review the [Plugin Base Guide](../plugin-base-guide.md) - [Plugin configuration](add-plugin-configuration.md) in the first instance - Familiarity with the [Listening to events](../framework/event/listening-to-events.md) guide, as in this example the configuration is read inside of a subscriber diff --git a/guides/plugins/plugins/services/adjusting-service.md b/guides/plugins/plugins/services/adjusting-service.md index 62cf9e43be..1457823e09 100644 --- a/guides/plugins/plugins/services/adjusting-service.md +++ b/guides/plugins/plugins/services/adjusting-service.md @@ -13,7 +13,7 @@ In this guide you'll learn how to adjust a service. You can read more about serv ## Prerequisites -In order to add your own custom service for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide). +In order to add your own custom service for your plugin, you first need a plugin as base. Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide.md). ::: info Refer to this video on **[Decorating services](https://www.youtube.com/watch?v=Rgf4c9rd1kw)** explaining service decorations with an easy example. Also available on our free online training ["Shopware 6 Backend Development"](https://academy.shopware.com/courses/shopware-6-backend-development-with-jisse-reitsma). diff --git a/guides/plugins/plugins/services/dependency-injection.md b/guides/plugins/plugins/services/dependency-injection.md index 8a9c73ba4b..d79c3a88cb 100644 --- a/guides/plugins/plugins/services/dependency-injection.md +++ b/guides/plugins/plugins/services/dependency-injection.md @@ -15,10 +15,10 @@ You can read more about injecting services in the [Symfony documentation](https: ## Prerequisites To add your own custom service for your plugin, you first need a plugin as a base. -Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide). +Therefore, you can refer to the [Plugin Base Guide](../plugin-base-guide.md). Furthermore, you need a working service. -Therefore, you can refer to [Adding a custom service](add-custom-service) guide. +Therefore, you can refer to [Adding a custom service](add-custom-service.md) guide. ::: info Refer to this video on **[Injecting services into a command](https://www.youtube.com/watch?v=Z4kyx9J1xaQ)** explaining DI based on the example of a custom CLI command. diff --git a/guides/plugins/plugins/storefront/javascript/index.md b/guides/plugins/plugins/storefront/javascript/index.md index fab26da223..314ecb2ed7 100644 --- a/guides/plugins/plugins/storefront/javascript/index.md +++ b/guides/plugins/plugins/storefront/javascript/index.md @@ -8,9 +8,9 @@ nav: This section explains how to extend and customize the Storefront using JavaScript plugins. It covers creating custom plugins, overriding existing functionality, reacting to events, loading external scripts, and interacting with the Store API. -* [Add Custom Javascript](./add-custom-javascript.md) -* [Add Javascript as Script Tag](./add-javascript-as-script-tag.md) -* [Fetching Data with Javascript](./fetching-data-with-javascript.md) +* [Add Custom JavaScript](./add-custom-javascript.md) +* [Add JavaScript as Script Tag](./add-javascript-as-script-tag.md) +* [Fetching Data with JavaScript](./fetching-data-with-javascript.md) * [Override Existing JavaScript](./override-existing-javascript.md) * [Reacting to JavaScript events](./reacting-to-javascript-events.md) diff --git a/guides/plugins/plugins/storefront/javascript/override-existing-javascript.md b/guides/plugins/plugins/storefront/javascript/override-existing-javascript.md index 12fc6ea0ef..63ac538c52 100644 --- a/guides/plugins/plugins/storefront/javascript/override-existing-javascript.md +++ b/guides/plugins/plugins/storefront/javascript/override-existing-javascript.md @@ -148,4 +148,4 @@ You should see the cookie notice at the bottom of the page. If you click the "Ac ## Next steps -It is sometimes possible to use an event instead of overriding a JavaScript plugin. Read the [listening to events](./reacting-to-javascript-events) guide to learn how. +It is sometimes possible to use an event instead of overriding a JavaScript plugin. Read the [listening to events](./reacting-to-javascript-events.md) guide to learn how. diff --git a/guides/plugins/plugins/storefront/styling/add-custom-assets.md b/guides/plugins/plugins/storefront/styling/add-custom-assets.md index 8b2f9ee446..9a87e07ece 100644 --- a/guides/plugins/plugins/storefront/styling/add-custom-assets.md +++ b/guides/plugins/plugins/storefront/styling/add-custom-assets.md @@ -13,7 +13,7 @@ When working with an own plugin, the usage of own custom images or other assets ## Prerequisites -In order to be able to start with this guide, you need to have an own plugin running. As to most guides, this guide is also built upon the [Plugin base guide](../../plugin-base-guide.md) +In order to be able to start with this guide, you need to have an own plugin running. As to most guides, this guide is also built upon the [Plugin base guide](../../plugin-base-guide.md). Needless to say, you should have your image or another asset at hand to work with. diff --git a/guides/plugins/themes/styling/add-css-js-to-theme.md b/guides/plugins/themes/styling/add-css-js-to-theme.md index 744b80de82..03960779d6 100644 --- a/guides/plugins/themes/styling/add-css-js-to-theme.md +++ b/guides/plugins/themes/styling/add-css-js-to-theme.md @@ -123,5 +123,5 @@ This command starts a NodeJS web server on port `9998`. If you open the Storefro Now that you know how to customize the styling via SCSS and add JavaScript, here is a list of things you can do. -* [Override Bootstrap variables in a theme](override-bootstrap-variables-in-a-theme) +* [Override Bootstrap variables in a theme](override-bootstrap-variables-in-a-theme.md) * [Customize templates](../../plugins/storefront/templates/customize-templates.md) diff --git a/products/digital-sales-rooms/index.md b/products/digital-sales-rooms/index.md index cba80b0bc7..fa5c5fcab9 100644 --- a/products/digital-sales-rooms/index.md +++ b/products/digital-sales-rooms/index.md @@ -30,8 +30,7 @@ Review the below minimum operating requirements before you install the *Digital * [node](https://nodejs.org/en) >= v18 * [pnpm](https://pnpm.io/installation) >= 8 * [Shopware Frontends framework](https://frontends.shopware.com/) based on Nuxt 3. -* Instance of [Shopware 6](../../guides/installation/) (version 6.6.0 and above). - * Recommend installing with [devenv](../../guides/installation/legacy-setups/devenv-setup.md) +* Instance of [Shopware 6](../../guides/installation/index.md) * Third party services: * [Daily.co](https://www.daily.co/) - Refer to setup instructions for [realtime video call](./setup-3rd-party/realtime-video-dailyco.md) * [Mercure](https://mercure.rocks/)- Refer to setup instructions for [realtime Mercure service](./setup-3rd-party/realtime-service-mercure.md) diff --git a/products/paas/shopware-paas/repository.md b/products/paas/shopware-paas/repository.md index 7beccb60b5..d0936bd058 100644 --- a/products/paas/shopware-paas/repository.md +++ b/products/paas/shopware-paas/repository.md @@ -11,7 +11,7 @@ nav: # Repository -The source code of your project will reside in a git-based VCS repository. You can start with a plain project. However, we suggest starting with a new Composer create-project. You will learn more about the setup template in the [Setup Template](setup-template) section. +The source code of your project will reside in a git-based VCS repository. You can start with a plain project. However, we suggest starting with a new Composer create-project. You will learn more about the setup template in the [Setup Template](setup-template.md) section. ::: info This guide explains the repository setup using **GitHub**. You can also integrate Bitbucket or GitLab-based version control environments with Shopware PaaS. Refer to [Source Integrations](https://fixed.docs.upsun.com/integrations/source.html) for more information. diff --git a/resources/references/security.md b/resources/references/security.md index e2f5bc974d..75a90b608c 100644 --- a/resources/references/security.md +++ b/resources/references/security.md @@ -17,7 +17,7 @@ If you have found a security vulnerability in Shopware, please report it to us f ## ACL in the Administration -The Access Control List (ACL) in Shopware ensures that by default, data can only be created, read, updated, or deleted (CRUD), once the user has specific privileges for a module. [ACL in the Administration](../../concepts/framework/architecture/administration-concept#acl-in-the-administration) +The Access Control List (ACL) in Shopware ensures that by default, data can only be created, read, updated, or deleted (CRUD), once the user has specific privileges for a module. [ACL in the Administration](../../concepts/framework/architecture/administration-concept.md#acl-in-the-administration) Issues in the ACL permission validation are generally treated as bugs. They are not considered security vulnerabilities by themselves, as long as the missing or incorrect permission check does not result in privilege escalation, unauthorized access to sensitive data, or similar severe consequences. This is because, in such cases, malicious actors would already need to be authenticated with access to the Administration (or an authenticated Admin API context). @@ -51,7 +51,7 @@ If this is a concern to you, you can disable the whole URL upload feature by set General Data Protection Regulation (GDPR) is a comprehensive European Union (EU) regulation that enhances individuals' privacy rights by imposing strict rules on how organizations collect, process, and protect personal data. For more information, refer to [GDPR](https://docs.shopware.com/en/shopware-6-en/tutorials-and-faq/gdpr) guide. -Shopware provides a comprehensive [Cookie Consent Management](../../concepts/commerce/content/cookie-consent-management) system with features to help shop owners handle customer privacy preferences, ensure transparent cookie handling, and support GDPR compliance efforts. +Shopware provides a comprehensive [Cookie Consent Management](../../concepts/commerce/content/cookie-consent-management.md) system with features to help shop owners handle customer privacy preferences, ensure transparent cookie handling, and support GDPR compliance efforts. ## HTML sanitizer From 82b89f8f81460af178f41048438ea79eb4ec6ddd Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Tue, 12 May 2026 08:31:58 +0200 Subject: [PATCH 27/39] Update guides/hosting/infrastructure/optional-packages.md Co-authored-by: Soner <s.sayakci@shopware.com> --- guides/hosting/infrastructure/optional-packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/hosting/infrastructure/optional-packages.md b/guides/hosting/infrastructure/optional-packages.md index f8bbc1ea52..013c855b75 100644 --- a/guides/hosting/infrastructure/optional-packages.md +++ b/guides/hosting/infrastructure/optional-packages.md @@ -23,7 +23,7 @@ composer require --dev symfony/profiler-pack Install the Platform-as-a-Service integration: ```bash -composer require paas --ignore-platform-req=ext-amqp +composer require shopware/paas-meta --ignore-platform-req=ext-amqp ``` ## Fastly integration From 32a3df628e4dc6b32a3a72f977ae1cdea60bbdc3 Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Tue, 12 May 2026 08:32:25 +0200 Subject: [PATCH 28/39] Update guides/hosting/infrastructure/optional-packages.md Co-authored-by: Soner <s.sayakci@shopware.com> --- guides/hosting/infrastructure/optional-packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/hosting/infrastructure/optional-packages.md b/guides/hosting/infrastructure/optional-packages.md index 013c855b75..2b3ddce12d 100644 --- a/guides/hosting/infrastructure/optional-packages.md +++ b/guides/hosting/infrastructure/optional-packages.md @@ -15,7 +15,7 @@ Extend a project with optional packages as needed. Install Symfony’s profiler and related development tools: ```bash -composer require --dev symfony/profiler-pack +composer require --dev shopware/dev-tools ``` ## PaaS integration From d64d6c037520c339923cb6cc90b19bc00c087e71 Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Tue, 12 May 2026 08:32:42 +0200 Subject: [PATCH 29/39] Update guides/hosting/infrastructure/optional-packages.md Co-authored-by: Soner <s.sayakci@shopware.com> --- guides/hosting/infrastructure/optional-packages.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/hosting/infrastructure/optional-packages.md b/guides/hosting/infrastructure/optional-packages.md index 2b3ddce12d..68854461a5 100644 --- a/guides/hosting/infrastructure/optional-packages.md +++ b/guides/hosting/infrastructure/optional-packages.md @@ -31,5 +31,5 @@ composer require shopware/paas-meta --ignore-platform-req=ext-amqp Install Fastly support: ```bash -composer require fastly +composer require shopware/fastly-meta ``` From 3c68de7c5dc08efdc2b68a73aa9dd5a64e02d92a Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Tue, 12 May 2026 08:33:03 +0200 Subject: [PATCH 30/39] Update guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md Co-authored-by: Soner <s.sayakci@shopware.com> --- guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md b/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md index 7e0052682b..0e85517a37 100644 --- a/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md +++ b/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md @@ -119,7 +119,7 @@ The `update()` method runs when your plugin is updated to a new version. Databas ```php // <plugin root>/src/SwagBasicExample -public function update(UpdateContext $updateContext$context): void +public function update(UpdateContext $context): void { // Update as necessary, rarely database-related } From eb6248b9c19aa253593967e497f38cd8907d15d6 Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Tue, 12 May 2026 08:33:25 +0200 Subject: [PATCH 31/39] Update guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md Co-authored-by: Soner <s.sayakci@shopware.com> --- guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md b/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md index 0e85517a37..42e6f7692f 100644 --- a/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md +++ b/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md @@ -137,7 +137,7 @@ Run [CI](../../../development/testing/ci.md) (static analysis, tests, and reprod ```php // <plugin root>/src/SwagBasicExample -public function postInstall(InstallContext $installContext): void +public function postInstall(InstallContext $context): void { } From b7c371e5428bcb84eb18748247de31548e7562fd Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Tue, 12 May 2026 08:33:39 +0200 Subject: [PATCH 32/39] Update guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md Co-authored-by: Soner <s.sayakci@shopware.com> --- guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md b/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md index 42e6f7692f..2251ba1129 100644 --- a/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md +++ b/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md @@ -141,7 +141,7 @@ public function postInstall(InstallContext $context): void { } -public function postUpdate(UpdateContext $updateContext): void +public function postUpdate(UpdateContext $context): void { } ``` From c92b128f4a4a9c5652077320a7282a95cd44a654 Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Tue, 12 May 2026 08:33:52 +0200 Subject: [PATCH 33/39] Update guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md Co-authored-by: Soner <s.sayakci@shopware.com> --- guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md b/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md index 2251ba1129..eba8a5adb9 100644 --- a/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md +++ b/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md @@ -156,7 +156,7 @@ Do not blindly delete entities your plugin created. For example, if your plugin ```php // <plugin root>/src/SwagBasicExample -public function uninstall(UninstallContext $uninstallContext): void +public function uninstall(UninstallContext $context): void { // Remove or deactivate the data created by the plugin } From 5544e0d655c848adbc450279a55c637bc2fc053b Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Tue, 12 May 2026 08:34:05 +0200 Subject: [PATCH 34/39] Update guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md Co-authored-by: Soner <s.sayakci@shopware.com> --- guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md b/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md index eba8a5adb9..ed433071ee 100644 --- a/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md +++ b/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md @@ -170,7 +170,7 @@ When uninstalling a plugin, you can choose whether to remove all associated plug ```php // <plugin root>/src/SwagBasicExample -public function uninstall(UninstallContext $uninstallContext): void +public function uninstall(UninstallContext $context): void { parent::uninstall($uninstallContext); From 627a645ca04e4311d24987f94bb736f6b0b159af Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Tue, 12 May 2026 08:34:16 +0200 Subject: [PATCH 35/39] Update guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md Co-authored-by: Soner <s.sayakci@shopware.com> --- guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md b/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md index ed433071ee..018c02b292 100644 --- a/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md +++ b/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md @@ -102,7 +102,7 @@ The opposite of `activate()` in most respects. It is executed when the plugin is ```php // <plugin root>/src/SwagBasicExample -public function deactivate(DeactivateContext $deactivateContext): void +public function deactivate(DeactivateContext $context): void { // Deactivate entities, such as a new payment method // Or remove previously created entities From 6bc9e1f396dda27a6faee82d217d15c443e0e1c1 Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Tue, 12 May 2026 08:34:31 +0200 Subject: [PATCH 36/39] Update guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md Co-authored-by: Soner <s.sayakci@shopware.com> --- guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md | 1 - 1 file changed, 1 deletion(-) diff --git a/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md b/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md index 018c02b292..9081957315 100644 --- a/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md +++ b/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md @@ -172,7 +172,6 @@ When uninstalling a plugin, you can choose whether to remove all associated plug // <plugin root>/src/SwagBasicExample public function uninstall(UninstallContext $context): void { - parent::uninstall($uninstallContext); if ($uninstallContext->keepUserData()) { return; From 6732930cf81fbb9ab45be3a39ff4a0d88c160a26 Mon Sep 17 00:00:00 2001 From: somethings <l.apple@shopware.com> Date: Tue, 12 May 2026 08:34:49 +0200 Subject: [PATCH 37/39] Update guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md Co-authored-by: Soner <s.sayakci@shopware.com> --- guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md b/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md index 9081957315..79ffe5ba1f 100644 --- a/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md +++ b/guides/plugins/plugins/plugin-fundamentals/plugin-lifecycle.md @@ -84,7 +84,7 @@ Avoid creating new business data for your plugin in the `install()` method. Crea ```php // <plugin root>/src/SwagBasicExample -public function activate(ActivateContext $activateContext): void +public function activate(ActivateContext $context): void { // Activate entities, such as a new payment method // Or create new entities, because now your plugin is installed and active From 1b163d3ef370c9c62f993618eddc663a922cb555 Mon Sep 17 00:00:00 2001 From: LApple <l.apple@shopware.com> Date: Tue, 12 May 2026 09:00:23 +0200 Subject: [PATCH 38/39] fix: correct theme configuration asset path --- guides/plugins/themes/configuration/theme-configuration.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/guides/plugins/themes/configuration/theme-configuration.md b/guides/plugins/themes/configuration/theme-configuration.md index ea7c417b90..f6dc00e2d3 100644 --- a/guides/plugins/themes/configuration/theme-configuration.md +++ b/guides/plugins/themes/configuration/theme-configuration.md @@ -618,7 +618,7 @@ A custom single-select field example </Tab> </Tabs> -![Example of a custom single-select field](../../../assets/example-single-select-config.png) +![Example of a custom single-select field](../../../../assets/example-single-select-config.png) A custom multi-select field example From 83e20171d5e9c4c6a9cdde7c76c6f14d9715603a Mon Sep 17 00:00:00 2001 From: LApple <l.apple@shopware.com> Date: Tue, 12 May 2026 09:13:29 +0200 Subject: [PATCH 39/39] fix: correct remaining theme asset paths --- guides/plugins/themes/configuration/theme-configuration.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/guides/plugins/themes/configuration/theme-configuration.md b/guides/plugins/themes/configuration/theme-configuration.md index f6dc00e2d3..f8e12a8df8 100644 --- a/guides/plugins/themes/configuration/theme-configuration.md +++ b/guides/plugins/themes/configuration/theme-configuration.md @@ -790,13 +790,13 @@ A custom multi-select field example </Tab> </Tabs> -![Example of a custom multi-select field](../../../assets/example-multi-select-config.png) +![Example of a custom multi-select field](../../../../assets/example-multi-select-config.png) ## Tabs, blocks and sections You can use tabs, blocks and sections to structure and group the config options. -![Example of tabs, blocks and sections](../../../assets/theme-config.png) +![Example of tabs, blocks and sections](../../../../assets/theme-config.png) In the picture above are four tabs. In the "Colours" tab there is one block "Theme colours" which contains two sections named "Important colors" and "Other". You can define the block and section individually for each item. Example: