From 71646feec898d856afc3eb550252b50c7e1a816d Mon Sep 17 00:00:00 2001 From: Malte Janz Date: Thu, 17 Sep 2026 11:13:17 +0200 Subject: [PATCH 1/5] chore: adjust shopware-cli and deployment-helper configuration file locations --- guides/development/dev-environment.md | 34 ++++++++-------- .../creating-a-staging-instance.md | 2 +- .../deployment-helper/configuration.md | 16 ++++---- .../deployment-helper/environment.md | 12 +++--- .../deployment-helper/extensions.md | 6 +-- .../deployments/deployment-helper/hosting.md | 4 +- .../deployment-helper/reference.md | 8 ++-- .../deployments/deployment-helper/staging.md | 6 +-- .../deployments/deployment-helper/store.md | 2 +- .../deployment-helper/troubleshooting.md | 6 +-- .../extension-management.md | 2 +- guides/plugins/plugins/bundle.md | 5 ++- .../shopware/get-started/prepare-codebase.md | 2 +- products/tools/cli/configuration.md | 39 +++++++++++++++++++ .../tools/cli/extension-commands/build.md | 22 +++++------ .../cli/extension-commands/configuration.md | 6 +-- .../extension-commands/extract-meta-data.md | 4 +- products/tools/cli/project-commands/build.md | 18 ++++----- .../cli/project-commands/dev-environment.md | 6 +-- .../cli/project-commands/helper-commands.md | 8 ++-- .../tools/cli/project-commands/image-proxy.md | 8 ++-- .../tools/cli/project-commands/mysql-dump.md | 16 ++++---- .../remote-extension-management.md | 4 +- .../updating-store-page.md | 8 ++-- products/tools/cli/validation.md | 8 ++-- 25 files changed, 146 insertions(+), 106 deletions(-) create mode 100644 products/tools/cli/configuration.md diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index f2d9e86671..f8451c91af 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -10,7 +10,7 @@ nav: Shopware CLI provides a fully integrated Docker-based development environment. A single command launches your entire stack, streams logs, manages watchers, and lets you configure PHP and profiling - all without manually editing Docker files. :::info -The development environment requires a compatibility date of `2026-03-01` or later in your `.shopware-project.yml`. Projects created with `shopware-cli project create` have this set automatically. +The development environment requires a compatibility date of `2026-03-01` or later in your `.config/shopware-project.yml`. Projects created with `shopware-cli project create` have this set automatically. See the [Shopware CLI configuration file lookup priority](../../products/tools/cli/configuration.md) for the preferred path and legacy fallbacks. ::: ## Starting the environment @@ -78,7 +78,7 @@ The following table lists the settings you can change in the Config tab: | **PHP Version** | `8.2`, `8.3`, `8.4`, `8.5` | | **Profiler** | `none`, `xdebug`, `blackfire`, `tideways`, `pcov`, `spx` | -When selecting `blackfire` or `tideways`, additional credential fields appear. Sensitive credentials are stored in `.shopware-project.local.yml` (excluded from version control). +When selecting `blackfire` or `tideways`, additional credential fields appear. Sensitive credentials are stored in `.config/shopware-project.local.yml` (excluded from version control). :::info The profiler is now configured via the Config tab. @@ -92,7 +92,7 @@ If your project was created before March 2026 and uses the older `make up`/`make ### What triggers the wizard -The wizard appears when your project's `compatibility_date` in `.shopware-project.yml` is before `2026-03-01` (or missing entirely). This signals that the project hasn't been configured for the new development environment yet. +The wizard appears when your project's `compatibility_date` in `.config/shopware-project.yml` is before `2026-03-01` (or missing entirely). This signals that the project hasn't been configured for the new development environment yet. ### What the wizard does @@ -100,12 +100,12 @@ Walking through the setup wizard takes about a minute. Here's what happens at ea 1. **Welcome** - explains what the wizard will do and asks you to proceed 2. **Admin user** - pre-fills `admin` (you can change it) for the Shopware admin account -3. **Admin password** - pre-fills `shopware` (you can change it); stored as credentials in `.shopware-project.yml` +3. **Admin password** - pre-fills `shopware` (you can change it); stored as credentials in `.config/shopware-project.yml` 4. **PHP version** - reads your `composer.lock` to determine compatible PHP versions and offers the highest supported one as the default (e.g., `8.5`) After you confirm, the wizard: -- Sets `compatibility_date` to `2026-03-01` in `.shopware-project.yml` +- Sets `compatibility_date` to `2026-03-01` in `.config/shopware-project.yml` - Adds a `local` environment with type `docker` and your chosen URL/credentials - Configures the Docker PHP version - Generates a new `compose.yaml` tailored to your project's dependencies @@ -113,13 +113,13 @@ After you confirm, the wizard: ### What happens to existing files -| File | What changes | -| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | -| `.shopware-project.yml` | Updated with `compatibility_date`, `environments`, and `docker` config | -| `.shopware-project.local.yml` | Created if you chose a profiler with credentials (Blackfire, Tideways) | -| `compose.yaml` | **Replaced** with the CLI-managed version - your old file is overwritten, so back it up first and move any customizations to `compose.override.yaml` | -| `Makefile` | **Not touched** - you can delete it once you've migrated, or keep it around | -| `composer.json` | If `shopware/deployment-helper` isn't already present, it's added to `require` | +| File | What changes | +| ------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------- | +| `.config/shopware-project.yml` | Updated with `compatibility_date`, `environments`, and `docker` config | +| `.config/shopware-project.local.yml` | Created if you chose a profiler with credentials (Blackfire, Tideways) | +| `compose.yaml` | **Replaced** with the CLI-managed version - your old file is overwritten, so back it up first and move any customizations to `compose.override.yaml` | +| `Makefile` | **Not touched** - you can delete it once you've migrated, or keep it around | +| `composer.json` | If `shopware/deployment-helper` isn't already present, it's added to `require` | ### After the wizard completes @@ -273,7 +273,7 @@ The compose file inspects your `composer.lock` at generation time: ## Environment executors -The CLI abstracts command execution across environment types, configured per environment in `.shopware-project.yml`: +The CLI abstracts command execution across environment types, configured per environment in `.config/shopware-project.yml`: | Type | Behavior | | ------------- | -------------------------------------------------------------------- | @@ -308,7 +308,7 @@ The web container exposes these ports by default: ## Configuration reference -### `.shopware-project.yml` +### `.config/shopware-project.yml` ```yaml compatibility_date: '2026-03-01' @@ -332,9 +332,9 @@ environments: Shop URL and Admin API credentials belong under `environments` (an empty `-e`/`--env` defaults to `environments.local`). Top-level `url` and `admin_api` keys are deprecated: existing config files that still use them keep working and log a deprecation warning, but `project create` and `project config init` only write `environments.local`. -### `.shopware-project.local.yml` +### `.config/shopware-project.local.yml` -Sensitive credentials are stored in `.shopware-project.local.yml` (add to `.gitignore`): +Sensitive credentials are stored in `.config/shopware-project.local.yml` (add to `.gitignore`): ```yaml docker: @@ -432,7 +432,7 @@ If you must run Composer on the host, raise CLI `memory_limit` to at least `512M ### Compatibility date error -Set `compatibility_date: '2026-03-01'` in `.shopware-project.yml`. For more context, see the [build command docs](../../products/tools/cli/project-commands/build.md#compatibility-date). +Set `compatibility_date: '2026-03-01'` in `.config/shopware-project.yml`. For more context, see the [build command docs](../../products/tools/cli/project-commands/build.md#compatibility-date). ## Next steps diff --git a/guides/hosting/installation-updates/creating-a-staging-instance.md b/guides/hosting/installation-updates/creating-a-staging-instance.md index cab669b885..22ec26ac99 100644 --- a/guides/hosting/installation-updates/creating-a-staging-instance.md +++ b/guides/hosting/installation-updates/creating-a-staging-instance.md @@ -65,7 +65,7 @@ shopware-cli project dump --clean --host localhost --username db_user --password shopware-cli project dump --clean --anonymize --host localhost --username db_user --password db_pass --output shop.sql shopware ``` -Configure the dump command with `.shopware-project.yml` to specify tables to skip, additional anonymization fields, and more. See the [CLI documentation](../../../products/tools/cli/project-commands/mysql-dump.md) for details. +Configure the dump command with `.config/shopware-project.yml` to specify tables to skip, additional anonymization fields, and more. See the [CLI documentation](../../../products/tools/cli/project-commands/mysql-dump.md) for details. ### 3. Configuring the staging instance diff --git a/guides/hosting/installation-updates/deployments/deployment-helper/configuration.md b/guides/hosting/installation-updates/deployments/deployment-helper/configuration.md index f7dc01e450..8a28affb35 100644 --- a/guides/hosting/installation-updates/deployments/deployment-helper/configuration.md +++ b/guides/hosting/installation-updates/deployments/deployment-helper/configuration.md @@ -7,7 +7,7 @@ nav: # Deployment Helper Configuration -The Deployment Helper can be configured via a `.shopware-project.yml` file in the root of your project. Configure only the keys you use. Every section is optional. +The Deployment Helper can be configured via a `.config/shopware-project.yml` file in the root of your project. Configure only the keys you use. Every section is optional. See the [Shopware CLI configuration file lookup priority](../../../../../products/tools/cli/configuration.md) for the preferred path and legacy fallbacks. ## Basic configuration @@ -238,7 +238,7 @@ This significantly speeds up deployment for shops with many sales channels. ## OpenSearch index creation on install -The `opensearch.index-on-install` key controls whether OpenSearch indexes are created automatically right after a fresh installation. When creating a new Shopware PaaS project with `shopware-cli project create --deployment shopware-paas`, the generated `.shopware-project.yml` sets this to `true` so OpenSearch indexing is enabled from the first deployment. For other deployment targets, the key defaults to `false` and can be enabled manually if needed: +The `opensearch.index-on-install` key controls whether OpenSearch indexes are created automatically right after a fresh installation. When creating a new Shopware PaaS project with `shopware-cli project create --deployment shopware-paas`, the generated `.config/shopware-project.yml` sets this to `true` so OpenSearch indexing is enabled from the first deployment. For other deployment targets, the key defaults to `false` and can be enabled manually if needed: ```yaml deployment: @@ -248,16 +248,16 @@ deployment: ## Local configuration overrides -You can create a `.shopware-project.local.yml` file alongside your `.shopware-project.yml` to override configuration values for local development without modifying the base config. This file should be added to your `.gitignore`. +You can create a `.config/shopware-project.local.yml` file alongside your `.config/shopware-project.yml` to override configuration values for local development without modifying the base config. This file should be added to your `.gitignore`. The local file is deep-merged on top of the base configuration: - **Scalar values** (strings, numbers) are replaced by the local value. - **Maps** (associative arrays) are deep-merged recursively. -- **Lists** (indexed arrays): for each list-valued key, the list from `.shopware-project.local.yml` is appended to the end of the list from `.shopware-project.yml`. The relative order of items within each list is preserved, nested lists are treated the same way, and no automatic deduplication is performed. +- **Lists** (indexed arrays): for each list-valued key, the list from `.config/shopware-project.local.yml` is appended to the end of the list from `.config/shopware-project.yml`. The relative order of items within each list is preserved, nested lists are treated the same way, and no automatic deduplication is performed. ```yaml -# .shopware-project.local.yml +# .config/shopware-project.local.yml deployment: hooks: pre: | @@ -275,14 +275,14 @@ deployment: The local config file supports custom YAML tags to control how values are merged. These tags (such as `!reset` and `!override`) are interpreted by the Deployment Helper itself and are not part of the YAML standard. -> Note: Generic YAML parsers or linters that are not configured to allow custom tags may emit errors or warnings when loading `.shopware-project.local.yml`. Ensure your tooling supports custom tags or excludes this file, and use a Deployment Helper version that documents support for `!reset` and `!override` (see the Deployment Helper changelog for the minimum supported version). +> Note: Generic YAML parsers or linters that are not configured to allow custom tags may emit errors or warnings when loading `.config/shopware-project.local.yml`. Ensure your tooling supports custom tags or excludes this file, and use a Deployment Helper version that documents support for `!reset` and `!override` (see the Deployment Helper changelog for the minimum supported version). #### `!reset`: clear and replace a field Use `!reset` on a single field to ignore the value from the base configuration and use only the tagged value. It can be applied to scalars, lists, or maps, and it affects only that one field: the parent object is still merged as usual, but the value for this key is completely replaced. For lists, all inherited items are dropped; for maps, only the keys you define remain for that field. ```yaml -# .shopware-project.local.yml +# .config/shopware-project.local.yml deployment: extension-management: # Resets just this exclude field: the base exclude list is discarded and replaced @@ -300,7 +300,7 @@ deployment: Use `!override` on a mapping/section to disable deep-merging for that whole mapping. The tagged section completely replaces the corresponding section from the base configuration: nested keys are not merged recursively, and any keys that are not listed in the overriding section are removed. ```yaml -# .shopware-project.local.yml +# .config/shopware-project.local.yml deployment: # Overrides the entire hooks section: all hooks from the base config are removed hooks: !override diff --git a/guides/hosting/installation-updates/deployments/deployment-helper/environment.md b/guides/hosting/installation-updates/deployments/deployment-helper/environment.md index 1d8aa65efe..be18f65b78 100644 --- a/guides/hosting/installation-updates/deployments/deployment-helper/environment.md +++ b/guides/hosting/installation-updates/deployments/deployment-helper/environment.md @@ -79,12 +79,12 @@ See [SSL/TLS Setup](../../../infrastructure/database.md#ssltls-connection) for c ### Deployment control -| Variable | Values | Purpose | -| ------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------- | -| `SHOPWARE_DEPLOYMENT_TIMEOUT` | Seconds (default: `300`) | Max time a single deployment step can run; set to `null` to disable | -| `SHOPWARE_DEPLOYMENT_FORCE_REINSTALL` | `1` or unset | Set to `1` to force fresh install with `--drop-database` (destroys existing data!) | -| `SHOPWARE_DEPLOYMENT_STAGING` | `1` or unset | Set to `1` to enable staging mode on every deployment | -| `SHOPWARE_PROJECT_CONFIG_FILE` | File path | Custom path to `.shopware-project.yml` (absolute or relative to project root) | +| Variable | Values | Purpose | +| ------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------ | +| `SHOPWARE_DEPLOYMENT_TIMEOUT` | Seconds (default: `300`) | Max time a single deployment step can run; set to `null` to disable | +| `SHOPWARE_DEPLOYMENT_FORCE_REINSTALL` | `1` or unset | Set to `1` to force fresh install with `--drop-database` (destroys existing data!) | +| `SHOPWARE_DEPLOYMENT_STAGING` | `1` or unset | Set to `1` to enable staging mode on every deployment | +| `SHOPWARE_PROJECT_CONFIG_FILE` | File path | Custom path to `.config/shopware-project.yml` (absolute or relative to project root) | ### Store authentication diff --git a/guides/hosting/installation-updates/deployments/deployment-helper/extensions.md b/guides/hosting/installation-updates/deployments/deployment-helper/extensions.md index 292a2a6d07..74539cb143 100644 --- a/guides/hosting/installation-updates/deployments/deployment-helper/extensions.md +++ b/guides/hosting/installation-updates/deployments/deployment-helper/extensions.md @@ -110,7 +110,7 @@ See [Extension Management](../../extension-management.md) for details on install ### Option 2: Disable the Deployment Helper's extension management -If you prefer to manage extensions manually through the Store or Administration, disable the extension management in your `.shopware-project.yml`: +If you prefer to manage extensions manually through the Store or Administration, disable the extension management in your `.config/shopware-project.yml`: ```yaml deployment: @@ -139,7 +139,7 @@ Shopware Plugin Service Removing an extension requires you to follow two steps: -First, set the extension to `remove` in the `.shopware-project.yml` file: +First, set the extension to `remove` in the `.config/shopware-project.yml` file: ```yaml deployment: @@ -157,7 +157,7 @@ deployment: and deploy the changes. The extension will be uninstalled and is inactive. -Secondly, remove the extension from source code, remove the entry from the `.shopware-project.yml` file, and deploy the changes again. +Secondly, remove the extension from source code, remove the entry from the `.config/shopware-project.yml` file, and deploy the changes again. ## How Deployment Helper adapts to different Shopware versions diff --git a/guides/hosting/installation-updates/deployments/deployment-helper/hosting.md b/guides/hosting/installation-updates/deployments/deployment-helper/hosting.md index 98bc8a363a..e0b7e75a35 100644 --- a/guides/hosting/installation-updates/deployments/deployment-helper/hosting.md +++ b/guides/hosting/installation-updates/deployments/deployment-helper/hosting.md @@ -20,11 +20,11 @@ No additional configuration is required; the helper detects Platform.sh from the ## PaaS Native -PaaS Native environments invoke Deployment Helper during the deploy step of your CI/CD pipeline. Simply configure your `.shopware-project.yml` as usual and DH will execute with the same flow as Platform.sh or manual deployments. +PaaS Native environments invoke Deployment Helper during the deploy step of your CI/CD pipeline. Simply configure your `.config/shopware-project.yml` as usual and DH will execute with the same flow as Platform.sh or manual deployments. ## Kubernetes / Operators -When using [Shopware's Kubernetes operator](https://github.com/shopware/shopware-operator), deployment is triggered via a one-time job that invokes Deployment Helper. The operator does not run DH directly; it spawns it as a pod job. Configure your `.shopware-project.yml` and Deployment Helper will behave as normal. +When using [Shopware's Kubernetes operator](https://github.com/shopware/shopware-operator), deployment is triggered via a one-time job that invokes Deployment Helper. The operator does not run DH directly; it spawns it as a pod job. Configure your `.config/shopware-project.yml` and Deployment Helper will behave as normal. ## Fastly integration diff --git a/guides/hosting/installation-updates/deployments/deployment-helper/reference.md b/guides/hosting/installation-updates/deployments/deployment-helper/reference.md index 968054dfb0..ca9bf3e9cf 100644 --- a/guides/hosting/installation-updates/deployments/deployment-helper/reference.md +++ b/guides/hosting/installation-updates/deployments/deployment-helper/reference.md @@ -60,7 +60,7 @@ The `run` command accepts the following options: | `--skip-assets-install` | Skip asset installation (use when assets were already copied in CI/CD) | | `--skip-asset-install` | Deprecated alias for `--skip-assets-install` | | `--timeout=` | Set script execution timeout in seconds. Set to `null` to disable. Takes precedence over `SHOPWARE_DEPLOYMENT_TIMEOUT`, which in turn defaults to `300` (see [`RunCommand`](https://github.com/shopware/deployment-helper/blob/main/src/Command/RunCommand.php)). | -| `--project-config=` | Path to a custom `.shopware-project.yml` file (absolute or relative to project root) | +| `--project-config=` | Path to a custom `.config/shopware-project.yml` file (absolute or relative to project root) | `run` returns a non-zero exit code if any step fails. In CI/CD, treat a non-zero exit as a failed deployment and stop the rollout. @@ -68,10 +68,10 @@ The `run` command accepts the following options: ### One config file, environment variables for differences -Use a single `.shopware-project.yml` for all environments (production, staging, dev). Override environment-specific settings via environment variables in your CI/CD: +Use a single `.config/shopware-project.yml` for all environments (production, staging, dev). Override environment-specific settings via environment variables in your CI/CD: ```yaml -# .shopware-project.yml (committed) +# .config/shopware-project.yml (committed) deployment: store: license-domain: 'example.com' @@ -130,7 +130,7 @@ Only enable `always_clear` if you have a specific reason (e.g., custom caching l ### One-time tasks are version-control, not manual ops -Include one-time tasks in your `.shopware-project.yml` and commit them to Git. This way: +Include one-time tasks in your `.config/shopware-project.yml` and commit them to Git. This way: - Developers see what migrations exist in the codebase. - The task runs automatically on production with no manual steps. diff --git a/guides/hosting/installation-updates/deployments/deployment-helper/staging.md b/guides/hosting/installation-updates/deployments/deployment-helper/staging.md index 71aa58b7f9..7181528fc7 100644 --- a/guides/hosting/installation-updates/deployments/deployment-helper/staging.md +++ b/guides/hosting/installation-updates/deployments/deployment-helper/staging.md @@ -9,7 +9,7 @@ nav: In a staging environment, you usually want Shopware's staging mode to be re-applied every time the database is refreshed from production, so that emails remain disabled, app connections are reset, URLs are rewritten, and so on. The Deployment Helper can do this for you automatically. -Enable it either in `.shopware-project.yml`: +Enable it either in `.config/shopware-project.yml`: ```yaml deployment: @@ -17,7 +17,7 @@ deployment: enabled: true ``` -Or, via the environment variable `SHOPWARE_DEPLOYMENT_STAGING=1`. The latter is convenient when the same `.shopware-project.yml` is shared between production and staging. Set the env variable only on the staging environment. +Or, via the environment variable `SHOPWARE_DEPLOYMENT_STAGING=1`. The latter is convenient when the same `.config/shopware-project.yml` is shared between production and staging. Set the env variable only on the staging environment. When enabled, the Deployment Helper runs `system:setup:staging --no-interaction --force` as a `PostDeploy` event listener after extensions have been managed, for both the installation and update flows. To configure what staging mode actually changes (banners, URL rewriting, email delivery, ElasticSearch checks, etc.), see [Creating a Staging Instance](../../creating-a-staging-instance.md#configuring-staging-mode). @@ -51,7 +51,7 @@ This has caused real data leaks in the past. Always enable or run staging mode a Shopware does not automatically detect whether an instance is staging or production. The system runs in whatever mode is configured. You must explicitly enable staging mode via: - Environment variable: `SHOPWARE_DEPLOYMENT_STAGING=1` -- Or configuration: `deployment.staging.enabled: true` in `.shopware-project.yml` +- Or configuration: `deployment.staging.enabled: true` in `.config/shopware-project.yml` - Or manual command: `bin/console system:setup:staging` If you skip this step after copying production data, the instance behaves like production (real email, real app connections, production URLs). There is no automatic safeguard. diff --git a/guides/hosting/installation-updates/deployments/deployment-helper/store.md b/guides/hosting/installation-updates/deployments/deployment-helper/store.md index 9e1597c5b2..28c241355f 100644 --- a/guides/hosting/installation-updates/deployments/deployment-helper/store.md +++ b/guides/hosting/installation-updates/deployments/deployment-helper/store.md @@ -44,7 +44,7 @@ export SHOPWARE_STORE_SHOP_SECRET=your-shop-secret export SHOPWARE_STORE_LICENSE_DOMAIN=example.com ``` -In `.shopware-project.yml`, you can hardcode the license domain (it's not secret): +In `.config/shopware-project.yml`, you can hardcode the license domain (it's not secret): ```yaml deployment: diff --git a/guides/hosting/installation-updates/deployments/deployment-helper/troubleshooting.md b/guides/hosting/installation-updates/deployments/deployment-helper/troubleshooting.md index 03d45c018e..c55c2423dd 100644 --- a/guides/hosting/installation-updates/deployments/deployment-helper/troubleshooting.md +++ b/guides/hosting/installation-updates/deployments/deployment-helper/troubleshooting.md @@ -100,14 +100,14 @@ See [One-time task timeout](one-time-tasks.md#one-time-task-timeout) for details ## A config setting seems to have no effect -Deployment Helper provides a configuration schema for `.shopware-project.yml`. Use it in your editor to validate the file while editing, so misspelled or misplaced keys are reported before deployment. +Deployment Helper provides a configuration schema for `.config/shopware-project.yml`. Use it in your editor to validate the file while editing, so misspelled or misplaced keys are reported before deployment. Check if: - Your editor is using the schema and does not report any validation errors. - The key is nested under the correct section, for example `deployment:`. - You are editing the file the helper actually loads. If `SHOPWARE_PROJECT_CONFIG_FILE` or `--project-config` is set, that file wins over the auto-discovered one. -- A `.shopware-project.local.yml` is overriding your value. Local files merge on top of the base file. See [Local configuration overrides](configuration.md#local-configuration-overrides). +- A `.config/shopware-project.local.yml` is overriding your value. Local files merge on top of the base file. See [Local configuration overrides](configuration.md#local-configuration-overrides). ## Extensions aren't being installed or updated as expected @@ -144,7 +144,7 @@ If you skipped the staging mode setup, your staging instance is running in produ # Or, automatically on every deployment, set: export SHOPWARE_DEPLOYMENT_STAGING=1 - # .shopware-project.yml + # .config/shopware-project.yml deployment: staging: enabled: true diff --git a/guides/hosting/installation-updates/extension-management.md b/guides/hosting/installation-updates/extension-management.md index 28af1df130..4b6e0517c3 100644 --- a/guides/hosting/installation-updates/extension-management.md +++ b/guides/hosting/installation-updates/extension-management.md @@ -116,6 +116,6 @@ Next, clear the cache once. After doing this, the Extension Manager in the Admin Once your extensions are installed via Composer, the [Deployment Helper](deployments/deployment-helper/index.md) automatically manages them during deployments: installing new extensions, updating outdated ones, activating/deactivating as configured, and removing unwanted extensions. -This eliminates the need for manual extension management steps in your deployment pipeline. The Deployment Helper reads your `.shopware-project.yml` configuration and ensures the deployed environment's extension state matches your codebase automatically. +This eliminates the need for manual extension management steps in your deployment pipeline. The Deployment Helper reads your `.config/shopware-project.yml` configuration and ensures the deployed environment's extension state matches your codebase automatically. See [Deployment Helper: Extensions and Apps](deployments/deployment-helper/extensions.md) for configuration options. diff --git a/guides/plugins/plugins/bundle.md b/guides/plugins/plugins/bundle.md index 77b648b739..18d3eb5a3b 100644 --- a/guides/plugins/plugins/bundle.md +++ b/guides/plugins/plugins/bundle.md @@ -46,6 +46,8 @@ How a typical Shopware 6 project structure looks when bundles are used: ```text project-root/ +├── .config/ +│ └── shopware-project.yml ├── bin/ │ └── console ├── config/ @@ -76,7 +78,6 @@ project-root/ ├── vendor/ ├── composer.json ├── composer.lock -└── .shopware-project.yaml ``` The bundle is typically placed in a project's `src/` folder, which is the standard location for custom code. You will still need to register the bundle in the project's `config/bundles.php` file. @@ -176,7 +177,7 @@ Since bundles don't have a lifecycle, migrations aren't automatically executed. bin/console database:migrate --all ``` -If you use [Deployment Helper](../../hosting/installation-updates/deployments/deployment-helper/index.md), you can add it to the `.shopware-project.yaml` file: +If you use [Deployment Helper](../../hosting/installation-updates/deployments/deployment-helper/index.md), you can add it to the `.config/shopware-project.yml` file: ```yaml deployment: diff --git a/products/paas/shopware/get-started/prepare-codebase.md b/products/paas/shopware/get-started/prepare-codebase.md index 66197bbb67..b94bfc14cc 100644 --- a/products/paas/shopware/get-started/prepare-codebase.md +++ b/products/paas/shopware/get-started/prepare-codebase.md @@ -24,7 +24,7 @@ To uninstall plugins in the PaaS environment, use the [Deployment Helper](../../ The uninstallation process involves two steps: -1. **Set the extension to remove**: Configure the extension state as `remove` in your `.shopware-project.yml` file and deploy the changes to uninstall the extension. +1. **Set the extension to remove**: Configure the extension state as `remove` in your `.config/shopware-project.yml` file and deploy the changes to uninstall the extension. 2. **Remove from source code**: After the deployment, remove the extension from your source code and deploy again. diff --git a/products/tools/cli/configuration.md b/products/tools/cli/configuration.md new file mode 100644 index 0000000000..ddb81cea31 --- /dev/null +++ b/products/tools/cli/configuration.md @@ -0,0 +1,39 @@ +--- +nav: + title: Configuration files + position: 4 + +--- + +# Configuration files + +Shopware CLI uses separate configuration files for projects and extensions. The preferred location for both is the `.config/` directory next to the checkout they describe: + +```text +.config/shopware-project.yml +.config/shopware-extension.yml +``` + +## Lookup priority + +When no explicit project-config path is supplied, Shopware CLI looks for project configuration in this order: + +1. `.config/shopware-project.yml` +2. `.shopware-project.yaml` +3. `.shopware-project.yml` + +For extension configuration, it looks relative to the extension directory in this order: + +1. `.config/shopware-extension.yml` +2. `.shopware-extension.yml` +3. `.shopware-extension.yaml` + +The root-level files are legacy locations and remain supported. If both the preferred and a legacy file exist, the preferred file wins and Shopware CLI warns that the legacy file is ignored for that run. + +The `--project-config ` option always takes precedence over project-config discovery. Extension configuration has no equivalent option. + +Project configuration also supports a local override. Its path is derived from the resolved base file: the preferred file uses `.config/shopware-project.local.yml`; a legacy base file keeps its corresponding root-level local override. The local override is deep-merged and should not be committed. + +New configuration files created by `project config init`, `project create`, the development-environment TUI, or `extension config init` are written to the preferred `.config/` paths. Existing files are updated in their resolved location. + +For migration instructions, see the [Shopware CLI project-config ADR](https://github.com/shopware/shopware-cli/blob/main/docs/adr/0002-project-config-dot-config.md#migration). diff --git a/products/tools/cli/extension-commands/build.md b/products/tools/cli/extension-commands/build.md index 64a4b816bd..d0992371d1 100644 --- a/products/tools/cli/extension-commands/build.md +++ b/products/tools/cli/extension-commands/build.md @@ -17,10 +17,10 @@ Shopware CLI allows you to easily build the assets of an extension. To build an shopware-cli extension build ``` -Shopware CLI reads the `shopware/core` requirement from `composer.json` or `manifest.xml` and builds the assets using the lowest compatible Shopware version. This ensures the extension remains usable across multiple Shopware versions. If the selected version is incorrect, you can override it using a `.shopware-extension.yml` file. +Shopware CLI reads the `shopware/core` requirement from `composer.json` or `manifest.xml` and builds the assets using the lowest compatible Shopware version. This ensures the extension remains usable across multiple Shopware versions. If the selected version is incorrect, you can override it using a `.config/shopware-extension.yml` file. See the [Shopware CLI configuration file lookup priority](../configuration.md) for the preferred path and legacy fallbacks. ```yaml -# .shopware-extension.yml +# .config/shopware-extension.yml build: shopwareVersionConstraint: '6.6.9.0' ``` @@ -32,7 +32,7 @@ This only affects the build process and not on the installation of the extension If your plugin consists of multiple bundles, usually when you have implemented `getAdditionalBundles` in your `Plugin` class, you have to provide the path to the bundle you want to build in the config: ```yaml -# .shopware-extension.yml +# .config/shopware-extension.yml build: extraBundles: # Assumes the bundle name is the same as the directory name @@ -68,7 +68,7 @@ Building with esbuild works completely standalone without the Shopware codebase. An esbuild bundle can be used for JavaScript bundling, offering a significantly faster alternative to the standard Shopware bundling process, as it eliminates the need to involve Shopware for asset building. ```yaml -# .shopware-extension.yml +# .config/shopware-extension.yml build: zip: assets: @@ -107,7 +107,7 @@ Before Shopware 6.5, bundling the Composer dependencies into the ZIP file is req To disable this behavior, you can adjust the configuration: ```yaml -# .shopware-extension.yml +# .config/shopware-extension.yml build: zip: composer: @@ -121,7 +121,7 @@ This is automatically disabled for plugins targeting Shopware 6.5 and above and Shopware CLI deletes a lot of known files before packaging the extension into a ZIP file. If you want to delete more files, you can adjust the configuration: ```yaml -# .shopware-extension.yml +# .config/shopware-extension.yml build: zip: pack: @@ -135,7 +135,7 @@ build: If you bring additional NPM packages, make sure that you added only runtime dependencies to `dependencies` inside `package.json` and tooling to `devDependencies` and enabled `npm_strict` in the configuration: ```yaml -# .shopware-extension.yml +# .config/shopware-extension.yml build: zip: assets: @@ -148,10 +148,10 @@ This skips unnecessary `npm install` and `npm ci` commands and only installs the When creating an archive using `shopware-cli extension package`, a `checksum.json` file is automatically generated. This file contains checksums for all files in the extension, which can be used to verify the integrity of the extension after installation. -If you want to exclude certain files or paths from the checksum calculation, you can configure this in your `.shopware-extension.yml` file: +If you want to exclude certain files or paths from the checksum calculation, you can configure this in your `.config/shopware-extension.yml` file: ```yaml -# .shopware-extension.yml +# .config/shopware-extension.yml build: zip: checksum: @@ -163,7 +163,7 @@ build: For example, to exclude the `src/Resources/config/services.php` file from checksum calculation: ```yaml -# .shopware-extension.yml +# .config/shopware-extension.yml build: zip: checksum: @@ -191,7 +191,7 @@ This is important when distributing extensions because developers often commit c The changelog generation can be enabled with the configuration: ```yaml -# .shopware-extension.yml +# .config/shopware-extension.yml changelog: enabled: true ``` diff --git a/products/tools/cli/extension-commands/configuration.md b/products/tools/cli/extension-commands/configuration.md index c90149eb5f..360d3ea9a9 100644 --- a/products/tools/cli/extension-commands/configuration.md +++ b/products/tools/cli/extension-commands/configuration.md @@ -7,9 +7,9 @@ nav: # Configuration -Many configurations can be changed using a `.shopware-extension.yml` file in the root of your extension. +Many configurations can be changed using a `.config/shopware-extension.yml` file in the root of your extension. See the [Shopware CLI configuration file lookup priority](../configuration.md) for the preferred path and legacy fallbacks. -Here is an example of a `.shopware-extension.yml` file: +Here is an example of a `.config/shopware-extension.yml` file: ```yaml compatibility_date: '2026-02-11' @@ -50,7 +50,7 @@ To programmatically access the configuration schema, use `shopware-cli extension ## Compatibility date -You can define a `compatibility_date` in `.shopware-extension.yml`: +You can define a `compatibility_date` in `.config/shopware-extension.yml`: ```yaml compatibility_date: '2026-02-11' diff --git a/products/tools/cli/extension-commands/extract-meta-data.md b/products/tools/cli/extension-commands/extract-meta-data.md index 09d78966e4..f8c0ef9d3f 100644 --- a/products/tools/cli/extension-commands/extract-meta-data.md +++ b/products/tools/cli/extension-commands/extract-meta-data.md @@ -43,10 +43,10 @@ It will output always the English changelog. ## Configuration schema -To view the JSON schema for the `.shopware-extension.yml` configuration file, you can use: +To view the JSON schema for the `.config/shopware-extension.yml` configuration file, you can use: ```bash shopware-cli extension config-schema ``` -This outputs the JSON schema that describes all available configuration options in `.shopware-extension.yml`. This is particularly useful for AI agents and automation tools that need to understand the extension configuration structure. +This outputs the JSON schema that describes all available configuration options in `.config/shopware-extension.yml`. This is particularly useful for AI agents and automation tools that need to understand the extension configuration structure. diff --git a/products/tools/cli/project-commands/build.md b/products/tools/cli/project-commands/build.md index 7b50d92637..622971db3d 100644 --- a/products/tools/cli/project-commands/build.md +++ b/products/tools/cli/project-commands/build.md @@ -56,11 +56,11 @@ For more information, see the [Composer authentication documentation](https://ge ## Build configuration -Configure the build in `.shopware-project.yml`. The following sections cover commonly used build settings. +Configure the build in `.config/shopware-project.yml`. The following sections cover commonly used build settings. ### Reducing JavaScript in the Storefront -Shopware's default Browserslist configuration supports a broad range of browsers. To reduce JavaScript polyfills and CSS prefixes, set a narrower `browserslist` query in `.shopware-project.yml`: +Shopware's default Browserslist configuration supports a broad range of browsers. To reduce JavaScript polyfills and CSS prefixes, set a narrower `browserslist` query in `.config/shopware-project.yml`: ```yaml build: @@ -82,7 +82,7 @@ By default, FroshPlatformTemplateMail compiles MJML templates at runtime when em #### Configuration -Enable MJML compilation in `.shopware-project.yml`: +Enable MJML compilation in `.config/shopware-project.yml`: ```yaml build: @@ -123,7 +123,7 @@ Build hooks let you run custom shell commands at specific stages of the CI build #### Configuration -Define hooks in `.shopware-project.yml`: +Define hooks in `.config/shopware-project.yml`: ```yaml build: @@ -156,7 +156,7 @@ Hooks also inherit environment variables from the parent process, so CI/CD varia ### Compatibility date -You can define a `compatibility_date` in `.shopware-project.yml`: +You can define a `compatibility_date` in `.config/shopware-project.yml`: ```yaml compatibility_date: '2026-02-11' @@ -172,11 +172,11 @@ The `compatibility_date` lets Shopware CLI introduce behavior changes without ch Shopware CLI automatically detects plugins and apps. Custom bundles (classes that extend Shopware's bundle class) cannot be detected automatically because Shopware CLI does not execute PHP code. -Declare custom bundles in `.shopware-project.yml`. The older `extra.shopware-bundles` configuration in the project's `composer.json` is deprecated but remains supported for compatibility. +Declare custom bundles in `.config/shopware-project.yml`. The older `extra.shopware-bundles` configuration in the project's `composer.json` is deprecated but remains supported for compatibility. -#### Declaring bundles in `.shopware-project.yml` +#### Declaring bundles in `.config/shopware-project.yml` -The recommended approach is to declare bundles in the `build` section of `.shopware-project.yml`: +The recommended approach is to declare bundles in the `build` section of `.config/shopware-project.yml`: ```yaml build: @@ -191,7 +191,7 @@ The `path` is relative to the project root. The `name` field is optional; when o #### Legacy `composer.json` configuration ::: warning -Declaring bundles through `extra.shopware-bundles` in `composer.json` is deprecated. Existing configurations continue to work, but Shopware CLI emits a deprecation warning when they are loaded. Migrate bundle declarations to `build.bundles` in `.shopware-project.yml`. +Declaring bundles through `extra.shopware-bundles` in `composer.json` is deprecated. Existing configurations continue to work, but Shopware CLI emits a deprecation warning when they are loaded. Migrate bundle declarations to `build.bundles` in `.config/shopware-project.yml`. ::: A legacy bundle declaration in `composer.json` looks like this: diff --git a/products/tools/cli/project-commands/dev-environment.md b/products/tools/cli/project-commands/dev-environment.md index 6d6c9bdf04..35f34aa800 100644 --- a/products/tools/cli/project-commands/dev-environment.md +++ b/products/tools/cli/project-commands/dev-environment.md @@ -35,7 +35,7 @@ shopware-cli project dev install \ --admin-username admin --admin-password mysecret123 ``` -Starts the development environment (if not already running), runs the deployment helper to install Shopware, and saves the admin credentials to `.shopware-project.yml`. Intended for CI, scripts, and agents as a non-interactive counterpart to the TUI's install wizard. If the shop is already installed, the command prints a notice and exits successfully. +Starts the development environment (if not already running), runs the deployment helper to install Shopware, and saves the admin credentials to `.config/shopware-project.yml`. Intended for CI, scripts, and agents as a non-interactive counterpart to the TUI's install wizard. If the shop is already installed, the command prints a notice and exits successfully. Available flags: @@ -73,10 +73,10 @@ shopware-cli project logs --lines 50 ## Configuration -The environment is configured in `.shopware-project.yml`. See the [full configuration reference](../../../../guides/development/dev-environment.md#configuration-reference) for all options. +The environment is configured in `.config/shopware-project.yml`. See the [full configuration reference](../../../../guides/development/dev-environment.md#configuration-reference) for all options. ```yaml -# .shopware-project.yml +# .config/shopware-project.yml compatibility_date: '2026-03-01' docker: diff --git a/products/tools/cli/project-commands/helper-commands.md b/products/tools/cli/project-commands/helper-commands.md index 45c5c9f47d..14ad1cd8b4 100644 --- a/products/tools/cli/project-commands/helper-commands.md +++ b/products/tools/cli/project-commands/helper-commands.md @@ -117,7 +117,7 @@ It is just a shortcut for `bin/console cache:clear` without having to be in the shopware-cli project clear-cache ``` -If an API connection is configured in the `.shopware-project.yml`, it will clear the remote instance cache. +If an API connection is configured in the `.config/shopware-project.yml`, it will clear the remote instance cache. See the [Shopware CLI configuration file lookup priority](../configuration.md) for the preferred path and legacy fallbacks. ## Console @@ -213,17 +213,17 @@ This is useful when you encounter problems with your setup and need to understan ## Project configuration schema -To view the JSON schema for the `.shopware-project.yml` configuration file: +To view the JSON schema for the `.config/shopware-project.yml` configuration file: ```bash shopware-cli project config-schema ``` -This outputs the JSON schema describing all available configuration options in `.shopware-project.yml`. Useful for automation and understanding the project configuration structure. +This outputs the JSON schema describing all available configuration options in `.config/shopware-project.yml`. Useful for automation and understanding the project configuration structure. ## Initialize project configuration -To create a new `.shopware-project.yml` configuration file interactively: +To create a new `.config/shopware-project.yml` configuration file interactively: ```bash shopware-cli project config init diff --git a/products/tools/cli/project-commands/image-proxy.md b/products/tools/cli/project-commands/image-proxy.md index de36e0fd66..063cc1fce0 100644 --- a/products/tools/cli/project-commands/image-proxy.md +++ b/products/tools/cli/project-commands/image-proxy.md @@ -20,7 +20,7 @@ This lets you develop with production-like data and images without needing to do ## Usage ```bash -# Start the proxy server using configuration from .shopware-project.yml +# Start the proxy server using configuration from .config/shopware-project.yml shopware-cli project image-proxy # Specify a custom upstream URL @@ -41,10 +41,10 @@ shopware-cli project image-proxy --skip-config ## Configuration -You can configure the upstream URL in your `.shopware-project.yml` file: +You can configure the upstream URL in your `.config/shopware-project.yml` file: ```yaml -# .shopware-project.yml +# .config/shopware-project.yml image_proxy: url: https://production.example.com ``` @@ -103,7 +103,7 @@ When developing locally but needing access to production media files: ```bash # Configure once echo "image_proxy: - url: https://production.example.com" >> .shopware-project.yml + url: https://production.example.com" >> .config/shopware-project.yml # Start proxy shopware-cli project image-proxy diff --git a/products/tools/cli/project-commands/mysql-dump.md b/products/tools/cli/project-commands/mysql-dump.md index af4238466b..43eb00bc2e 100644 --- a/products/tools/cli/project-commands/mysql-dump.md +++ b/products/tools/cli/project-commands/mysql-dump.md @@ -45,10 +45,10 @@ The following tables are anonymized: [Find the complete list here](https://github.com/shopware/shopware-cli/blob/main/internal/shop/config.go#L246) -It is possible to customize the anonymization process by using the `dump.rewrite` configuration in the `.shopware-project.yml` file. +It is possible to customize the anonymization process by using the `dump.rewrite` configuration in the `.config/shopware-project.yml` file. ```yaml -# .shopware-project.yml +# .config/shopware-project.yml dump: rewrite: : @@ -79,10 +79,10 @@ Some tables are not relevant for dumps, like log tables. To ignore some default - `version_commit_data` - `webhook_event_log` -To ignore additional tables, use the `dump.ignore` configuration in the `shopware-project.yml` file. +To ignore additional tables, use the `dump.ignore` configuration in the `.config/shopware-project.yml` file. ```yaml -# .shopware-project.yml +# .config/shopware-project.yml dump: nodata: - @@ -93,7 +93,7 @@ dump: It is also possible to completely ignore a table **not only the content**. ```yaml -# .shopware-project.yml +# .config/shopware-project.yml dump: ignore: - @@ -104,7 +104,7 @@ dump: It is possible to add a where clause to the export of a table. So only rows matching the where clause will be exported. ```yaml -# .shopware-project.yml +# .config/shopware-project.yml dump: where: : 'id > 5' @@ -120,10 +120,10 @@ shopware-cli project dump --limit order=100 Tables referencing the limited table via foreign keys (including transitively) are automatically filtered to contain only rows belonging to the kept rows. A second limit on a table that is already filtered this way is rejected. When the limited table references itself (for example, `product.parent_id`), the ancestors of the kept rows are also exported, so the dump remains importable. This requires the `CREATE` and `DROP` privileges, since the rows kept are frozen in staging tables. -The same behavior can be configured persistently in `.shopware-project.yml`: +The same behavior can be configured persistently in `.config/shopware-project.yml`: ```yaml -# .shopware-project.yml +# .config/shopware-project.yml dump: limit: : diff --git a/products/tools/cli/project-commands/remote-extension-management.md b/products/tools/cli/project-commands/remote-extension-management.md index 31f41441d8..325d481f2a 100644 --- a/products/tools/cli/project-commands/remote-extension-management.md +++ b/products/tools/cli/project-commands/remote-extension-management.md @@ -15,7 +15,7 @@ This is one of the most commonly used command families in Shopware CLI, especial 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/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). +To use the extension manager, you need a `.config/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**. @@ -23,7 +23,7 @@ Make sure you log in using your username and password to the CLI. The extension ## Targeting an environment -All commands in this family accept the global `-e`/`--env` flag to target a named environment from the `environments` section of `.shopware-project.yml` (see the [Environment executors](../../../../guides/development/dev-environment.md#environment-executors) reference). When set, the command uses that environment's `url` and `admin_api` credentials instead of the top-level configuration. An unknown environment name causes the command to fail instead of silently falling back to the default configuration. +All commands in this family accept the global `-e`/`--env` flag to target a named environment from the `environments` section of `.config/shopware-project.yml` (see the [Environment executors](../../../../guides/development/dev-environment.md#environment-executors) reference). When set, the command uses that environment's `url` and `admin_api` credentials instead of the top-level configuration. An unknown environment name causes the command to fail instead of silently falling back to the default configuration. ```bash shopware-cli project extension list -e staging diff --git a/products/tools/cli/shopware-account-commands/updating-store-page.md b/products/tools/cli/shopware-account-commands/updating-store-page.md index 5a30dc1597..032ba7427a 100644 --- a/products/tools/cli/shopware-account-commands/updating-store-page.md +++ b/products/tools/cli/shopware-account-commands/updating-store-page.md @@ -21,13 +21,13 @@ Start with the current Store page and update only the parts you want to change. shopware-cli account producer extension info pull ``` -This downloads all uploaded Store images and creates a `.shopware-extension.yml` file with the extension's Store metadata. +This downloads all uploaded Store images and creates a `.config/shopware-extension.yml` file with the extension's Store metadata. The file can be checked into version control and is automatically removed when you create a ZIP file using Shopware CLI. ## Managing Store metadata locally with Git -The `.shopware-extension.yml` file contains the extension's Store metadata, such as descriptions, tags, installation instructions, and image configuration. By checking this file into Git, you can: +The `.config/shopware-extension.yml` file contains the extension's Store metadata, such as descriptions, tags, installation instructions, and image configuration. By checking this file into Git, you can: - Track Store listing changes together with code changes. - Review and approve localized or marketing content through pull requests. @@ -41,12 +41,12 @@ This workflow is especially useful when you maintain several extensions or local Store listing updates and extension package uploads are separate actions. A typical version-controlled workflow is: 1. Pull the current Store metadata with `extension info pull` when you first adopt the workflow. -2. Edit `.shopware-extension.yml` and the referenced images in the extension repository. +2. Edit `.config/shopware-extension.yml` and the referenced images in the extension repository. 3. Review the Store listing changes in Git like any other content change. 4. Push approved Store metadata with `extension info push`. 5. Validate and upload the release package using the [Store release workflow](./releasing-extension-to-shopware-store.md). -Because `.shopware-extension.yml` is not included in the extension ZIP created by Shopware CLI, keeping Store metadata in the repository does not add the listing configuration to the distributed package. +Because `.config/shopware-extension.yml` is not included in the extension ZIP created by Shopware CLI, keeping Store metadata in the repository does not add the listing configuration to the distributed package. ## Updating the Store page diff --git a/products/tools/cli/validation.md b/products/tools/cli/validation.md index 96f60bc443..78899e1343 100644 --- a/products/tools/cli/validation.md +++ b/products/tools/cli/validation.md @@ -78,7 +78,7 @@ Shopware CLI uses an embedded Go-based PHP linter. It does not download or execu The underlying linter supports PHP language profiles from PHP 7.2 through PHP 8.5, with PHP 8.6 available as a preview profile. Shopware CLI currently normalizes a derived PHP 7.2 profile to PHP 7.3 for linting. -By default, Shopware CLI derives the PHP language profile from the extension's Shopware version constraint. To select a specific profile instead, set `validation.php_version` in `.shopware-extension.yml`: +By default, Shopware CLI derives the PHP language profile from the extension's Shopware version constraint. To select a specific profile instead, set `validation.php_version` in `.config/shopware-extension.yml`. See the [Shopware CLI configuration file lookup priority](./configuration.md) for the preferred path and legacy fallbacks: ```yaml validation: @@ -277,7 +277,7 @@ Local or CI validation cannot replace the Store review completely. It does not i ## Validation ignores -To ignore selected errors or warnings for an extension, create a `.shopware-extension.yml` file in the extension root: +To ignore selected errors or warnings for an extension, create a `.config/shopware-extension.yml` file in the extension root: ```yaml validation: @@ -316,7 +316,7 @@ If you run Shopware CLI directly: shopware-cli project validate /path/to/your/project ``` -`project validate` gathers local extension source directories and configured bundles and runs the registered validation tools against them. Composer-managed extensions resolved under `vendor/` are skipped. Project-level validation settings are read from `.shopware-project.yml` under `validation`. +`project validate` gathers local extension source directories and configured bundles and runs the registered validation tools against them. Composer-managed extensions resolved under `vendor/` are skipped. Project-level validation settings are read from `.config/shopware-project.yml` under `validation`. :::warning `project validate` does not run extension metadata and packaging validation for every contained extension. The `sw-cli` verifier only runs with a single-extension context. Run `extension validate` for an individual extension when you also need its Composer or manifest metadata, icon, snippet, and package checks. @@ -351,7 +351,7 @@ validation: path: 'custom/plugins/MyPlugin/src/Example.php' ``` -You can also exclude extensions from project validation with `validation.ignore_extensions` in `.shopware-project.yml`. +You can also exclude extensions from project validation with `validation.ignore_extensions` in `.config/shopware-project.yml`. ### Detecting breaking changes before upgrading {#detecting-breaking-changes-before-upgrading} From d430a6e687100d2c565424db958b6d7422ff7721 Mon Sep 17 00:00:00 2001 From: Malte Janz Date: Thu, 17 Sep 2026 11:53:21 +0200 Subject: [PATCH 2/5] fix: clarify project configuration file paths in documentation Co-authored-by: Copilot Autofix powered by AI <175728472+Copilot@users.noreply.github.com> --- .../deployments/deployment-helper/environment.md | 2 +- .../deployments/deployment-helper/reference.md | 2 +- .../deployments/deployment-helper/troubleshooting.md | 2 +- 3 files changed, 3 insertions(+), 3 deletions(-) diff --git a/guides/hosting/installation-updates/deployments/deployment-helper/environment.md b/guides/hosting/installation-updates/deployments/deployment-helper/environment.md index be18f65b78..70a3e84035 100644 --- a/guides/hosting/installation-updates/deployments/deployment-helper/environment.md +++ b/guides/hosting/installation-updates/deployments/deployment-helper/environment.md @@ -84,7 +84,7 @@ See [SSL/TLS Setup](../../../infrastructure/database.md#ssltls-connection) for c | `SHOPWARE_DEPLOYMENT_TIMEOUT` | Seconds (default: `300`) | Max time a single deployment step can run; set to `null` to disable | | `SHOPWARE_DEPLOYMENT_FORCE_REINSTALL` | `1` or unset | Set to `1` to force fresh install with `--drop-database` (destroys existing data!) | | `SHOPWARE_DEPLOYMENT_STAGING` | `1` or unset | Set to `1` to enable staging mode on every deployment | -| `SHOPWARE_PROJECT_CONFIG_FILE` | File path | Custom path to `.config/shopware-project.yml` (absolute or relative to project root) | +| `SHOPWARE_PROJECT_CONFIG_FILE` | File path | Custom project configuration path (absolute or relative to project root) | ### Store authentication diff --git a/guides/hosting/installation-updates/deployments/deployment-helper/reference.md b/guides/hosting/installation-updates/deployments/deployment-helper/reference.md index ca9bf3e9cf..368350c163 100644 --- a/guides/hosting/installation-updates/deployments/deployment-helper/reference.md +++ b/guides/hosting/installation-updates/deployments/deployment-helper/reference.md @@ -60,7 +60,7 @@ The `run` command accepts the following options: | `--skip-assets-install` | Skip asset installation (use when assets were already copied in CI/CD) | | `--skip-asset-install` | Deprecated alias for `--skip-assets-install` | | `--timeout=` | Set script execution timeout in seconds. Set to `null` to disable. Takes precedence over `SHOPWARE_DEPLOYMENT_TIMEOUT`, which in turn defaults to `300` (see [`RunCommand`](https://github.com/shopware/deployment-helper/blob/main/src/Command/RunCommand.php)). | -| `--project-config=` | Path to a custom `.config/shopware-project.yml` file (absolute or relative to project root) | +| `--project-config=` | Path to a custom project configuration file (absolute or relative to project root) | `run` returns a non-zero exit code if any step fails. In CI/CD, treat a non-zero exit as a failed deployment and stop the rollout. diff --git a/guides/hosting/installation-updates/deployments/deployment-helper/troubleshooting.md b/guides/hosting/installation-updates/deployments/deployment-helper/troubleshooting.md index c55c2423dd..1a43cee5d5 100644 --- a/guides/hosting/installation-updates/deployments/deployment-helper/troubleshooting.md +++ b/guides/hosting/installation-updates/deployments/deployment-helper/troubleshooting.md @@ -107,7 +107,7 @@ Check if: - Your editor is using the schema and does not report any validation errors. - The key is nested under the correct section, for example `deployment:`. - You are editing the file the helper actually loads. If `SHOPWARE_PROJECT_CONFIG_FILE` or `--project-config` is set, that file wins over the auto-discovered one. -- A `.config/shopware-project.local.yml` is overriding your value. Local files merge on top of the base file. See [Local configuration overrides](configuration.md#local-configuration-overrides). +- The local override alongside the resolved project configuration (for example, `.config/shopware-project.local.yml`) is overriding your value. Local files merge on top of the base file. See [Local configuration overrides](configuration.md#local-configuration-overrides). ## Extensions aren't being installed or updated as expected From ffb7e3f478f5c04402edc07a810e8eead995edd6 Mon Sep 17 00:00:00 2001 From: Malte Janz Date: Thu, 17 Sep 2026 11:56:35 +0200 Subject: [PATCH 3/5] fix: remove appending to config shell script recommendation to be more careful --- products/tools/cli/project-commands/image-proxy.md | 8 +++----- 1 file changed, 3 insertions(+), 5 deletions(-) diff --git a/products/tools/cli/project-commands/image-proxy.md b/products/tools/cli/project-commands/image-proxy.md index 063cc1fce0..c722cf861c 100644 --- a/products/tools/cli/project-commands/image-proxy.md +++ b/products/tools/cli/project-commands/image-proxy.md @@ -41,10 +41,10 @@ shopware-cli project image-proxy --skip-config ## Configuration -You can configure the upstream URL in your `.config/shopware-project.yml` file: +Configure the upstream URL in the project configuration file resolved by Shopware CLI. See the [configuration file lookup priority](../configuration.md) before editing, especially if your project still uses a legacy root-level file. If no project configuration exists, run `shopware-cli project config init` first. ```yaml -# .config/shopware-project.yml +# Add this to the resolved project configuration file image_proxy: url: https://production.example.com ``` @@ -101,9 +101,7 @@ shopware: When developing locally but needing access to production media files: ```bash -# Configure once -echo "image_proxy: - url: https://production.example.com" >> .config/shopware-project.yml +# Add image_proxy.url to the resolved project configuration file (see above) # Start proxy shopware-cli project image-proxy From e6d0a4ced2892888af8279b89222c6e53269f2ba Mon Sep 17 00:00:00 2001 From: Malte Janz Date: Thu, 17 Sep 2026 11:58:57 +0200 Subject: [PATCH 4/5] fix: codestyle --- .../deployments/deployment-helper/environment.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/guides/hosting/installation-updates/deployments/deployment-helper/environment.md b/guides/hosting/installation-updates/deployments/deployment-helper/environment.md index 70a3e84035..662991307c 100644 --- a/guides/hosting/installation-updates/deployments/deployment-helper/environment.md +++ b/guides/hosting/installation-updates/deployments/deployment-helper/environment.md @@ -79,12 +79,12 @@ See [SSL/TLS Setup](../../../infrastructure/database.md#ssltls-connection) for c ### Deployment control -| Variable | Values | Purpose | -| ------------------------------------- | ------------------------ | ------------------------------------------------------------------------------------ | -| `SHOPWARE_DEPLOYMENT_TIMEOUT` | Seconds (default: `300`) | Max time a single deployment step can run; set to `null` to disable | -| `SHOPWARE_DEPLOYMENT_FORCE_REINSTALL` | `1` or unset | Set to `1` to force fresh install with `--drop-database` (destroys existing data!) | -| `SHOPWARE_DEPLOYMENT_STAGING` | `1` or unset | Set to `1` to enable staging mode on every deployment | -| `SHOPWARE_PROJECT_CONFIG_FILE` | File path | Custom project configuration path (absolute or relative to project root) | +| Variable | Values | Purpose | +| ------------------------------------- | ------------------------ | ---------------------------------------------------------------------------------- | +| `SHOPWARE_DEPLOYMENT_TIMEOUT` | Seconds (default: `300`) | Max time a single deployment step can run; set to `null` to disable | +| `SHOPWARE_DEPLOYMENT_FORCE_REINSTALL` | `1` or unset | Set to `1` to force fresh install with `--drop-database` (destroys existing data!) | +| `SHOPWARE_DEPLOYMENT_STAGING` | `1` or unset | Set to `1` to enable staging mode on every deployment | +| `SHOPWARE_PROJECT_CONFIG_FILE` | File path | Custom project configuration path (absolute or relative to project root) | ### Store authentication From 835dfb09709acf6c6fedc3644a27acc5c5526161 Mon Sep 17 00:00:00 2001 From: Malte Janz Date: Thu, 17 Sep 2026 13:58:39 +0200 Subject: [PATCH 5/5] fix: add why section for the configuration location change --- guides/development/dev-environment.md | 2 +- products/tools/cli/configuration.md | 8 ++++++-- 2 files changed, 7 insertions(+), 3 deletions(-) diff --git a/guides/development/dev-environment.md b/guides/development/dev-environment.md index f8451c91af..a5190f298c 100644 --- a/guides/development/dev-environment.md +++ b/guides/development/dev-environment.md @@ -118,7 +118,7 @@ After you confirm, the wizard: | `.config/shopware-project.yml` | Updated with `compatibility_date`, `environments`, and `docker` config | | `.config/shopware-project.local.yml` | Created if you chose a profiler with credentials (Blackfire, Tideways) | | `compose.yaml` | **Replaced** with the CLI-managed version - your old file is overwritten, so back it up first and move any customizations to `compose.override.yaml` | -| `Makefile` | **Not touched** - you can delete it once you've migrated, or keep it around | +| `Makefile` | **Not touched** - you can delete it once you've migrated | | `composer.json` | If `shopware/deployment-helper` isn't already present, it's added to `require` | ### After the wizard completes diff --git a/products/tools/cli/configuration.md b/products/tools/cli/configuration.md index ddb81cea31..903f52e75d 100644 --- a/products/tools/cli/configuration.md +++ b/products/tools/cli/configuration.md @@ -14,15 +14,19 @@ Shopware CLI uses separate configuration files for projects and extensions. The .config/shopware-extension.yml ``` +## Why `.config` + +The [`.config` convention](https://dot-config.github.io/) keeps project root directories uncluttered and provides a standard location that other tools can adopt. Shopware CLI and Deployment Helper are the first official Shopware tools to use it. + ## Lookup priority -When no explicit project-config path is supplied, Shopware CLI looks for project configuration in this order: +When no explicit project-config path is supplied, Shopware CLI and Deployment Helper look for project configuration in this order: 1. `.config/shopware-project.yml` 2. `.shopware-project.yaml` 3. `.shopware-project.yml` -For extension configuration, it looks relative to the extension directory in this order: +For extension configuration, the CLI looks relative to the extension directory in this order: 1. `.config/shopware-extension.yml` 2. `.shopware-extension.yml`