diff --git a/.gitbook.yaml b/.gitbook.yaml index d8f790ed17..56d73003cc 100644 --- a/.gitbook.yaml +++ b/.gitbook.yaml @@ -98,4 +98,14 @@ redirects: guides/installation/setups/devenv.html: guides/installation/legacy-setups/devenv-setup.html guides/installation/setups/symfony-cli.html: guides/installation/legacy-setups/symfony-cli-setup.html guides/installation/setups/devenv-options.html: guides/installation/legacy-setups/devenv-options.html - guides/installation/setups/: guides/installation/ \ No newline at end of file + guides/installation/setups/: guides/installation/ + guides/plugins/plugins/administration/system-updates/meteor-components.html: guides/upgrades-migrations/administration/meteor-components.html + guides/plugins/plugins/administration/system-updates/pinia.html: guides/upgrades-migrations/administration/pinia.html + guides/plugins/plugins/administration/system-updates/vue3.html: guides/upgrades-migrations/administration/vue3.html + 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 + 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/ + resources/references/upgrades/: guides/upgrades-migrations/ \ No newline at end of file diff --git a/concepts/api/admin-api.md b/concepts/api/admin-api.md index 6bb1cb3553..133aecf370 100644 --- a/concepts/api/admin-api.md +++ b/concepts/api/admin-api.md @@ -1,12 +1,18 @@ --- nav: title: Admin API - position: 20 + position: 60 --- # Admin API +The Admin API represents the administrative and integration surface of Shopware. It enables structured access to core business entities such as products, orders, customers, media, and configurations. It is intended for backend integrations, automation, data synchronization, and system-to-system communication. + +These integrations typically involve structured data exchange, synchronization, imports, exports, and notifications. They prioritize consistency, error handling, validation, and transactional integrity. Performance is also important in terms of high data loads rather than fast response times. + The Admin API provides CRUD operations for every entity within Shopware and is used to build integrations with external systems. -For more information, refer to the [Guides section](../../guides/integrations-api/index.md). +For details on endpoints, authentication methods, schemas, and request formats, always refer to the Admin API documentation. + + diff --git a/concepts/api/index.md b/concepts/api/index.md index c963ca36aa..3ba222ae63 100644 --- a/concepts/api/index.md +++ b/concepts/api/index.md @@ -7,8 +7,17 @@ nav: # API -The Shopware API allows developers to interact with and integrate Shopware with other systems and applications. It provides a set of services that enable developers to perform various operations, such as managing products, customers, orders, and shopping carts.The API supports both read and write operations, allowing developers to retrieve information from Shopware and make modifications or additions to the e-commerce platform. By leveraging the Shopware API, developers can extend the functionality of Shopware, integrate it with external systems, and create seamless experiences for managing and operating online stores. +Shopware exposes HTTP-based APIs that allow external systems and custom applications to interact with the platform. -Shopware supports two major functional APIs: the Store API and the Admin API. These APIs serve different purposes. The Store API is designed to interact with the front-end or storefront of a Shopware online store while the Admin API is intended for administrative operations related to managing the back-end of the Shopware platform. +Two functional APIs are available, each representing a different integration surface: -The API documentation provides details on the available endpoints, request/response formats, authentication mechanisms, and data structures. It supports different authentication methods, including token-based authentication and OAuth 2.0, to ensure secure communication between the API client and the Shopware platform. +* **Store API**: customer-facing interactions +* **Admin API**: administrative and system-level operations + +Both APIs use HTTP and exchange JSON payloads. The Administration API requires OAuth 2.0 authentication, whereas the Store API is publicly accessible and only requires contextual headers, with authentication needed for customer-specific endpoints. While they serve different purposes within the platform, they share some underlying design principles and structural patterns: + +* Search criteria abstraction for filtering, sorting, and pagination +* Structured JSON request/response bodies +* Header-based contextual behavior + +These patterns form the foundation of integration development. diff --git a/concepts/api/store-api.md b/concepts/api/store-api.md index 4fd48be32d..f15e5ad168 100644 --- a/concepts/api/store-api.md +++ b/concepts/api/store-api.md @@ -1,35 +1,17 @@ --- nav: title: Store API - position: 10 + position: 50 --- # Store API -Every interaction between the store and a customer can be modeled using the Store API. It serves as a normalized layer or an interface to communicate between customer-facing applications and the Shopware Core. It can be used to build custom frontends like SPAs, native apps, or simple catalog apps. It doesn't matter what you want to build as long as you are able to consume a JSON API via HTTP. +The Store API represents the customer-facing surface of Shopware. It is designed for storefront/frontend-related interactions such as product browsing, cart handling, checkout, and customer account management. It exposes only data that is relevant and safe for frontend use and supports both anonymous and authenticated customers. -![Data and logic flow in Shopware 6 \(top to bottom and vice versa\)](../../assets/concepts-api-storeApiLogic.svg) +The Store API acts as a normalized interface layer between customer-facing applications and the Shopware Core. It enables headless frontends (such as SPAs or native apps) to consume Shopware functionality via JSON over HTTP. Core business logic is exposed through HTTP routes, ensuring that the Storefront and API consumers rely on the same underlying services. -Whenever additional logic is added to Shopware, the method of the corresponding service is exposed via a dedicated HTTP route. At the same time, it can be programmatically used to provide data to a controller or other services in the stack. This way, you can ensure that there is always common logic between the API and the Storefront and almost no redundancy. It also allows us to build core functionalities into our Storefront without compromising support for our API consumers. +For details on endpoints, authentication methods, schemas, and request formats, always refer to the Store API documentation. + -## Extensibility - -Using plugins, you can add custom routes to the Store API \(as well as any other routes\) and also register custom services. We don't force developers to provide API coverage for their functionalities. However, if you want to support headless applications, ensure that your plugin provides its functionalities through dedicated routes. - - - -## Store API and the traditional TWIG storefront - -When using the server-side rendered TWIG storefront, the Store API is not used. -Instead, the storefront uses custom [storefront controllers](../../guides/plugins/plugins/storefront/add-custom-controller.md) which internally use the Store API to fetch data. - -The storefront controllers are optimized for the usage in our TWIG storefront. And the biggest difference is the way that authentication and authorization are handled. -As the Store-API is a proper REST API, the main design is stateless, which means authentication info needs to be provided via the request headers in form of the `sw-context-token`. -The storefront relies on the session to store the authentication info, that way you do not have to handle the authentication manually with every request. - -## What next? - -* To start working with the Store API, check out our [Quick Start guide](https://shopware.stoplight.io/docs/store-api/38777d33d92dc-quick-start-guide) and explore all endpoints in our reference guide. - -* An interesting project based on the Store API is [Composable Frontends](../../../frontends/). +Shopware provides [Composable Frontends](https://frontends.shopware.com/) as a headless frontend implementation based on the Store API. diff --git a/concepts/framework/architecture/index.md b/concepts/framework/architecture/index.md index 35e8b3701a..de4d2b0b24 100644 --- a/concepts/framework/architecture/index.md +++ b/concepts/framework/architecture/index.md @@ -5,6 +5,36 @@ nav: --- -# Architecture +# Shopware Architecture -On a high level, Shopware consists of multiple modules that separate the entire code base into logical units. Some modules are independent, and some depend on others. +Shopware follows a modular, API-first architecture built on top of Symfony and modern frontend technologies. The platform separates concerns into clearly defined layers, allowing storefront experiences, administrative tooling, and core business logic to evolve independently while sharing a common backend foundation. + +At a high level, the system consists of three primary domains: + +* **Core** — the backend foundation containing business logic, data abstraction, APIs, and extension mechanisms. +* **Storefront** — the customer-facing presentation layer responsible for rendering sales channels and interacting with the Store API. +* **Administration** — the management interface used by merchants and operators to configure, manage, and operate the platform. + +These domains are unified through a shared API layer and a consistent plugin system, enabling extensibility without tightly coupling features to presentation layers. + +## Architectural principles + +The Shopware architecture is guided by several core principles: + +* **API-first design** — all functionality is exposed via APIs, enabling headless and composable commerce scenarios. +* **Separation of concerns** — frontend experiences (storefront/admin) are decoupled from backend logic. +* **Extensibility** — plugins integrate through events, services, and extension points rather than modifying core code. +* **Asynchronous processing** — background tasks (indexing, messaging, integrations) are handled via message queues and workers. +* **Domain-driven structure** — business logic is organized around commerce domains rather than UI features. + +## Core components + +The architecture centers around the Shopware Core, which provides: + +* Data Abstraction Layer (DAL) for database interaction +* Business services and domain logic +* Sales Channel and Store APIs +* Plugin and event system +* Messaging and scheduled task infrastructure + +The Storefront and Administration layers consume these services rather than duplicating logic, ensuring consistency across channels. diff --git a/concepts/framework/architecture/storefront-concept.md b/concepts/framework/architecture/storefront-concept.md index 3e08bab3c6..9fc91a3446 100644 --- a/concepts/framework/architecture/storefront-concept.md +++ b/concepts/framework/architecture/storefront-concept.md @@ -1,7 +1,7 @@ --- nav: title: Storefront - position: 10 + position: 15 --- @@ -32,11 +32,21 @@ The main concerns that the Storefront component has are listed below. Furthermor Contrary to API calls that result in single resource data, a whole page in the Storefront displays multiple different data sets on a single page. Think of partials, which lead to a single page being displayed. Imagine a page that displays the order overview in the customer account environment. There are partials that are generic and will be displayed on almost every Page. These partials include - for example, Header and Footer information wrapped into a `GenericPage` as `Pagelets` \(`HeaderPagelet`, `FooterPagelet`\). This very generic Page will later be enriched with the specific information you want to display through a separate loader \(e.g. a list of orders\). -To achieve getting information from a specific resource, the Storefront's second concern is to map requests to the Core. Internally, the Storefront makes use of the [Store API](../../api/store-api) routes to enrich the Page with additional information, e.g., a list of orders, which is being fetched through the order route. Once all needed information is added to the Page, the corresponding page loader returns the Page to a Storefront controller. +To obtain information from a specific resource, the Storefront's second concern is to map requests to the Core. Internally, the Storefront makes use of the [Store API](https://shopware.stoplight.io/docs/store-api/38777d33d92dc-quick-start-guide) routes to enrich the Page with additional information, e.g., a list of orders, which is being fetched through the order route. + +![Data and logic flow in Shopware 6 \(top to bottom and vice versa\)](../../../assets/concepts-api-storeApiLogic.svg) + +Once all needed information is added to the Page, the corresponding page loader returns the Page to a Storefront controller. + +### Store API and the traditional Twig storefront + +In the traditional server-side rendered Twig storefront, the Store API is not called directly by the browser. Instead, custom storefront controllers internally use the Store API to fetch data from the Core. + +The Store API is stateless and expects authentication information via request headers (for example the `sw-context-token`). In contrast, the traditional storefront relies on session-based authentication, so authentication does not need to be handled manually on every request. Contrary to the Core, which can almost completely omit templating in favor of JSON responses, the Storefront contains a rich set of Twig templates to display a fully functional shop. Another concern of the Storefront is to provide templating with Twig. The page object, which was enriched beforehand, will later be passed to a specific Twig page template throughout a controller. A more detailed look into an example can be found in [Composite data handling](storefront-concept#composite-data-handling). -Last but not least, the Storefront not only contains static templates but also includes a theming engine to modify the rendered templates or change the default layout programmatically with your own [Themes](../../../guides/plugins/themes/) or [Plugins](storefront-concept). +Last but not least, the Storefront not only contains static templates but also includes a theming engine to modify the rendered templates or change the default layout programmatically with your own [Themes](../../../guides/plugins/themes/) or [Plugins](../../../guides/plugins/plugins/). ## Structure diff --git a/guides/upgrades-migrations/administration/index.md b/guides/upgrades-migrations/administration/index.md new file mode 100644 index 0000000000..4fb462c566 --- /dev/null +++ b/guides/upgrades-migrations/administration/index.md @@ -0,0 +1,17 @@ +--- +nav: + title: Administration + position: 10 + +--- + +# Administration + +These guides cover upcoming architectural changes and migration paths affecting Administration extensions. Use them to prepare plugins for major system transitions: + +* [Vue 3 migration](./vue3) +* [Meteor components](./meteor-components) +* [Pinia migration](./pinia) +* [Vite migration](./vite) +* [Vue migration build removal](./vue-migration-build) +* [Native Vue implementation](./vue-native) diff --git a/guides/plugins/plugins/administration/system-updates/meteor-components.md b/guides/upgrades-migrations/administration/meteor-components.md similarity index 93% rename from guides/plugins/plugins/administration/system-updates/meteor-components.md rename to guides/upgrades-migrations/administration/meteor-components.md index d93dab20af..8c03c01858 100644 --- a/guides/plugins/plugins/administration/system-updates/meteor-components.md +++ b/guides/upgrades-migrations/administration/meteor-components.md @@ -1,15 +1,15 @@ --- nav: title: Upgrading to Meteor Components - position: 260 + position: 11 --- # Future Development Roadmap: Upgrading to Meteor Components -> **Note:** The information provided in this article, including timelines and specific implementations, is subject to change. -> This document serves as a general guideline for our development direction. - -## Introduction +:::info +The information provided in this article, including timelines and specific implementations, is subject to change. +This document serves as a general guideline for our development direction. +::: With the release of Shopware 6.7, we will replace several current administration components with components from the [Meteor Component Library](https://meteor-component-library.vercel.app/). diff --git a/guides/plugins/plugins/administration/system-updates/pinia.md b/guides/upgrades-migrations/administration/pinia.md similarity index 99% rename from guides/plugins/plugins/administration/system-updates/pinia.md rename to guides/upgrades-migrations/administration/pinia.md index 9e45a5d6a5..9ccd31dc47 100644 --- a/guides/plugins/plugins/administration/system-updates/pinia.md +++ b/guides/upgrades-migrations/administration/pinia.md @@ -1,13 +1,11 @@ --- nav: title: Upgrading to Pinia - position: 261 + position: 12 --- # Migration from Vuex in Shopware to Pinia -## Introduction - With the release of Shopware 6.7, we will replace Vuex with [Pinia](https://pinia.vuejs.org/) as the state management library for the administration. ## Why Pinia? diff --git a/guides/plugins/plugins/administration/system-updates/vite.md b/guides/upgrades-migrations/administration/vite.md similarity index 97% rename from guides/plugins/plugins/administration/system-updates/vite.md rename to guides/upgrades-migrations/administration/vite.md index ae20f20183..ec8ff9a799 100644 --- a/guides/plugins/plugins/administration/system-updates/vite.md +++ b/guides/upgrades-migrations/administration/vite.md @@ -1,15 +1,15 @@ --- nav: title: Changing from Webpack to Vite - position: 260 + position: 13 --- # Future Development Roadmap: Changing from Webpack to Vite -> **Note:** The information provided in this article, including timelines and specific implementations, is subject to change. -> This document serves as a general guideline for our development direction. - -## Introduction +:::info +The information provided in this article, including timelines and specific implementations, is subject to change. +This document serves as a general guideline for our development direction. +::: We are planning substantial changes to the way we build our Vue.js application. The current Webpack build system has been in place for quite some time now, but like everything in tech, it becomes outdated sooner than later. Additionally to Webpack being slow and outdated, we identified a security risk for the future of our application. Many Webpack maintainers have moved on to other projects. Therefore, the Webpack project no longer receives significant updates. The same applies to the Webpack loaders we currently use. diff --git a/guides/plugins/plugins/administration/system-updates/vue-migration-build.md b/guides/upgrades-migrations/administration/vue-migration-build.md similarity index 95% rename from guides/plugins/plugins/administration/system-updates/vue-migration-build.md rename to guides/upgrades-migrations/administration/vue-migration-build.md index ecdbbe522d..be16d7579c 100644 --- a/guides/plugins/plugins/administration/system-updates/vue-migration-build.md +++ b/guides/upgrades-migrations/administration/vue-migration-build.md @@ -1,15 +1,15 @@ --- nav: title: Removing Vue Migration Build - position: 260 + position: 14 --- # Future Development Roadmap: Removing Vue Migration Build -> **Note:** The information provided in this article, including timelines and specific implementations, is subject to change. -> This document serves as a general guideline for our development direction. - -## Introduction +:::info +The information provided in this article, including timelines and specific implementations, is subject to change. +This document serves as a general guideline for our development direction. +::: Prior to Shopware 6.7, we utilized the Vue migration build to facilitate the transition from Vue 2 to Vue 3 for plugin developers. This approach allowed most public APIs to behave similarly to Vue 2 while enabling gradual migration. diff --git a/guides/plugins/plugins/administration/system-updates/vue-native.md b/guides/upgrades-migrations/administration/vue-native.md similarity index 97% rename from guides/plugins/plugins/administration/system-updates/vue-native.md rename to guides/upgrades-migrations/administration/vue-native.md index 99f2594b45..42ec3be1ab 100644 --- a/guides/plugins/plugins/administration/system-updates/vue-native.md +++ b/guides/upgrades-migrations/administration/vue-native.md @@ -1,13 +1,15 @@ --- nav: title: Native Vue - position: 260 + position: 15 --- # Future Development Roadmap: Moving Towards Vue Native -> **Note:** The information provided in this article, including timelines and specific implementations, is subject to change. -> This document serves as a general guideline for our development direction. +:::info +The information provided in this article, including timelines and specific implementations, is subject to change. +This document serves as a general guideline for our development direction. +::: ## Introduction diff --git a/resources/references/upgrades/administration/vue3.md b/guides/upgrades-migrations/administration/vue3.md similarity index 99% rename from resources/references/upgrades/administration/vue3.md rename to guides/upgrades-migrations/administration/vue3.md index 4fcb3c1dfb..e387597226 100644 --- a/resources/references/upgrades/administration/vue3.md +++ b/guides/upgrades-migrations/administration/vue3.md @@ -5,9 +5,7 @@ nav: --- -# Vue 3 upgrade - -## Introduction +# Vue 3 Upgrade The Shopware administration uses Vue.js `2`, which will reach its end of life (EOL) **on December 31st 2023**. To deliver up-to-date and maintainable software, the administration will use Vue.js `3` from Shopware version `6.6` and upwards. If you are unfamiliar with the changes from Vue.js `2` to Vue.js `3`, please refer to this [official guide](https://v3-migration.vuejs.org/). diff --git a/resources/references/upgrades/core/translation/extension-translation.md b/guides/upgrades-migrations/extension-translation.md similarity index 94% rename from resources/references/upgrades/core/translation/extension-translation.md rename to guides/upgrades-migrations/extension-translation.md index ff25abbddd..3c1cb1bf6d 100644 --- a/resources/references/upgrades/core/translation/extension-translation.md +++ b/guides/upgrades-migrations/extension-translation.md @@ -23,10 +23,10 @@ The snippet loading system now follows this resolution order: When a translation key is requested, Shopware will: -- First check the specific country variant (e.g., `es-AR`) -- If not found, check the base language (e.g., `es`) -- If not found, the legacy fallback will be checked (`en-GB`) -- Finally, fall back to `en` if still not found +* First check the specific country variant (e.g., `es-AR`) +* If not found, check the base language (e.g., `es`) +* If not found, the legacy fallback will be checked (`en-GB`) +* Finally, fall back to `en` if still not found **Result**: ~90% reduction in duplicate translations while maintaining full functionality. diff --git a/guides/upgrades-migrations/index.md b/guides/upgrades-migrations/index.md new file mode 100644 index 0000000000..a633a2de46 --- /dev/null +++ b/guides/upgrades-migrations/index.md @@ -0,0 +1,78 @@ +--- +nav: + title: Upgrades and Migrations + position: 10 + +--- + +# Version Upgrades and Migrations + +This section covers version-based upgrades and required migration effort for Shopware core and extensions. When upgrading to a new minor or major Shopware version, review it to understand breaking changes, required adjustments, and compatibility requirements. + +## Scope of this section + +Upgrades typically fall into one of these categories: + +* **Core**: Framework-level changes, data abstraction layer (DAL) updates, APIs, feature removals, and backend behavior. +* **[Administration](administration/index.md)**: frontend framework upgrades, Vue upgrades, breaking changes. +* **Translations**: [Extension translation](extension-translation), [Language pack migration](./language-pack-migration). +* **Extensions**: Version compatibility and required refactorings. + +:::info +Administration framework upgrades (Vue, Pinia, Vite, Meteor) may introduce breaking changes requiring major version updates for affected plugins. +::: + +## Upgrade strategy for extension developers + +To reduce long-term upgrade cost: + +* Avoid internal APIs and undocumented features +* Avoid unstable Admin patterns (`this.$parent`, prop mutation, Vue internals) +* Keep dependencies aligned with Shopware core +* Maintain automated test coverage +* Keep database migrations idempotent +* Track deprecations continuously—do not batch them + +## Typical upgrade workflow + +When targeting a new Shopware version: + +1. Review [release notes](https://www.shopware.com/de/changelog/) and UPGRADE files +2. Check breaking changes per layer (Core / Admin / Storefront / API) +3. Validate extension compatibility +4. Apply required migrations +5. Rebuild Admin/Storefront assets if needed +6. Test critical flows +7. Update extension versions if required + +## Extension responsibilities + +### Custom projects + +* Follow the ([Performing updates guide](../hosting/installation-updates/performing-updates.md)) to stage, test, and execute upgrades in order. +* Review [RELEASE_INFO](https://github.com/shopware/shopware/blob/trunk/RELEASE_INFO-6.7.md) and UPGRADE files ([example](https://github.com/shopware/shopware/blob/trunk/UPGRADE-6.7.md)) per release. +* Script data migrations and cache warm-ups. +* Use feature toggles or maintenance mode to decouple risky changes from the deployment. + +### Custom plugins + +* Provide migration code for schema/config changes. +* Ship defaults that work on older core versions until you deliberately drop support. +* Test against the target Shopware version matrix before rollout; note breaking changes in the plugin README. + +### Store plugins + +* Align Store metadata (compatibility range, changelog) with the tested core versions; refuse installation on unsupported versions. +* Run Shopware Store validation on the new build before submission ([Store submission via CLI](../../products/cli/shopware-account-commands/releasing-extension-to-shopware-store.md)). +* Communicate BC breaks explicitly. +* Prefer additive changes and feature flags to keep existing shops stable. + +### Apps + +* Version manifests carefully. Broaden compatibility only after testing, and narrow it when deprecations apply. +* Keep webhook/action handlers tolerant to new fields and events. Avoid hard coupling to specific core patch behavior. +* Document required scopes/permissions per version and avoid removing scopes without a migration path. + +## Next steps + +For the operational update procedure, continue with [Upgrade Shopware](./upgrade-shopware.md). diff --git a/resources/references/upgrades/core/translation/language-pack-migration.md b/guides/upgrades-migrations/language-pack-migration.md similarity index 96% rename from resources/references/upgrades/core/translation/language-pack-migration.md rename to guides/upgrades-migrations/language-pack-migration.md index bc4c3e92dc..2dbc9779d1 100644 --- a/resources/references/upgrades/core/translation/language-pack-migration.md +++ b/guides/upgrades-migrations/language-pack-migration.md @@ -13,7 +13,7 @@ Starting with Shopware **6.7.3.0**, translations are managed directly in Shopwar - **From Shopware 6.7.3.0 onward** - - Translations can be installed via Shopware itself, the [Language Pack plugin][language-pack-plugin] is not required to fetch the + - Translations can be installed via Shopware itself. The [Language Pack plugin][language-pack-plugin] is not required to fetch the newest [Shopware translations][shopware-translations]. - A new CLI command is available: @@ -22,7 +22,7 @@ Starting with Shopware **6.7.3.0**, translations are managed directly in Shopwar ``` - The [Language Pack plugin][language-pack-plugin] still works but is not recommended. -- Languages now have an active flag which can be toggled in the Administration under `Settings → Languages` +- Languages now have an active flag which can be toggled in the Administration under `Settings → Languages`. - Languages installed/managed from other sources do not need to register their locales in the admin anymore. - **Other translation plugins or snippets in themes are not affected and can still be used alongside the integrated handling.** @@ -39,7 +39,7 @@ Starting with Shopware **6.7.3.0**, translations are managed directly in Shopwar - Nothing changes. - To install additional languages, use the CLI command: -```bash +```bash bin/console translation:install --locales ``` @@ -47,7 +47,7 @@ Example: `bin/console translation:install --locales it-IT,fr-FR` will install It ### 2. You are **currently using the Language Pack plugin** -1. Run the translation command and install every language you are using in your shop +1. Run the translation command and install every language you are using in your shop: ```bash bin/console translation:install --locales , diff --git a/guides/upgrades-migrations/upgrade-shopware.md b/guides/upgrades-migrations/upgrade-shopware.md new file mode 100644 index 0000000000..2ac9778005 --- /dev/null +++ b/guides/upgrades-migrations/upgrade-shopware.md @@ -0,0 +1,78 @@ +--- +nav: + title: Upgrade Shopware + position: 10 +--- + +# Upgrade Shopware + +This guide explains how to update an existing Shopware installation using Composer. + +For maintaining custom plugins or apps, review the [Upgrades and Migrations](../upgrades-migrations/index.md) guide before performing updates. + +## Standard update process + +Shopware updates can be executed via Composer or with the web-based updater in the Administration panel. + +### 1. Enable maintenance mode + +```bash +bin/console sales-channel:maintenance:enable --all +``` + +### 2. Update Composer dependencies + +Before running the update, adjust the required Shopware version in `composer.json` to the version to be installed. When using the Commercial plugin, update the `shopware/commercial` requirement to a compatible version as well. + +Failure to change these version constraints means that running the update command will resolve to the currently installed Shopware version and no actual upgrade will happen. + +After adjusting the version constraints, update all Composer packages without executing scripts: + +```bash +composer update --no-scripts +``` + +The `--no-scripts` flag instructs Composer to avoid running any scripts that may reference Shopware CLI commands. These commands will only work after updated recipes are installed. + +### 3. Update Symfony recipes (optional but recommended) + +To force-update all configuration files managed by Symfony Flex: + +```bash +composer recipes:update +``` + +Review changes carefully before committing them. + +### 4. Finalize the update + +Complete the update by running: + +```bash +bin/console system:update:finish +``` + +This command applies all required update routines for the newly installed Shopware version, including running database migrations, and recompiling themes with the latest code. + +After the update process has finished successfully, disable maintenance mode separately: + +```bash +bin/console sales-channel:maintenance:disable --all +``` + +## Operational best practices + +* Automate pre-upgrade checks (PHP/DB versions, extensions, disk space). +* Always test upgrades on staging with production-like data. +* Keep verified database backups and a recovery plan. +* Review changelogs and UPGRADE files before applying changes. +* Track deprecations early and use official tooling (Rector, Administration codemods referenced in [Performing updates](../hosting/installation-updates/performing-updates.md)) to reduce manual work. +* Avoid skipping major versions. +* Commit the `composer.lock` file. +* Run post-upgrade smoke tests. + +## After the update + +* Clear caches if necessary +* Rebuild Administration and Storefront assets if required +* Test critical business flows (checkout, login, API integrations) diff --git a/resources/references/upgrades/administration/index.md b/resources/references/upgrades/administration/index.md deleted file mode 100644 index ce7b1d6f0a..0000000000 --- a/resources/references/upgrades/administration/index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -nav: - title: Administration - position: 10 - ---- - -# Administration - -This section contains all upgrade guides related to the Shopware Administration. diff --git a/resources/references/upgrades/core/index.md b/resources/references/upgrades/core/index.md deleted file mode 100644 index e5d404a66e..0000000000 --- a/resources/references/upgrades/core/index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -nav: - title: Core - position: 20 - ---- - -# Core upgrade and migration guides - -This section contains all upgrade and migration guides related to the Shopware Core. diff --git a/resources/references/upgrades/core/translation/index.md b/resources/references/upgrades/core/translation/index.md deleted file mode 100644 index 98cfc5a4e8..0000000000 --- a/resources/references/upgrades/core/translation/index.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -nav: - title: Translation - position: 10 - ---- - -# Update And Migration Guides For Translations In The Shopware Core - -This section contains all upgrade and migration guides related to translations in the Shopware Core. diff --git a/resources/references/upgrades/index.md b/resources/references/upgrades/index.md deleted file mode 100644 index 023adeb784..0000000000 --- a/resources/references/upgrades/index.md +++ /dev/null @@ -1,11 +0,0 @@ ---- -nav: - title: Upgrades and Migrations - position: 50 - ---- - -# Upgrades and Migrations - -Software projects typically undergo changes and upgrades, for Shopware this is not different. -This section provides you with comprehensive update guides for specific technical changes.